Configure social login in Liberty

We can configure a Liberty server so that users can authenticate to websites hosted on the Liberty server by logging in with their social media accounts. Choose from the predefined social media platform configurations, or define our own configuration for any social media platform that is based on the OAuth 2.0 or OpenID Connect 1.0 standards.

Social login is a form of single sign-on (SSO) that enables users to sign in to a website using their existing social media account instead of creating an account specifically for the website. For example, we can configure social login so that users can log in to your website with their Facebook or Twitter accounts. We can enable social login for any social media platform that uses the OAuth 2.0 or OpenID Connect 1.0 standard for authorization. In Liberty, social login is enabled by the socialLogin-1.0 feature. We can configure social login for one or more of the following social media platforms.

• Facebook
• GitHub
• Google
• LinkedIn
• Twitter
• Other OAuth 2.0 social media platforms
• Other OpenID Connect 1.0 Provider

Configure social login for Facebook

Configure social login for Facebook.

1. Create a Facebook application.

   See Facebook App Development. When configuring the application, register our Liberty server with the application by providing a redirect URL in the following format:

   https://liberty_host:SSL_port/ibm/api/social-login/redirect/facebookLogin

   After we create the application, note the app ID and app secret, which we will add to our Liberty configuration.

2. Open the server.xml configuration file for the Liberty server, and add the socialLogin-1.0 and appSecurity-2.0 features.

   <featureManager>
       <feature>socialLogin-1.0</feature>
       <feature>appSecurity-2.0</feature>
       ...
   </featureManager>

3. Add the facebookLogin element and configure it with the app ID and app secret.
   <facebookLogin clientId="facebook_app_id" clientSecret="facebook_app_secret" />

   The facebookLogin element specifies certain default values for the connection to Facebook. We can override the default values and specify other settings by configuring more attributes as listed in Facebook Login.

4. Configure a truststore on the keyStore element, and import the certificate from the Facebook endpoint to the truststore.

   For example, the following configuration points to the default Liberty truststore file.

   <keyStore id="defaultKeyStore" password="keyspass" />

   To import the certificate to the Liberty truststore, in your browser, go to one of the endpoints specified by the facebookLogin element, and export the certificate. Use a key management tool such as iKeyman or the Java keytool utility to add the certificate to the Liberty truststore file. Tip: In some cases, we might have to import more than one certificate. For details about which certificates we need to import, see the messages.log file.

Configure social login for GitHub

Configure social login for GitHub.

1. Create a GitHub OAuth application.

   See the information about web applications in GitHub: OAuth API. When configuring the application, register our Liberty server with the application by providing a redirect URL in the following format:

   https://liberty_host:SSL_port/ibm/api/social-login/redirect/githubLogin

   After we create the application, note the client ID and client secret, which we will add to our Liberty configuration.

2. Open the server.xml configuration file for the Liberty server, and add the socialLogin-1.0 and appSecurity-2.0 features.

   <featureManager>
       <feature>socialLogin-1.0</feature>
       <feature>appSecurity-2.0</feature>
       ...
   </featureManager>

3. Add the githubLogin element and configure it with the client ID and client secret.

   <githubLogin clientId="github_client_id" clientSecret="github_client_secret" />

   The githubLogin element specifies certain default values for the connection to GitHub. We can override the default values and specify other settings by configuring more attributes as listed in GitHub Login.

4. Configure a truststore on the keyStore element, and import the certificate from the GitHub endpoint to the truststore.

   For example, the following configuration points to the default Liberty truststore file.

   <keyStore id="defaultKeyStore" password="keyspass" />

   To import the certificate to the Liberty truststore, in your browser, go to one of the endpoints specified by the githubLogin element, and export the certificate. Use a key management tool such as iKeyman or the Java keytool utility to add the certificate to the Liberty truststore file. Tip: In some cases, we might have to import more than one certificate. For details about which certificates we need to import, see the messages.log file.

Configure social login for Google

Configure social login for Google.

1. Create an OAuth client ID in a Google API Console project.

   See Create a Google API Console project and client ID.

   When configuring the application, register our Liberty server with the application by providing a redirect URL in the following format:

   https://liberty_host:SSL_port/ibm/api/social-login/redirect/googleLogin

   After we create the client ID, note the client ID and client secret, which we will add to our Liberty configuration.

2. Open the server.xml configuration file for the Liberty server, and add the socialLogin-1.0 and appSecurity-2.0 features.

   <featureManager>
       <feature>socialLogin-1.0</feature>
       <feature>appSecurity-2.0</feature>
       ...
   </featureManager>

3. Add the googleLogin element and configure it with the client ID and client secret.
   <googleLogin clientId="google_client_id" clientSecret="google_client_secret" />

   The googleLogin element specifies certain default values for the connection to Google. We can override the default values and specify other settings by configuring more attributes as listed in Google Login.

4. Configure a truststore on the keyStore element, and import the certificate from the Google endpoint to the truststore.

   For example, the following configuration points to the default Liberty truststore file.

   <keyStore id="defaultKeyStore" password="keyspass" />

   To import the certificate to the Liberty truststore, in your browser, go to one of the endpoints specified by the googleLogin element, and export the certificate. Use a key management tool such as iKeyman or the Java keytool utility to add the certificate to the Liberty truststore file. Tip: In some cases, we might have to import more than one certificate. For details about which certificates we need to import, see the messages.log file.

