openliberty / guide-social-media-login

A guide on how to allow users to log in to your application with their social media accounts by using the Open Liberty Social Media Login feature.

Authenticating users through social media providers

Note	This repository contains the guide documentation source. To view the guide in published form, view it on the Open Liberty website.

You’ll explore how to allow users to log in to your application with their social media accounts by using the Open Liberty Social Media Login feature.

What you’ll learn

Social media login provides a form of single sign-on (SSO) that application users can use to sign in to a secured website with their existing social media account. Social media login simplifies the authentication process for users and allows you to provide a secure authentication method for your users without having to explicitly implement it.

The Social Media Login feature in Open Liberty provides configuration elements to configure application authentication by using one or more social media platforms, including GitHub, LinkedIn, Facebook, Twitter, and Google. You can also create a custom configuration for any other social media platform that implements the OAuth 2.0 standard or the OpenID Connect 1.0 standard for authorization.

The application that is provided with this guide is secured through basic authentication. The application includes a simple welcome page that includes a message and a Log in button. The welcome page is defined in the hello.html file, and the Log in button is defined in the button element of that page. When the application user clicks the Log in button, a dialog box opens requesting the user’s username and password for authenticating to the service. In this guide, you will replace the basic authentication dialog with a dialog to log in with a social media provider.

hello.html

link:finish/src/main/webapp/hello.html[role=include]

Additional prerequisites

Before you begin, you must have a GitHub account to complete this guide. Register for a GitHub account, if you don’t already have one.

https://raw.githubusercontent.com/OpenLiberty/guides-common/prod/gitclone.adoc

Creating a GitHub OAuth2 application

Obtain an OAuth 2.0 client ID and client secret credentials for accessing the GitHub API by registering a new application in your GitHub account. Register a new application on the Settings > Developer settings > OAuth Apps page of your account.

Set the Homepage URL to https://localhost:9443, and set the authorization callback URL to https://localhost:9443/ibm/api/social-login/redirect/githubLogin.

When the registration is complete, the client ID and client secret credentials are displayed. To provide your application with the credentials, export the GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET environment variables.

For more information about creating an OAuth application, see the GitHub documentation.

Replace the values of the [github-client-id] and [github-client-secret] fields in the following command: https://raw.githubusercontent.com/OpenLiberty/guides-common/prod/os-tabs.adoc

export GITHUB_CLIENT_ID=[github-client-id]
export GITHUB_CLIENT_SECRET=[github-client-secret]

set GITHUB_CLIENT_ID=[github-client-id]
set GITHUB_CLIENT_SECRET=[github-client-secret]

Building and running the application in dev mode

First, navigate to the start directory.

https://raw.githubusercontent.com/OpenLiberty/guides-common/prod/devmode-lmp33-start-cd.adoc

Configuring GitHub as a social media login provider

Enable the Social Media Login feature in the application by updating the Liberty server.xml configuration file.

Replace the Liberty server.xml configuration file.
src/main/liberty/config/server.xml

The socialLogin-1.0 feature definition enables the Social Media Login feature in the application so that you can use the githubLogin configuration element to configure GitHub as a social media login provider.

The client ID and client secret credentials for your GitHub OAuth2 application are injected into the githubLogin configuration element with values of github.client.id and github.client.secret. These values are supplied by the GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET environment variables.

For more information, see the githubLogin element documentation.

server.xml

link:finish/src/main/liberty/config/server.xml[role=include]

https://raw.githubusercontent.com/OpenLiberty/guides-common/prod/devmode-build.adoc

Check out the service that you created by going to the http://localhost:9080/api/hello.html URL.

Try logging in with your social media account. After you log in with your GitHub account, authorize access to your GitHub user data with the OAuth2 application that you created in the Creating a GitHub OAuth2 application section. After authentication, you’re redirected to the /hello endpoint that’s served by HelloServlet, which also serves the securedHello.jsp page.

The securedHello.jsp page contains a Log out button that makes a POST request to the /logout endpoint, which is served by LogoutServlet.

Because the logout feature isn’t fully implemented, an error is returned when you click the Log out button:

 Exception thrown by application class 'io.openliberty.guides.sociallogin.LogoutServlet.doPost:50'
java.lang.NullPointerException:
at io.openliberty.guides.sociallogin.LogoutServlet.doPost(LogoutServlet.java:50)
at javax.servlet.http.HttpServlet.service(HttpServlet.java:706)
at javax.servlet.http.HttpServlet.service(HttpServlet.java:791)
at com.ibm.ws.webcontainer.servlet.ServletWrapper.service(ServletWrapper.java:1230)
at [internal classes]

hello.html

link:finish/src/main/webapp/hello.html[role=include]

HelloServlet.java

link:finish/src/main/java/io/openliberty/guides/sociallogin/HelloServlet.java[role=include]

securedHello.jsp

link:finish/src/main/webapp/securedHello.jsp[role=include]

LogoutServlet.java

link:finish/src/main/java/io/openliberty/guides/sociallogin/LogoutServlet.java[role=include]

Implementing logout

The LogoutServlet provided in the start directory uses the logout() method in the HttpServletRequest class to log the user out of the application. After a user is logged out, the user is redirected to the hello.html page.

You are also provided with a LogoutHandler class and ILogout interface to add custom logout logic that revokes the application permissions from a user’s account.

The logoutHandler.getLogout() method gets an implementation of the ILogout interface for GitHub and uses the logout() method of that interface to revoke the OAuth2 permissions that are granted to the application by the user.

The response that’s returned by this logout() method is verified by the application, which checks whether it has a 2xx series status code.

The request.logout() method is then called to log the user out of the application.

The logoutHandler.getLogout() method returns the implementation of the ILogout interface based on the name of the social media provider that a user chooses. The social media provider’s name is retrieved by using the UserProfileManager class. The UserProfileManager class returns the ID of the social media login configuration. In this application, when the application user selects GitHub, the name of the social media provider is githubLogin.

Implement the ILogout interface to revoke permissions for the application from the user’s GitHub account.

Replace the GitHubLogout class.
src/main/java/io/openliberty/guides/sociallogin/logout/GitHubLogout.java

GitHub’s REST API provides a DELETE endpoint, which is stored in the unauthorizeUrl variable. The unauthorizeUrl variable is used to revoke application permissions from the user. The JAX-RS Client is used to send a request to this DELETE endpoint.

