Authenticating users through social media providers

duration 30 minutes

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.

Prerequisites:

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.

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.

Getting started

The fastest way to work through this guide is to clone the Git repository and use the projects that are provided inside:

Copied to clipboard
git clone https://github.com/openliberty/guide-social-media-login.git
cd guide-social-media-login

The start directory contains the starting project that you will build upon.

The finish directory contains the finished project that you will build.

Before you begin, make sure you have all the necessary prerequisites.

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:

Copied to clipboard
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.

When you run Open Liberty in dev mode, dev mode listens for file changes and automatically recompiles and deploys your updates whenever you save a new change. Run the following goal to start Open Liberty in dev mode:

Copied to clipboard
cd start
mvn liberty:dev

After you see the following message, your Liberty instance is ready in dev mode:

**************************************************************
*    Liberty is running in dev mode.

Dev mode holds your command-line session to listen for file changes. Open another command-line session to continue, or open the project in your editor.

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.
View Code
Copied to clipboard
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.

Running the application

You started the Open Liberty in dev mode at the beginning of the guide, so all the changes were automatically picked up.

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]

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.
View Code
Copied to clipboard
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.

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.

When you are done checking out the service, exit dev mode by pressing CTRL+C in the command-line session where you ran Liberty.

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:

 1<html>
 2<head>
 3    <title>Social Media Login Guide</title>
 4</head>
 5<body>
 6<h1>Social Media Login Guide</h1>
 7<p>Welcome to the social media login guide</p>
 8<p>You are currently not authenticated!</p>
11<form method="GET" action="hello">
14    <button type="submit">Log in</button>
16</form>
18</body>
19</html>20

Prerequisites:

Nice work! Where to next?

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

Authenticating users through social media providers by Open Liberty is licensed under CC BY-ND 4.0

What did you think of this guide?

Extreme Dislike Dislike Like Extreme Like

What could make this guide better?

Raise an issue to share feedback

Create a pull request to contribute to this guide

Need help?

Ask a question on Stack Overflow

Like Open Liberty? Star our repo on GitHub.

Star