Configuring social login in Liberty

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

About this task

Social login is a form of single sign-on (SSO) that enables users to sign in to a website by using their existing social media account instead of creating an account specifically for the website. For example, you can configure social login so that users can log in to your website with their Facebook or Twitter accounts. You 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. You 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

Configuring social login for Facebook

Configure social login for Facebook.

Create a Facebook application.
For more information, see Facebook App Development.
When you configure your application, register your 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 you create the application, note the app ID and app secret, which you will add to your Liberty configuration.

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>

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. You can override the default values and specify other settings by configuring more attributes as listed in Facebook Login.
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, you might have to import more than one certificate. For details about which certificates you need to import, see the messages.log file.

Configuring social login for GitHub

Configure social login for GitHub.

Create a GitHub OAuth application.
For more information, see the information about web applications in GitHub: OAuth API.
When you configure your application, register your 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 you create the application, note the client ID and client secret, which you will add to your Liberty configuration.

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>

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. You can override the default values and specify other settings by configuring more attributes as listed in GitHub Login.
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, you might have to import more than one certificate. For details about which certificates you need to import, see the messages.log file.

Configuring social login for Google

Configure social login for Google.

Create an OAuth client ID in a Google API Console project.
For more information, see Creating a Google API Console project and client ID.
When you configure your application, register your 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 you create the client ID, note the client ID and client secret, which you will add to your Liberty configuration.

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>

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. You can override the default values and specify other settings by configuring more attributes as listed in Google Login.
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, you might have to import more than one certificate. For details about which certificates you need to import, see the messages.log file.

Configuring social login for LinkedIn

Configure social login for LinkedIn.

Create a LinkedIn application.
For more information, see LinkedIn: Authenticating with OAuth 2.0.
When you configure your application, register your 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 you create the application, note the client ID and client secret, which you will add to your Liberty configuration.

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>

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. You can override the default values and specify other settings by configuring more attributes as listed in LinkedIn Login.
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, you might have to import more than one certificate. For details about which certificates you need to import, see the messages.log file.

Configuring social login for Twitter

Configure social login for Twitter.

Create a Twitter application.For more information, see Twitter Apps.
After you create the application, enable the Request email addresses from users permission. Be sure to note the consumer key and consumer secret, which you will add to your Liberty configuration.
You can optionally enable callback locking to ensure that apps cannot overwrite the callback URL. Under Settings, 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
```

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>

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. You can override the default values and specify other settings by configuring more attributes as listed in Twitter Login.
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, you might have to import more than one certificate. For details about which certificates you need to import, see the messages.log file.

Configuring 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.

Create an application for the social media platform.
For more information, see the documentation for the specific social media platform.

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

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>

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.
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, you might have to import more than one certificate. For details about which certificates you need to import, see the messages.log file.
Go back to your social media application, and configure a redirect or callback URL that points to the ID of your 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
```

Configuring social login as OpenID Connect client

Configure social login as OpenID Connect client.

Register Liberty as OpenID Connect client in OpenID Connect Provider.
For more information, 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 you create the application, note the client ID and client secret, which you will add to your Liberty configuration.

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>

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.
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, you might have to import more than one certificate. For details about which certificates you need to import, see the messages.log file.
Go back to your social media application, and configure a redirect or callback URL that points to the ID of your 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
```