Your GitHub application client ID and client secret credentials are obtained from the github.client.id and github.client.secret configuration properties. These credentials are encoded and stored in the encodedAuth variable and added to the request as an Authorization header.

The GitHub access token for a user, which is stored in the accessToken variable, is retrieved from their user profile that is modelled by the UserProfile class. The UserProfile object can be retrieved with the UserProfileManager class. The access token is used in the DELETE request body, which is stored in the requestBody variable.

GitHubLogout.java

link:finish/src/main/java/io/openliberty/guides/sociallogin/logout/GitHubLogout.java[role=include]

LogoutHandler.java

link:finish/src/main/java/io/openliberty/guides/sociallogin/logout/LogoutHandler.java[role=include]

LogoutServlet.java

link:finish/src/main/java/io/openliberty/guides/sociallogin/LogoutServlet.java[role=include]

ILogout.java

link:finish/src/main/java/io/openliberty/guides/sociallogin/logout/ILogout.java[role=include]

Check out the service that you created by going to the http://localhost:9080/api/hello.html URL.

Try logging in with your GitHub account. After authenticating, you are redirected to the https://localhost:9080/api/hello URL. When you click the Log out button, you are unauthenticated and redirected back to the http://localhost:9080/api/hello.html URL.

If you try logging in again, you are asked to reauthorize your application with GitHub. Then, you’re authenticated and redirected to the https://localhost:9080/api/hello URL. While you stay logged in to GitHub, the application doesn’t prompt you to enter your GitHub credentials.

https://raw.githubusercontent.com/OpenLiberty/guides-common/prod/devmode-quit-ctrlc.adoc

Next steps

As an exercise, configure Facebook as a second social media provider for social media login for your application. If you add more than one social media login provider, a selection form is presented to the user. This form contains all of the social media providers that are configured in your application.

For information about setting up an OAuth2 application and revoking permissions, see the Facebook documentation:

• Registering for a Facebook application

• Adding Facebook Login to your Facebook application

• Revoking Facebook Login

Great work! You’re done!

You secured a web application in Open Liberty by using the Social Media Login feature.

Related Links

Learn more about MicroProfile.

View the MicroProfile specs

View the MicroProfile

https://raw.githubusercontent.com/OpenLiberty/guides-common/prod/attribution.adoc

guide-social-media-login's Issues

Peer Review - Windows

Dev content review for logout branch

• Configuring security and social media login
  • if not necessary, we do not ask readers to update file. Rewrite the content of whole section so that no extra update actions (just replace action at the beginning), and explain the detail
  • some hotspots are not right
• Running the application
  • ask readers to logout and relogin, they will see re-authenication
  • add instruction to stop dev mode
• remove "Testing the service" section
• Next Steps
  • "Next Steps" or "Next Step"
  • The statement for "Social Media Login feature documentation" may not need
  • Better rewrite the content to ask reader to try either provider and provide necessary information for different providers,
• pom.xml remove plugin versions, specify directly

Consider guide-social-media-login for repo name

This may be a better repo name and slug.

@k-rtik @gkwan-ibm Cc @lauracowen

Feedback from Jamie

When talking about external instructions maybe reference the sites docs on github as the instructions may change?

Do we not ask them to try out the application before we start?

You also need to authorise when connecting to github and this is not mentioned

in the HttpServletRequest. class to log the user out of the application after which the user is redirected to hello.html.
The above does not link to the class mentioned probably because of the space between the .class

Try logging in with your social media account. After authenticating, you will be redirected to https://localhost:9080/api/hello. When you click the logout button, you are unauthenticated and redirected back to http://localhost:9080/api/hello.html.
Mention that credentials are saved (In a cookie maybe?) as I did not have to type them back in the second time.

Peer Review - Linux

Functionality

• Check that the guide has working instructions and sample code
• Test the guide on 3 platforms: Mac, Win, Linux
• If any URL visits, try them on different browsers: Firefox, Chrome, Safari
• If any URL visits, try curl command where applicable

Formatting & Presentation

• Check the quality of code according to the best coding practices
  • Ensure that command substitutions use the $(cmd) format and not `cmd`
  • Ensure that the console output of the integrated tests do not include the [INFO] tab
• Check the quality and presentation of guide according to Structure and Style Guideline
• Check the consistency of guide with template and other guides
• Examples with the right outcomes are provided
• Example with the wrong outcomes, if any, are provided
• Check that all licensing statements are properly stated in all files
• Check that the pom.xml, server.xml, etc files are clean
• Check that the directories are properly structured
• Ensure that the guide is using the latest version of the liberty-maven-plugin or liberty-gradle-plugin where applicable
• Check that some of these page-tags are used in a guide: MicroProfile, Maven, Docker, Kubernetes, Gradle, Java EE, Security, Cloud. Only these tags are visible on the website. Latest list here.
• Check the attribution statement is accurate for the guide
• Verify the travisTest.sh script, if any, is accurate and consistent with other guides

Peer Testing: tests to be done by a peer member.

Guide’s contributor’s (if available, otherwise peer tester’s) responsibility:

• Additional tests where applicable:
  • Define test coverage and review with team (including guide contributor, if available)
  • Define detail test cases
  • Consider corner cases targeting the specific guide
  • Consider different platform tests, ie, Mac, Windows, Linux
  • Consider corner cases UI tests
  • Consider testing URL on all browsers, ie, FF, Chrome, Safari
  • Consider testing the curl command for URL visits
• Consider building with both Maven and Gradle build tools
• Testing with different IDEs, ie, Atom, Eclipse (Optional: VS.code, IntelliJ, Microclimate)
• Run Acrolinx Checker on draft (above 70 score approximately)
• Consider SEO title and description for the guides
• Ensure automated test is enable, set up with Travis CI, and able to schedule tests
• Run diff -r start/ finish/ and there's no differences
• Ensure that the automation tests are able to run when PR is created

Peer Tester’s responsibility:

• Check the appearance of the guide on test site for the following items:
  • Table of contents
  • Headings
  • Paragraphs
  • code snippets
  • outputs
  • links
  • hotspots
• Test the guide end-to-end with working instruction and sample code
• Perform all the defined test cases

User Review

Allow a person with a fresh mind to read the guide and execute the steps described in the guide, test whether each step is clear enough to understand, and no logic errors.

