JBoss.orgCommunity Documentation

Chapter 8. Social

8.1. Social Login Config
8.1.1. Enable social login
8.1.2. Social-only login
8.1.3. Social Callback URL
8.2. Facebook
8.3. GitHub
8.4. Google
8.5. Twitter
8.6. Social Provider SPI

Keycloak makes it easy to let users log in to your application using an existing account with a social network. Currently Facebook, Google and Twitter is supported with more planned for the future. There's also a Social Provider SPI that makes it relatively simple to add additional social networks.

To enable log in with a social network you need to enable social login for your realm and configure one or more social providers.

To enable login with Facebook you first have to create an app in the Facebook Developer Console. Then you need to copy the client id and secret into the Keycloak Admin Console.

  1. Log in to the Facebook Developer Console. Click Apps in the menu and select Create a New App. Use any value for Display Name and Category you want, then click the Create App button. Wait for the project to be created (this may take a while). If after creating the app you are not redirected to the app settings, click on Apps in the menu and select the app you created.

  2. Once the app has been created click on Settings in sidebar on the left. You must specify a contact email. Save your changes. Then click on Advanced. Under Security make sure Client OAuth Login is enabled. In Valid OAuth redirect URIs insert the social callback url. Scroll down and click on the Save Changes button.

  3. Click Status & Review and select YES for Do you want to make this app and all its live features available to the general public?. You will not be able to set this until you have provided a contact email in the general settings of this application.

  4. Click Basic. Copy App ID and App Secret (click show) from the Facebook Developer Console into the settings page in the Keycloak Admin Console as the Key and Secret. Then click Save in the Keycloak Admin Console to enable login with Facebook.

To enable login with GitHub you first have to create an application in GitHub Settings. Then you need to copy the client id and secret into the Keycloak Admin Console.

  1. Log in to GitHub Settings. Click the Register new application button. Use any value for Application name, Homepage URL and Application Description you want. In Authorization callback URL enter the social callback url for your realm. Click the Register application button.

  2. Copy Client ID and Client secret from the GitHub Settings into the settings page in the Keycloak Admin Console as the Key and Secret. Then click Save in the Keycloak Admin Console to enable login with Google.

To enable login with Google you first have to create a project and a client in the Google Developer Console. Then you need to copy the client id and secret into the Keycloak Admin Console.

  1. Log in to the Google Developer Console. Click the Create Project button. Use any value for Project name and Project ID you want, then click the Create button. Wait for the project to be created (this may take a while).

  2. Once the project has been created click on APIs & auth in sidebar on the left. To retrieve user profiles the Google+ API has to be enabled. Scroll down to find it in the list. If its status is OFF, click on OFF to enable it (it should move to the top of the list and the status should be ON).

  3. Now click Credentials in the sidebar on the left. Then click Create New Client ID. Select Web application as Application type. Empty the Authorized Javascript origins textarea. In Authorized redirect URI enter the social callback url for your realm. Click the Create Client ID button.

  4. Copy Client ID and Client secret from the Google Developer Console into the settings page in the Keycloak Admin Console as the Key and Secret. Then click Save in the Keycloak Admin Console to enable login with Google.

You may also want to configure how the Google Consent Screen looks when users log in to your application via Google. To do this go to Google Developer Console and click on Consent Screen in the sidebar to the left.

To enable login with Twtter you first have to create an application in the Twitter Developer Console. Then you need to copy the consumer key and secret into the Keycloak Admin Console.

  1. Log in to the Twitter Developer Console. Click the Create a new application button. Use any value for Name, Description and Website you want. Insert the social callback url in Callback URL. Then click Create your Twitter application.

  2. Now click on Settings and tick the box Allow this application to be used to Sign in with Twitter, then click on Update this Twitter application's settings.

  3. Now click API Keys tab. Copy API key and API secret from the Twitter Developer Console into the settings page in the Keycloak Admin Console as the Key and Secret. Then click Save in the Keycloak Admin Console to enable login with Twitter.

Tip

Twitter doesn't allow localhost in the redirect URI. To test on a local server replace localhost with 127.0.0.1.

Keycloak provides an SPI to make it easy to add additional social providers. This is done by implementing org.keycloak.social.SocialProvider in social/core and adding a provider configuration file (META-INF/services/org.keycloak.social.SocialProvider).

A good reference for implementing a Social Provider is the Google provider which you can find in social/google on GitHub or in the source download.