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.
socialLogin-1.0
feature. You can configure social login for one or more of the
following social media platforms.
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
andappSecurity-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
andappSecurity-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
andappSecurity-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
andappSecurity-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
andappSecurity-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
andappSecurity-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
andtokenEndpoint
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.
- The Liberty server passes the OAuth scope
value that you define on the
- 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
andappSecurity-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:
If a discovery endpoint is configured, other configured social login OIDC endpoints are ignored. All endpoints are replaced with the following discovered endpoints:<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>
issuer
,authorizationEndpoint
,tokenEndpoint
,userInfoEndpoint
, andjwksUri
.
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
andtokenEndpoint
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.
- The following example configuration defines social login for a Google application that uses
OpenID
Connect:
- 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