Review and walkthrough by a non-SME or a new user with a critical and fresh pair of eyes:

• Record the time it takes to go through the entire guide ~ 24 minutes
• Test each step in the guide is clear and easy to understand
• Ensure no logic errors
• Resolve anything that does not work
• Resolve anything usability issues (confusing or hard to follow)
• Achieve basic understanding/working knowledge of the topic in the guide

Peer Review - Linux

Functionality

• Check that the guide has working instructions and sample code
• If any URL visits, try them on different browsers: (Firefox, Safari)
• If any URL visits, try curl command where applicable (N/A)

Formatting & Presentation

README.adoc checks:

• Ensure that command substitutions use the $(cmd) format and not `cmd`
• Ensure that the console output of the integrated tests do not include the [INFO] tab
• Check the quality and presentation of guide according to Structure and Style Guideline
• Check that the pom.xml, server.xml, etc files are clean
  • Remove any dependencies and features that are not required
  • Ensure that the parent pom.xml files do not contain any dependencies, and all dependencies are specified in the children pom.xml files
• Examples with the right outcomes are provided (N/A)
• Example with the wrong outcomes, if any, are provided (N/A)

pom.xml checks (if files are present):

• Check that the file follows the template found here: https://github.com/OpenLiberty/draft-guides-template/blob/master/finish/pom.xml
• Check that the following dependencies are included in all of the pom.xml files:

<!-- Provided dependencies -->
<dependency>
  <groupId>jakarta.platform</groupId>
  <artifactId>jakarta.jakartaee-api</artifactId>
  <version>8.0.0</version>
  <scope>provided</scope>
</dependency>

<dependency>
  <groupId>org.eclipse.microprofile</groupId
  <artifactId>microprofile</artifactId>
  <version>3.3</version>
  <type>pom</type>
  <scope>provided</scope>
</dependency>

• Check that the versions of plugins are directly provided and not fed in by a file property.
  • Not formatted like so:

    <properties>
        <!-- Plugins -->
        <version.liberty-maven-plugin>3.2</version.liberty-maven-plugin>
    </properties>

    <!-- Liberty plugin -->
    <plugin>
        <groupId>io.openliberty.tools</groupId>
        <artifactId>liberty-maven-plugin</artifactId>
        <version>${version.liberty-maven-plugin}</version>
    </plugin>

• Should be formatted like so:

    <!-- Liberty plugin -->
    <plugin>
        <groupId>io.openliberty.tools</groupId>
        <artifactId>liberty-maven-plugin</artifactId>
        <version>3.2</version>
    </plugin>

• Check that there are 4 spaces per indent for proper formatting
• Ensure that the guide is using the latest version of the liberty-maven-plugin or liberty-gradle-plugin where applicable

Overall checks:

• Check the consistency of guide with the template and other guides
• Check the quality of code according to the best coding practices
• Check that all licensing statements are properly stated in all files, with the correct year (Should be present in all Java files + the index.html)
• Check that the directories are properly structured
• Check that some of these page-tags are used in a guide: MicroProfile, Maven, Docker, Kubernetes, Gradle, Java EE, Security, Cloud. Only these tags are visible on the website. Latest list here.
• Check the attribution statement is accurate for the guide
• Verify the travisTest.sh script, if any, is accurate and consistent with other guides

---

Guide’s contributor’s (if available, otherwise peer tester’s) responsibility:

• Additional tests where applicable:
  • Define test coverage and review with team (including guide contributor, if available)
  • Define detail test cases
  • Consider corner cases targeting the specific guide
  • Consider corner cases UI tests
  • Consider testing URL on all browsers, ie, FF, Chrome, Safari
  • Consider testing the curl command for URL visits
• Consider building with both Maven and Gradle build tools
• Testing with different IDEs, ie, Atom, Eclipse (Optional: VS.code, IntelliJ, Microclimate)
• Run Acrolinx Checker on draft (above 70 score approximately)
• Consider SEO title and description for the guides
• Ensure automated test is enable, set up with Travis CI, and able to schedule tests
• Run diff -r start/ finish/ and there's no differences
• Ensure that the automation tests are able to run when PR is created

Peer Tester’s responsibility:

• Check the appearance of the guide on test site for the following items:
  • Table of contents
  • Headings
  • Paragraphs
  • code snippets
  • outputs
  • links
  • hotspots
• Test the guide end-to-end with working instruction and sample code
• Perform all the defined test cases

ID review feedback

I added ID review feedback in the attached Word doc. Let me know if you have any questions!

social-media-login-guide.docx

Peer Review - Mac

Peer Review: review to be done by a peer member.

Functionality

• Check that the guide has working instructions and sample code
• Test the guide on 3 platforms: Mac, Win, Linux
• If any URL visits, try them on different browsers: Firefox, Chrome, Safari
• If any URL visits, try curl command where applicable

Formatting & Presentation

• Check the quality of code according to the best coding practices
  • Ensure that command substitutions use the $(cmd) format and not `cmd`
  • Ensure that the console output of the integrated tests do not include the [INFO] tab
• Check the quality and presentation of guide according to Structure and Style Guideline
• Check the consistency of guide with template and other guides
• Examples with the right outcomes are provided
• Example with the wrong outcomes, if any, are provided
• Check that all licensing statements are properly stated in all files
• Check that the pom.xml, server.xml, etc files are clean
• Check that the directories are properly structured
• Ensure that the guide is using the latest version of the liberty-maven-plugin or liberty-gradle-plugin where applicable
• Check that some of these page-tags are used in a guide: MicroProfile, Maven, Docker, Kubernetes, Gradle, Java EE, Security, Cloud. Only these tags are visible on the website. Latest list here.
• Check the attribution statement is accurate for the guide
• Verify the travisTest.sh script, if any, is accurate and consistent with other guides

Peer Testing: tests to be done by a peer member.

Guide’s contributor’s (if available, otherwise peer tester’s) responsibility:

• Additional tests where applicable:
  • Define test coverage and review with team (including guide contributor, if available)
  • Define detail test cases
  • Consider corner cases targeting the specific guide
  • Consider different platform tests, ie, Mac, Windows, Linux
  • Consider corner cases UI tests
  • Consider testing URL on all browsers, ie, FF, Chrome, Safari
  • Consider testing the curl command for URL visits