Configure social login for LinkedIn

Configure social login for LinkedIn.

1. Create a LinkedIn application.

   See LinkedIn: Authenticating with OAuth 2.0. When configuring the application, register our Liberty server with the application by providing a redirect URL in the following format:

   https://liberty_host:SSL_port/ibm/api/social-login/redirect/linkedinLogin

   After we create the application, note the client ID and client secret, which we will add to our Liberty configuration.

2. Open the server.xml configuration file for the Liberty server, and add the socialLogin-1.0 and appSecurity-2.0 features.

   <featureManager>
       <feature>socialLogin-1.0</feature>
       <feature>appSecurity-2.0</feature>
       ...
   </featureManager>

3. Add the linkedinLogin element and configure it with the client ID and client secret.

   <linkedinLogin clientId="linkedin_client_id" clientSecret="linkedin_client_secret" />

   The linkedinLogin element specifies certain default values for the connection to LinkedIn. We can override the default values and specify other settings by configuring more attributes as listed in LinkedIn Login.

4. Configure a truststore on the keyStore element, and import the certificate from the LinkedIn endpoint to the truststore.

   For example, the following configuration points to the default Liberty truststore file.

   <keyStore id="defaultKeyStore" password="keyspass" />

   To import the certificate to the Liberty truststore, in your browser, go to one of the endpoints specified by the linkedinLogin element, and export the certificate. Use a key management tool such as iKeyman or the Java keytool utility to add the certificate to the Liberty truststore file. Tip: In some cases, we might have to import more than one certificate. For details about which certificates we need to import, see the messages.log file.

Configure social login for Twitter

Configure social login for Twitter.

1. Create a Twitter application.

   See Twitter Apps.

   After we create the application, enable the Request email addresses from users permission. Be sure to note the consumer key and consumer secret, which we will add to our Liberty configuration. We can optionally enable callback locking to ensure that apps cannot overwrite the callback URL. Under Sets, enter the callback URL in the following format and check the Enable Callback Locking setting.

   https://liberty_host:SSL_port/ibm/api/social-login/redirect/twitterLogin

2. Open the server.xml configuration file for the Liberty server, and add the socialLogin-1.0 and appSecurity-2.0 features.

   <featureManager>
       <feature>socialLogin-1.0</feature>
       <feature>appSecurity-2.0</feature>
       ...
   </featureManager>

3. Add the twitterLogin element and configure it with the client ID and client secret.
   <twitterLogin consumerKey="twitter_consumer_key" consumerSecret="twitter_consumer_secret" />

   The twitterLogin element specifies certain default values for the connection to Twitter. We can override the default values and specify other settings by configuring more attributes as listed in Twitter Login.

4. Configure a truststore on the keyStore element, and import the certificate from the Twitter endpoint to the truststore.

   For example, the following configuration points to the default Liberty truststore file.

   <keyStore id="defaultKeyStore" password="keyspass" />

   To import the certificate to the Liberty truststore, in your browser, go to one of the endpoints specified by the twitterLogin element, and export the certificate. Use a key management tool such as iKeyman or the Java keytool utility to add the certificate to the Liberty truststore file. Tip: In some cases, we might have to import more than one certificate. For details about which certificates we need to import, see the messages.log file.

Configure social login for a social media platform that supports OAuth 2.0

Configure social login for a social media platform that supports OAuth 2.0, such as Instagram or Pinterest.

1. Create an application for the social media platform.

   See the documentation for the specific social media platform.

   After we create the application, note the client ID and client secret, which we will add to our Liberty configuration.

2. Open the server.xml configuration file for the Liberty server, and add the socialLogin-1.0 and appSecurity-2.0 features.

   <featureManager>
       <feature>socialLogin-1.0</feature>
       <feature>appSecurity-2.0</feature>
       ...
   </featureManager>

3. Add the oauth2Login element and configure the connection to the social media platform.

   For information about configurable attributes, see OAuth 2,0 Login.

   For example, the following configuration defines social login for an Instagram application:

   <oauth2Login id="instagramLogin" clientId="client_id" clientSecret="client_secret" 
       scope="basic public_content"   responseType="code" 
       tokenEndpointAuthMethod="client_secret_post"
       authorizationEndpoint="https://api.instagram.com/oauth/authorize"
       tokenEndpoint="https://api.instagram.com/oauth/access_token"
       userApi="https://api.instagram.com/v1/users/self"
       userNameAttribute="username"
       website="https://www.instagram.com/developer/authentication/"> 
   </oauth2Login>

   Configuration tips:

   • The Liberty server passes the OAuth scope value that you define on the scope attribute to the social media platform.

     The defined scope must be supported by the social media platform, and the scope must grant enough access for the Liberty server to read user data from the social media platform. Additionally, if you intend for the social media application to call other social media APIs, such as a marketing API, the defined value must include the scope required by those APIs.

   • Define the social media platform's endpoints on the authorizationEndpoint and tokenEndpoint attributes. The Liberty server first redirects the user to the authorization endpoint to authenticate the user and obtain the OAuth authorization code. Then, it invokes the token endpoint to exchange the OAuth authorization code for an OAuth token.

