JBoss.org Community Documentation

- Prev
- Next

## Chapter 8. Social

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.

## 8.1. Social Login Config

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

### 8.1.1. Enable social login

To configure social login, open the `Keycloak Admin Console`, select your realm from the drop-down box in the top left corner. In the `Login Options` section click on `Social login` to set it to `ON`. Click save settings, then click on `Social` in the menu at the top.

To enable a social provider select the provider you want from the drop-down and click on `Add Provider`. Then continue to the section below that provides specific instructions for the provider you are adding.

### 8.1.2. Social-only login

It's possible to configure a realm to only allow social login. To do this open the `Keycloak Admin Console`, select your realm from the drop-down box in the top left corner. Click the `Credentials` tab, and click on the `x` next to `password` in the `Required User Credentials`. This will disable login with username and password.

### 8.1.3. Social Callback URL

There is a single callback url used by all realms and social providers. This makes it possible to share the configuration for a social network between multiple realms. An example callback url is `http://localhost:8080/auth/rest/social/callback`. To get the callback url for your server replace `http://localhost:8080` with the base address of your server. You can also find the callback url in the Keycloak Admin Console under social settings.

## 8.2. Facebook

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.

## 8.3. GitHub

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.

## 8.4. 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 on the `Consent screen` link on the sidebar menu on the left. You must specify a project name and choose an email for the consent screen. Otherwise users will get a login error. There's other things you can configure here like what the consent screen looks like. Feel free to play around with this.

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

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

## 8.5. Twitter

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

## 8.6. Social Provider SPI

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.

- PrevChapter 7. Adapters
- Top of page
- Front page
- NextChapter 9. Themes