JBoss.orgCommunity Documentation
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 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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
).
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.
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.
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.
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.
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
.
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
.
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.
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.