• Consider building with both Maven and Gradle build tools
• Testing with different IDEs, ie, Atom, Eclipse (Optional: VS.code, IntelliJ, Microclimate)
• Run Acrolinx Checker on draft (above 70 score approximately)
• Consider SEO title and description for the guides
• Ensure automated test is enable, set up with Travis CI, and able to schedule tests
• Run diff -r start/ finish/ and there's no differences
• Ensure that the automation tests are able to run when PR is created

Peer Tester’s responsibility:

• Check the appearance of the guide on test site for the following items:
  • Table of contents
  • Headings
  • Paragraphs
  • code snippets
  • outputs
  • links
  • hotspots
• Test the guide end-to-end with working instruction and sample code
• Perform all the defined test cases

Laura's review feedback

I started reviewing but I have to review another first so here's what I had already - I will return to add more later/next week:

• "which users can use " -> "which your application users can use " maybe? Not essential but I find that we sometimes use "users" a bit loosely so it's not always clear who we mean (eg devleopers who are the users of Liberty, or end-users who use the app that the developers write using Liberty). I don't think we need to repeatedly clarify this but on this first mention maybe just make clear that we're talking about the users of the app?
• Think the URL/slug of the guide should be social-media-login as that's the name of the feature and technically "social" isn't a thing but "social media" is (whatever Marketing says).
• Ugh, don't think we need to trademark all those social media platform names. It looks messy and it's not necessary (check with @yeekangc or we can dig out the guidance we found last time this came up).
• "BASIC authentication" -> "basic authentication" (no highlighting or caps - otherwise it looks like you're talking 1980s computing...which was awesome but probably not relevant here...)
• "find the login button" - make sure the button label matches exactly what you say in the text (so "Login button"). Don't need to make every instance of "login button" active. But also, I'm not sure that either of these instances is appropriate to make active actually. You're not talking about the code in either case; you're talking about the UI button. If you want to say that the Login button on the page relates to the code, I think it needs to be said explicitly. eg "When you access the hello.html page, find the Login button, which is defined in the button line of the page's source code." or something...not great wording I know. I think basically in the text you're mixing in the same sentences the reader's act of accessing the hello.html page in a browser and seeing the UI with them looking at the line in the source of the hello.html page that defines that button.
• "for defaultRealm. " needs explaining - what's defaultRealm mean? Does the reader need to care here (ie should it be mentioned at all in this guide?)?

TBC....

Peer Review - Mac

Peer Review conducted on 3 platforms: Mac, Windows & Linux

• Mac OS is our base OS as the dev content team generally develops on the Mac OS.
• Conduct three separate peer reviews for each OS.

Peer Review: review to be done by a peer member.

Functionality

• Check that the guide has working instructions and sample code
• If any URL visits, try them on different browsers: Firefox, Chrome, Safari
• If any URL visits, try curl command where applicable

Formatting & Presentation

README.adoc checks:

• Ensure that command substitutions use the $(cmd) format and not `cmd`
• Ensure that the console output of the integrated tests do not include the [INFO] tab
• Check the quality and presentation of guide according to Structure and Style Guideline
• Check that the pom.xml, server.xml, etc files are clean
  • Remove any dependencies and features that are not required
  • Ensure that the parent pom.xml files do not contain any dependencies, and all dependencies are specified in the children pom.xml files
• Examples with the right outcomes are provided
• Example with the wrong outcomes, if any, are provided

pom.xml checks (if files are present):

• Check that the file follows the template found here: https://github.com/OpenLiberty/draft-guides-template/blob/master/finish/pom.xml
• Check that the following dependencies are included in all of the pom.xml files:

<!-- Provided dependencies -->
<dependency>
  <groupId>jakarta.platform</groupId>
  <artifactId>jakarta.jakartaee-api</artifactId>
  <version>8.0.0</version>
  <scope>provided</scope>
</dependency>

<dependency>
  <groupId>org.eclipse.microprofile</groupId
  <artifactId>microprofile</artifactId>
  <version>3.3</version>
  <type>pom</type>
  <scope>provided</scope>
</dependency>

• Check that the versions of plugins are directly provided and not fed in by a file property.
  • Not formatted like so:

    <properties>
        <!-- Plugins -->
        <version.liberty-maven-plugin>3.2</version.liberty-maven-plugin>
    </properties>

    <!-- Liberty plugin -->
    <plugin>
        <groupId>io.openliberty.tools</groupId>
        <artifactId>liberty-maven-plugin</artifactId>
        <version>${version.liberty-maven-plugin}</version>
    </plugin>

• Should be formatted like so:

    <!-- Liberty plugin -->
    <plugin>
        <groupId>io.openliberty.tools</groupId>
        <artifactId>liberty-maven-plugin</artifactId>
        <version>3.2</version>
    </plugin>

• Check that there are 4 spaces per indent for proper formatting
• Ensure that the guide is using the latest version of the liberty-maven-plugin or liberty-gradle-plugin where applicable

Overall checks:

• Check the consistency of guide with the template and other guides
• Check the quality of code according to the best coding practices
• Check that all licensing statements are properly stated in all files, with the correct year (Should be present in all Java files + the index.html)
• Check that the directories are properly structured
• Check that some of these page-tags are used in a guide: MicroProfile, Maven, Docker, Kubernetes, Gradle, Java EE, Security, Cloud. Only these tags are visible on the website. Latest list here.
• Check the attribution statement is accurate for the guide
• Verify the travisTest.sh script, if any, is accurate and consistent with other guides

---

• Additional tests where applicable:
  • Define test coverage and review with team (including guide contributor, if available)
  • Define detail test cases
  • Consider corner cases targeting the specific guide
  • Consider corner cases UI tests
  • Consider testing URL on all browsers, ie, FF, Chrome, Safari
  • Consider testing the curl command for URL visits
• Consider building with both Maven and Gradle build tools
• Testing with different IDEs, ie, Atom, Eclipse (Optional: VS.code, IntelliJ, Microclimate)
• Run Acrolinx Checker on draft (above 70 score approximately)
• Consider SEO title and description for the guides
• Ensure automated test is enable, set up with Travis CI, and able to schedule tests
• Run diff -r start/ finish/ and there's no differences
• Ensure that the automation tests are able to run when PR is created
• Check the appearance of the guide on test site for the following items:
  • Table of contents
  • Headings
  • Paragraphs
  • code snippets
  • outputs
  • links
  • hotspots
• Test the guide end-to-end with working instruction and sample code
• Perform all the defined test cases

Dev content review 4

• Securing HelloService
  • in the last paragraph of this section, @Config hotspot to the line @Context, should change @Config to @Context?
• Configuring the security and social media login
  • Adding required features
    • the word "elements" no need to be part of the hotspot
  • Adding Amazon login configuration
    • clientId, clientSecret, sslRef, and all other hotspots should hotspot to particular line instead of whole <oauth2Login/> block
    • the word oauth2Login in the "Further documentation ..." no need to be formatted as oauth2Login, should be part of the link
  • Adding Google login configuration
    • all hotspots should hotspot to particular line instead of whole <oidcLogin/> block
    • the word oidcLogin in the "Further documentation ..." no need to be formatted as oidcLogin, should be part of the link
• both pom.xml in finish and start directories
  • artifactId should be "guide-social-login" instead of "draft-guide-social-login"
  • convert the pom.xml to ideal pom.xml, see the guides which were converted with dev mode
• both server.xml in finish and start directories
  • change ""draft-guide-social-login.war" to ""guide-social-login.war"

Dev content review for the experimental branch

• missing instruction to start dev mode? or missing the whole section "Creating a secured servlet"?
• Implementing logout
  • After the "Create this GitHubLogout class." command, rewrite "A DELETE request...", add words to explain using github provided REST api to revoke permissions ...
  • "You are also provided with a LogoutHandler..." already say provided, why need to update LogoutHandler?
  • should LogoutServlet alse be provided? Generic to other social login provider too? If yes, no need to update it and no need to explain. The focus will be in the GitHubLogout.
• Next Steps
  • need to add something to update LogoutHandler and implement an ILogout for Facebook
• HelloServlet.java and LogoutServlet.java may need private static final long serialVersionUID = 1L; or generated uid
• GitHubLogout.java and ILogout.java, remove unused import javax.servlet.ServletException;
• In LogoutHandler, use better exception instead of IllegalArgumentException

Dev content review 3

• What you’ll learn
  • "HelloService is an existing microservice..." -> "HelloService is a provided microservice..."
  • "Instead of securing your HelloService service..." -> "Instead of securing the HelloService service..."
  • "... authenticate to your service using social media accounts." -> "... authenticate to the service using social media accounts."
  • "By the end of this guide, you will secure your HelloService service ..." -> "By the end of this guide, you will secure the HelloService service ..."
• Setting up the certificates and trust store
  • "Lastly, you need to create applications ..." Should the application plural or singlar?
  • For the GUI instruction, is missing following for the Download?
    • go to "Detail" tab
    • click Export button
  • Can "openssl s_client ..." command achieve as same as GUI instruction?
    • If yes, no need to have the GUI instruction
    • but, I failed to run openssl s_client -showcerts -connect https://developers.google.com:443 </dev/null on my mac
  • openssl and keytool cannot be run on Win
    • should talk readers where are they
  • I doubt to use \ for Win
  • should different platforms have diferent instruction to get the certificates?
  • I suggest not to display the full content of the example certificate -----BEGIN CERTIFICATE-----
• Securing HelloService
  • the "Update" command is not our practice. See the subsection "Securing the system service" of the JWT guide https://openliberty.io/guides/microprofile-jwt.html
    • or use "Replace" instead, see the subsection "Enabling dynamic configuration injection" of the MP config guide https://openliberty.io/guides/microprofile-config.html
• Configuring the security and social media login
  • "Replace the server.xml class." -> "Replace the server configuration file."
  • "Replace the contents of src/main/liberty/config/server.xml. " is duplcated in some sense. Suggest to remove it
  • Adding Amazon login configuration
    • Should hotspot clientId and clientSecret
    • Should clientId and clientSecret be empty string? I doubt. Should ask reader to replace them instead of saying they "should be ..."
  • Adding Amazon login configuration
    • Should hotspot clientId and clientSecret
    • Should clientId and clientSecret be empty string? I doubt. Should ask reader to replace them instead of saying they "should be ..."
    • should hotspot sslRef
    • for all the configuration elements,
      • suggest having hotspot
      • the urls no need to be a link, do like that a backtick char + \https://www.amazon.com/ap/oa
    • the link "Open Liberty config reference on oauth2Login" does not open a new tab and the word oauth2Login no need to be formatted as oauth2Login
  • Adding Google login configuration
    • Should hotspot clientId and clientSecret
    • Should clientId and clientSecret be empty string? I doubt. Should ask reader to replace them instead of saying they "should be ..."
    • should hotspot sslRef
      • for all the configuration elements,
      • suggest having hotspot
      • the urls no need to be a link, do like that a backtick char + \https://accounts.google.com/o/oauth2/v2/auth
    • the link "Open Liberty config reference on oauth2Login" does not open a new tab and the word oauth2Login no need to be formatted as oauth2Login
• Testing the service
  • After I reconsidered it, suggest no automation IT tests. Open an issue to investigate how to do full integration test for redirect social login in future.
  • Suggest to say following in this section:
    • "No automated tests are provided in this guide. You can test this service manually by starting a server and pointing a web browser at the http://localhost:9080/api/hello URL."
• Suggest to add following guides for "Where to next?" too
  • https://draft-guides.mybluemix.net/guides/microprofile-jwt.html
  • https://draft-guides.mybluemix.net/guides/security-intro.html

Peer Review - Linux

Peer Review: review to be done by a peer member.

Functionality

• Check that the guide has working instructions and sample code
• Test the guide on 3 platforms: Mac, Win, Linux
• If any URL visits, try them on different browsers: Firefox, Chrome, Safari
• If any URL visits, try curl command where applicable

Formatting & Presentation

• Check the quality of code according to the best coding practices
  • Ensure that command substitutions use the $(cmd) format and not `cmd`
  • Ensure that the console output of the integrated tests do not include the [INFO] tab
• Check the quality and presentation of guide according to Structure and Style Guideline
• Check the consistency of guide with template and other guides
• Examples with the right outcomes are provided
• Example with the wrong outcomes, if any, are provided
• Check that all licensing statements are properly stated in all files
• Check that the pom.xml, server.xml, etc files are clean
• Check that the directories are properly structured
• Ensure that the guide is using the latest version of the liberty-maven-plugin or liberty-gradle-plugin where applicable
• Check that some of these page-tags are used in a guide: MicroProfile, Maven, Docker, Kubernetes, Gradle, Java EE, Security, Cloud. Only these tags are visible on the website. Latest list here.
• Check the attribution statement is accurate for the guide
• Verify the travisTest.sh script, if any, is accurate and consistent with other guides

Peer Testing: tests to be done by a peer member.

Guide’s contributor’s (if available, otherwise peer tester’s) responsibility:

• Additional tests where applicable:
  • Define test coverage and review with team (including guide contributor, if available)
  • Define detail test cases
  • Consider corner cases targeting the specific guide
  • Consider different platform tests, ie, Mac, Windows, Linux
  • Consider corner cases UI tests
  • Consider testing URL on all browsers, ie, FF, Chrome, Safari
  • Consider testing the curl command for URL visits
• Consider building with both Maven and Gradle build tools
• Testing with different IDEs, ie, Atom, Eclipse (Optional: VS.code, IntelliJ, Microclimate)
• Run Acrolinx Checker on draft (above 70 score approximately)
• Consider SEO title and description for the guides
• Ensure automated test is enable, set up with Travis CI, and able to schedule tests
• Run diff -r start/ finish/ and there's no differences
• Ensure that the automation tests are able to run when PR is created

Peer Tester’s responsibility:

• Check the appearance of the guide on test site for the following items:
  • Table of contents
  • Headings
  • Paragraphs
  • code snippets
  • outputs
  • links
  • hotspots
• Test the guide end-to-end with working instruction and sample code
• Perform all the defined test cases

Publishing Tasks Checklist

Publishing Tasks

• Update the release date
• Create qa branch from dev branch
• Rename dev to master branch
• Rename the guide repo
  • guide-social-media-login
• Check that tags and categories are updated
  • https://github.com/OpenLiberty/guides-common
• Refresh qa staging site and verify
• If qa site has no problem, request to refresh openliberty.io site
• For master branch, add a tag by creating a new release for this repo with name "1st-release"

Post-Publishing Tests Checklist

Post-Publishing Tests (Austin)

• Check appearance (contents, headings, paragraphs, code snippets, outputs, links) of the guide on openliberty.io
• Clone repo and test finish directory with no error
• test the start directory end-to-end

Other post-publishing tasks (to be done by the Admin Team)

• Add description for the repo with link to guide's published website
• Double check the SEO title and description are added for the guide
• Create the Home and Branches wiki pages
• Ensure automated test for PR and Continuous Tests are enabled for both master and qa branches and are run on Travis, see instruction
• Ensure the automated tests are running successfully for the daily builds
• Ensure the automated tests are running successfully for the daily docker image, if the guide uses a docker image
• Enable pull creation notification on the repo for was-lib-guides-alerts, see instruction
• Enable master and qa branches lock down, see instruction
  • make sure the Branch protection rules were created
• Add the new guide's repo to the OpenLiberty/guides-common ZenHub board
• Clean up branches, issues, and PRs
• Send announcement to slack channels
  • dev_advocates_java
  • was-lib-guides-dev
  • was-gm-testing
• Arrange a demo at the EOI meeting

Post-Publishing Tests Checklist hasno dependencies

SEO description shouldn't be abstract

The description for SEO shouldn't be the visible abstract.

Please consult the other guides for examples. The abstract should be done in manner that is consistent with the other guides.

Acrolinx Check

What you’ll learn

• "end users" (Do not use - Deprecated Term) -> use "users"

  It simplifies the authentication process for end users and allows you to provide a secure authentication method for your users without having to explicitly implement it.

Creating a secured servlet

• Do not use "we", use "you"

  We will create a servlet to handle GET requests

• change "clicking on" to "clicking"

  When users access this endpoint by clicking on the login button

Implementing logout

• Too complex - Clarity

  Before the user is logged out of the application, the access token obtained by Social Login from the social media provider as part of the authentication can be used to revoke user permissions for the application

• change "logs into" to "logs in to"

  When the user logs into the application again

• Delete this word or phrase "," - incorrect extra comma

  Lastly, the HttpServletRequest#logout() method is used to log the user out of the application, after which the user is redirected to hello.html.

Configuring security and social media login

• use "this" with noun

  Adding this allows users that are authenticated using social media login to access your HelloService service.

• use "this" with noun

  This requires the SSL certificates for GitHub to be added to a truststore.

Next Steps

• change "setup" to "set up"

  You can create the configuration element in server.xml to setup login for Facebook.

Add a prereq section

Suggested in the EOI demo to add a prereq section for Github account, because we cannot assume that user has an account.

Content Review

@lauracowen 's comments about the guide:

Content

shouldn’t ask the user to ‘replace’ or ‘update’ files at all. They should ‘create’ the files. Then the text explains the relevant parts of the file for this guide.

The start directory (which is what they’re editing) should contain only files that are basically irrelevant to the guide. The files in the start directory are files that would be pointless for the user to create because they wouldn’t learn anything from doing so. If the file is part of the learning process (ie server.xml, HelloService.java here), they should be creating the file (even if it’s just copy/paste from the guide, it draws their attention to the specific file and what it contains). Then you explain the important bits of the file so they understand why that file is important in the context of this guide.

would make the guide simpler/slicker if we were just to have the github one. Partly because one is simpler/shorter than two to document, and partly because the LinkedIn one says it requires setting up a company page which is a whole load of extra faff to do just to be able to do the guide.

(check with [ @gkwan-ibm ]/[ @yeekangc ] the LinkedIn thing, in case there was some other reason but I’m inclined to think it’s not necessary)

One thing I’d like our guides to do more is include an extra ‘task’ at the end for the user to try on their own. So you could provide guidance on how to set up github. Then, after that’s working at the end of the guide, you could briefly explain that if more than one is added, there’s a selection form presented to the user and link them to the doc on how to add more (which does actually exist here: https://www.openliberty.io/docs/ref/feature/#socialLogin-1.0.html).

I think we can condense the github setup instructions down a bit then to something like:

Obtain an OAuth 2.0 client ID and client secret credentials for accessing the GitHub developer API by registering a new application in your GitHub account. On the Settings > Developer settings > OAuth Apps page of your account, register a new application. Set the Homepage URL to https://localhost:9443/. and the Authorization callback URL to https://localhost:9443/ibm/api/social-login/redirect/githubLogin . When the registration is complete, the client ID and client secret credentials are displayed on xxxxx. You’ll need these two values later in the guide to authenticate your application with GitHub.

I don’t think you need the full step-by-step experience just to get the app registered - most of it’s pretty obvious - you just need to help them know what values to enter for the URLs.

Technical

Don’t think you need the bit at the start about creating certificates. You should just be able to use basic tls configuration
<keyStore id="defaultKeyStore" password="yourPassword" />

in your server.xml, I don’t think you need to specify all those features. The jwt one is automatically loaded by the social media login one (so shouldn’t need to be explicitly specified, I think). The ssl one is auto loaded by the tls one, and by the social media login one

Front matter needs updates

Should review and update the front matter to reflect what is covered by the guide accurately.

e.g. I don't think this guide should be tagged with Jakarta EE or Java EE. Should review SEO metadata too.

@k-rtik @gkwan-ibm

Peer Review 3 - Windows

Functionality

• Check that the guide has working instructions and sample code
  • Testing on Windows 10 using Java 8 using branch experimental
• If any URL visits, try them on different browsers: Firefox, Chrome, Safari
• If any URL visits, try curl command where applicable (N/A)

Formatting & Presentation

README.adoc checks:

• Ensure that command substitutions use the $(cmd) format and not `cmd`
• Ensure that the console output of the integrated tests do not include the [INFO] tab (N/A)
• Check the quality and presentation of guide according to Structure and Style Guideline
• Check that the pom.xml, server.xml, etc files are clean (addressed already)
  • Remove any dependencies and features that are not required
  • Ensure that the parent pom.xml files do not contain any dependencies, and all dependencies are specified in the children pom.xml files (N/A)
• Examples with the right outcomes are provided (N/A)
• Example with the wrong outcomes, if any, are provided (N/A)

pom.xml checks (if files are present):

• Check that the file follows the template found here: https://github.com/OpenLiberty/draft-guides-template/blob/master/finish/pom.xml
• Check that the following dependencies are included in all of the pom.xml files:

<!-- Provided dependencies -->
<dependency>
  <groupId>jakarta.platform</groupId>
  <artifactId>jakarta.jakartaee-api</artifactId>
  <version>8.0.0</version>
  <scope>provided</scope>
</dependency>

<dependency>
  <groupId>org.eclipse.microprofile</groupId
  <artifactId>microprofile</artifactId>
  <version>3.3</version>
  <type>pom</type>
  <scope>provided</scope>
</dependency>

• Check that the versions of plugins are directly provided and not fed in by a file property.
  • Not formatted like so:

    <properties>
        <!-- Plugins -->
        <version.liberty-maven-plugin>3.2</version.liberty-maven-plugin>
    </properties>

    <!-- Liberty plugin -->
    <plugin>
        <groupId>io.openliberty.tools</groupId>
        <artifactId>liberty-maven-plugin</artifactId>
        <version>${version.liberty-maven-plugin}</version>
    </plugin>

• Should be formatted like so:

    <!-- Liberty plugin -->
    <plugin>
        <groupId>io.openliberty.tools</groupId>
        <artifactId>liberty-maven-plugin</artifactId>
        <version>3.2</version>
    </plugin>

• Check that there are 4 spaces per indent for proper formatting
• Ensure that the guide is using the latest version of the liberty-maven-plugin or liberty-gradle-plugin where applicable

Overall checks:

• Check the consistency of guide with the template and other guides
• Check the quality of code according to the best coding practices
• Check that all licensing statements are properly stated in all files, with the correct year (Should be present in all Java files + the index.html) (Addressed in different branch/peer review)
• Check that the directories are properly structured
• Check that some of these page-tags are used in a guide: MicroProfile, Maven, Docker, Kubernetes, Gradle, Java EE, Security, Cloud. Only these tags are visible on the website. Latest list here.
• Check the attribution statement is accurate for the guide
• Verify the travisTest.sh script, if any, is accurate and consistent with other guides

---

Guide’s contributor’s (if available, otherwise peer tester’s) responsibility:

• Additional tests where applicable:
  • Define test coverage and review with team (including guide contributor, if available)
  • Define detail test cases
  • Consider corner cases targeting the specific guide
  • Consider corner cases UI tests
  • Consider testing URL on all browsers, ie, FF, Chrome, Safari
  • Consider testing the curl command for URL visits
• Consider building with both Maven and Gradle build tools
• Testing with different IDEs, ie, Atom, Eclipse (Optional: VS.code, IntelliJ, Microclimate)
• Run Acrolinx Checker on draft (above 70 score approximately)
• Consider SEO title and description for the guides
• Ensure automated test is enable, set up with Travis CI, and able to schedule tests
• Run diff -r start/ finish/ and there's no differences
• Ensure that the automation tests are able to run when PR is created

Peer Tester’s responsibility:

• Check the appearance of the guide on test site for the following items:
  • Table of contents
  • Headings
  • Paragraphs
  • code snippets
  • outputs
  • links
  • hotspots
• Test the guide end-to-end with working instruction and sample code
• Perform all the defined test cases (N/A)

Dev content review 5

• For Windows, I doubt keytool is in the PATH env. Should use %JAVA_HOME%\bin\keytool?
• The order in "Setting up the certificates and truststore" is Google, GitHub, and Amazon, so that the order in "Configuring the security and social media login" should follow

Peer Review - Mac

Peer Review: review to be done by a peer member.

Functionality

• Check that the guide has working instructions and sample code
• Test the guide on 3 platforms: Mac, Win, Linux
• If any URL visits, try them on different browsers: Firefox, Chrome, Safari
• If any URL visits, try curl command where applicable

Formatting & Presentation

• Check the quality of code according to the best coding practices
  • Ensure that command substitutions use the $(cmd) format and not `cmd`
  • Ensure that the console output of the integrated tests do not include the [INFO] tab
• Check the quality and presentation of guide according to Structure and Style Guideline
• Check the consistency of guide with template and other guides
• Examples with the right outcomes are provided
• Example with the wrong outcomes, if any, are provided
• Check that all licensing statements are properly stated in all files
• Check that the pom.xml, server.xml, etc files are clean
• Check that the directories are properly structured
• Ensure that the guide is using the latest version of the liberty-maven-plugin or liberty-gradle-plugin where applicable
• Check that some of these page-tags are used in a guide: MicroProfile, Maven, Docker, Kubernetes, Gradle, Java EE, Security, Cloud. Only these tags are visible on the website. Latest list here.
• Check the attribution statement is accurate for the guide
• Verify the travisTest.sh script, if any, is accurate and consistent with other guides

Peer Testing: tests to be done by a peer member.

Guide’s contributor’s (if available, otherwise peer tester’s) responsibility:

• Additional tests where applicable:
  • Define test coverage and review with team (including guide contributor, if available)
  • Define detail test cases
  • Consider corner cases targeting the specific guide
  • Consider different platform tests, ie, Mac, Windows, Linux
  • Consider corner cases UI tests
  • Consider testing URL on all browsers, ie, FF, Chrome, Safari
  • Consider testing the curl command for URL visits
• Consider building with both Maven and Gradle build tools
• Testing with different IDEs, ie, Atom, Eclipse (Optional: VS.code, IntelliJ, Microclimate)
• Run Acrolinx Checker on draft (above 70 score approximately)
• Consider SEO title and description for the guides
• Ensure automated test is enable, set up with Travis CI, and able to schedule tests
• Run diff -r start/ finish/ and there's no differences
• Ensure that the automation tests are able to run when PR is created

Peer Tester’s responsibility:

• Check the appearance of the guide on test site for the following items:
  • Table of contents
  • Headings
  • Paragraphs
  • code snippets
  • outputs
  • links
  • hotspots
• Test the guide end-to-end with working instruction and sample code
• Perform all the defined test cases

SME Review

Need to address comments left by SME:

One thing I notice is that the effort to configure trust store to trust social media certificate is big. The certificates used by social medium you refer in this guide are signed by well-known CA, and can be found in the java cacerts file, and there is an option to automatically trust those CA without exporting from social media and importing to Liberty trust store. All you need is to add trustDefaultCerts="true" to ssl configuration.

Peer Review #2 - Windows

Peer Review: review to be done by a peer member.

Functionality

• Check that the guide has working instructions and sample code
• Test the guide on 3 platforms: Mac, Win, Linux
• If any URL visits, try them on different browsers: Firefox, Chrome, Safari
• If any URL visits, try curl command where applicable

Formatting & Presentation

• Check the quality of code according to the best coding practices
  • Ensure that command substitutions use the $(cmd) format and not `cmd`
  • Ensure that the console output of the integrated tests do not include the [INFO] tab
• Check the quality and presentation of guide according to Structure and Style Guideline
• Check the consistency of guide with template and other guides
• Examples with the right outcomes are provided
• Example with the wrong outcomes, if any, are provided
• Check that all licensing statements are properly stated in all files
• Check that the pom.xml, server.xml, etc files are clean
• Check that the directories are properly structured
• Ensure that the guide is using the latest version of the liberty-maven-plugin or liberty-gradle-plugin where applicable
• Check that some of these page-tags are used in a guide: MicroProfile, Maven, Docker, Kubernetes, Gradle, Java EE, Security, Cloud. Only these tags are visible on the website. Latest list here.
• guide needs to be added to guide_tags.json in guides-common dev branch for tags to appear
• Check the attribution statement is accurate for the guide
• Verify the travisTest.sh script, if any, is accurate and consistent with other guides

Peer Testing: tests to be done by a peer member.

Guide’s contributor’s (if available, otherwise peer tester’s) responsibility:

• Additional tests where applicable:
  • Define test coverage and review with team (including guide contributor, if available)
  • Define detail test cases
  • Consider corner cases targeting the specific guide
  • Consider different platform tests, ie, Mac, Windows, Linux
  • Consider corner cases UI tests
  • Consider testing URL on all browsers, ie, FF, Chrome, Safari
  • Consider testing the curl command for URL visits
• Consider building with both Maven and Gradle build tools
• Testing with different IDEs, ie, Atom, Eclipse (Optional: VS.code, IntelliJ, Microclimate)
• Run Acrolinx Checker on draft (above 70 score approximately)
• Consider SEO title and description for the guides
• Ensure automated test is enable, set up with Travis CI, and able to schedule tests
• Run diff -r start/ finish/ and there's no differences
• Ensure that the automation tests are able to run when PR is created

Peer Tester’s responsibility:

• Check the appearance of the guide on test site for the following items:
  • Table of contents
  • Headings
  • Paragraphs
  • code snippets
  • outputs
  • links
  • hotspots
• Test the guide end-to-end with working instruction and sample code
• Perform all the defined test cases (n/a)

Dev content review 2

• What you’ll learn*
  • the links "Social Media Login feature" should open a new tab
  • if https://oauth.net/2 is the offical website, add a link to the word "OAuth2"
  • if https://openid.net/connect is the offical website, add a link to the word " OpenID Connect"
• Setting up the certificates and trust store
  • Need inform or url to let readers know where to get the Amazon, Google and Github certificates
    • is there an alternative? Firefox Preferences > Privacy & Security > Security > Certificates > View Certificates... > select Amzon .... > Export etc
  • for the keytool -import... command, need to tell readers to replace <certificate-file-name> and <certificate-alias>
  • the last sentence is not right: "In order to try what you’ll build, enter the client IDs and client secrets to server.xml in the finish folder."
    • no need the begining phase "In order ...,"
    • should specify the full path for server.xml, i.e. src/main/liberty/config/server.xml
    • should be the start folder
• Securing HelloService
  • Need to tell readers "Navigate to the start directory" at the very beginning.
  • Missed to ask readers to add import statments.
  • the case not match "Users" in content vs "users" in java
  • the statement "First, add ..." says first but at the end of the section
• Configuring the security and social media login
  • server.xml still has a wrapped line
  • make sure all hotspots work
  • is it possible to add a hotspot to some words, e.g. keyStore, ssl, etc
  • feature elements
    • no need to use green box for the <feature/>s
    • or the green box is no need. Rephase the statment + using hotspot, readers will understand
• Building and running the application
  • The following statement not right because dev mode is not started from the above instructions.
    • "The Open Liberty server was started..."
• Testing the service
  • reduce the content, too detail
• if the java files are new, the license year can be 2020 instead of 2017, 2019
  • if the java files are from other source, the license year should be e.g. 2017, 2020 instead of 2017, 2019