4. Configure a truststore on the keyStore element, and import the certificate from the social media endpoint to the truststore.

   For example, the following configuration points to the default Liberty truststore file.

   <keyStore id="defaultKeyStore" password="keyspass" />

   To import the certificate to the Liberty truststore, in your browser, go to one of the endpoints specified by the oauth2Login element, and export the certificate. Use a key management tool such as iKeyman or the Java keytool utility to add the certificate to the Liberty truststore file. Tip: For some social media platforms, we might have to import more than one certificate. For details about which certificates we need to import, see the messages.log file.

5. Go back to your social media application, and configure a redirect or callback URL that points to the ID of the configured oauth2Login element in the following format.

   https://liberty_host:SSL_port/ibm/api/social-login/redirect/oauth2login_id

   For example, the redirect URL for the oauth2Login configuration example for Instagram has the following format:

   https://liberty_host:SSL_port/ibm/api/social-login/redirect/instagramLogin

Configure social login as OpenID Connect client

Configure social login as OpenID Connect client.

1. Register Liberty as OpenID Connect client in OpenID Connect Provider.

   See the documentation for the specific OpenID Connect Provider.

   Note: For Liberty 18.0.0.2 and earlier, this step is different. Create an application for the social media platform. After we create the application, note the client ID and client secret, which we will add to our Liberty configuration.

2. Open the server.xml configuration file for the Liberty server, and add the socialLogin-1.0 and appSecurity-2.0 features.

   <featureManager>
       <feature>socialLogin-1.0</feature>
       <feature>appSecurity-2.0</feature>
       ...
   </featureManager>

3. Add the oidcLogin element and configure the connection to the social media platform.

   For information about configurable attributes, see OpenID Connect 1,0 Login.

   • The following example configuration defines social login for a Google application that uses OpenID Connect:

     <oidcLogin id="googleOIDCLogin" clientId="client_id"
         clientSecret="client_secret"   
         authorizationEndpoint="https://accounts.google.com/o/oauth2/v2/auth"
         tokenEndpoint="https://www.googleapis.com/oauth2/v4/token"
         jwksUri="https://www.googleapis.com/oauth2/v3/certs"
         scope="openid profile email"
         userNameAttribute="email"
         isClientSideRedirectSupported="true"
         issuer="https://accounts.google.com"
         realmNameAttribute="iss" >
     </oidcLogin>

   • The following example configuration defines social login for a Google application where the OpenID Connect provider endpoints are automatically discovered through the discovery endpoint:

     <oidcLogin id="googleOIDCLogin" clientId="client_id"
         clientSecret="client_secret"   
         discoveryEndpoint=https://accounts.google.com/.well-known/openid-configuration
         scope="openid profile email"
         userNameAttribute="email"
         isClientSideRedirectSupported="true"
         realmNameAttribute="iss" >
     </oidcLogin>
     

     If a discovery endpoint is configured, other configured social login OIDC endpoints are ignored. All endpoints are replaced with the following discovered endpoints: issuer, authorizationEndpoint, tokenEndpoint, userInfoEndpoint, and jwksUri.

   Configuration tips:

   • The Liberty server passes the OAuth scope value that you define on the scope attribute to the social media platform. The defined scope must be supported by the social media platform, and the scope must grant enough access for the Liberty server to read user data from the social media platform. Additionally, if you intend for the social media application to call other social media APIs, such as a marketing API, the defined value must include the scope required by those APIs.

   • Define the social media platform's endpoints on the authorizationEndpoint and tokenEndpoint attributes. The Liberty server first redirects the user to the authorization endpoint to authenticate the user and obtain the OAuth authorization code. Then, it invokes the token endpoint to exchange the OAuth authorization code for an OAuth token.

4. Configure a truststore on the keyStore element, and import the certificate from the social media endpoint to the truststore.

   For example, the following configuration points to the default Liberty truststore file.

   <keyStore id="defaultKeyStore" password="keyspass" />

   To import the certificate to the Liberty truststore, in your browser, go to one of the endpoints specified by the oidcLogin element, and export the certificate. Use a key management tool such as iKeyman or the Java keytool utility to add the certificate to the Liberty truststore file. Tip: For some social media platforms, we might have to import more than one certificate. For details about which certificates we need to import, see the messages.log file.

5. Go back to your social media application, and configure a redirect or callback URL that points to the ID of the configured oidcLogin element in the following format.

   https://liberty_host:SSL_port/ibm/api/social-login/redirect/oidclogin_id

   For example, the redirect URL for the oidcLogin configuration example has the following format:

   https://liberty_host:SSL_port/ibm/api/social-login/redirect/googleOIDCLogin

• Social media selection form for Liberty
  
• Configure a custom social media selection form for Liberty
  

Parent topic: Authenticating users in Liberty

Related reference

• Social Media Login
• keyStore