Last time we saw how to implement custom Keycloak themes and i.e. how it helps to prevent phishing attacks. In this guide, we’ll focus on how to enable social login using Keycloak, with a step-by-step approach to integrating platforms such as Google. Whether you’re looking to simplify authentication or enhance security, this guide will walk you through the essential steps to configure and manage social login in your application.

How does it work

The general idea of social login works is pretty straightforward as a concept: when users access our application, they can choose a social network provider, such as Google or Facebook, for authentication instead of manually defining login and passwords. Then the application sends a login request to the selected platform and once the social network confirms the user’s identity, the user is granted access to the application and is logged in immediately. 

1. The user, who is not yet authenticated, tries to access a protected resource in a client application. Application redirects the browser to Keycloak which acts as the Identity Broker. and then redirects again to one of the Identity Providers.
2. A login page is presented with a list of available identity providers (such as Google, Facebook, etc.) based on the realm’s configuration.
3. The user selects an identity provider and then is redirected to the login page of the selected one, where they can provide their credentials. The identity provider’s setup, including connection properties, has already been configured by the admin via the admin console.
4. Upon successful authentication, the user is redirected back to Keycloak with an authentication response which eventually leads to retrieval of the access token.
5. Keycloak verifies the identity and creates a new user or skips this step if the user already exists.
6. Once Keycloak successfully authenticates the user, it issues its own token to allow access to the protected resource and redirects the user back to the client application.

Key benefits

• Users can sign up and access your application in just a few clicks. Applications could use the profile data instead of having users manually enter this information into forms. This can potentially speed up and streamline the registration process.
• Social login reduces the risk of weak password and offers enhanced security features like multi-factor authentication (MFA).
• In many applications, users often don’t keep their profiles up-to-date. However, they typically ensure their information is current on their social network. So after implementing social login, we can assume that the user data we collected is reliable, as it pulls information directly from their frequently updated social profiles.
• Social network providers often offer additional user data, such as location, interests and other beyond just basic profile information. By using this we can deliver personalized content to users more effectively. This allows for more targeted interactions and content recommendations.
• The social network provider is often responsible for verifying the user’s email address. If the provider shares this information, you receive a valid email address rather than potentially fake ones that users might use when registering on web applications. Furthermore, the provider also manages the password recovery process, reducing the need for your application to handle these aspects, which simplifies user management.

The numbers generally show an improvement in conversion, and in some cases, very significant increases. In an article prepared by the Auth0 marketing team, it is stated that social login can increase registration rates by up to 50%*.

Our experience with the development of DocsQuality allows us to believe in the validity of these assumptions. After implementing social media login, we observed a several-fold increase in the number of new users.

Potential drawbacks

When considering social login methods in Keycloak, it’s important to weigh their potential drawbacks, which have led to a noticeable decline in their use recently. Here are some key concerns:

•  Although relatively rare, there’s a risk that a social login could become a single point of failure. If a user’s social media credentials are compromised, it could potentially give hackers access to your platform and any associated accounts.
• Users often worry about how social media platforms handle their data. This concern can make them reluctant to grant additional apps access to their information, leading to decreased adoption of social login features.
• Social login protocols like OpenID Connect are open and interoperable but can be challenging to implement. Even experienced developers may find integrating these standards into their applications time-consuming and complex.  

To address security concerns, it’s important to promote good social media security practices among users. Encouraging strong, unique passwords and two-factor authentication for social media accounts can help mitigate these risks and enhance the security of social login methods. Fortunately, this last one is largely addressed by Keycloak, which simplifies the implementation of these protocols. Therefore, in our example, we’ll focus on utilizing Keycloak to streamline the social login process.

Adding social login

For this example, we will use the application we prepared in the previous blog post where we customize the themes. The initial view looks like this:

Now you can log in to one of the identity provider consoles, like GitHub in this case.

Navigate to Settings -> Developer settings -> OAuth Apps. Click New OAuth App and fill out the necessary information:

• Application Name
• Homepage URL
• Authorization callback URL

The last one should be in the format <your-keycloak-domain>/auth/realms/<your-realm>/broker/github/endpoint. For testing purposes, we will try to do just local setup using 4200 and 8080 ports. Once the form is completed, click Register Application. GitHub will generate a Client ID and Client Secret.

Now go to the Keycloak admin console. In the realm, navigate to Identity Providers from the left menu. From the Add provider dropdown, select GitHub.

Paste the Client ID and Client Secret you received from GitHub. If needed, select additional options, such as storing the tokens issued by the provider (for example, for making further calls to resources that accept this token), automatically verifying email addresses, or initiating a specific authentication flow after successful login. After enabling the social provider in the console, the login page should look like this:

After clicking the GitHub button we should see a standard OAuth authorization request (this way social providers like GitHub can mark this app as a verified one and automatically allow your further login attempts).

After approving the authorization, we should be redirected to the application.

Conclusion

We walked through the entire process of registering an identity provider in Keycloak, and as you can see, it is quite simple. It’s also a great starting point for further learning OAuth protocol features, handling custom identity providers or providing Single Sign-On (SSO) solutions, which we will possibly explore in the next posts.

This approach not only simplifies the registration process and enhances security but also provides a consistent and manageable way to connect with various platforms. Although each provider may have specific configuration nuances, the overall setup process remains straightforward and largely similar across different websites. By reducing the barriers to entry for users and handling authentication efficiently and in a modern way, Keycloak enables a smoother and more secure user experience.

In our last post (Exporting accounts to federated realms: A guide to Keycloak and LDAP Integration), we explored how to easily import users into our Keycloak server from another system using the LDAP protocol. This time, we’ll take a closer look at the visual aspect of this solution by customizing the stylesheet for our application and allowing the end-user to get a unique feeling when visiting our site. 

Built-in themes

Keycloak offers extensive customization options for the user interface and appearance through its “themes.” Customizing themes allows us to tailor the look and feel of their applications to meet specific needs, not only reinforcing the brand’s visual identity. 

Keycloak comes with several pre-built themes bundled within its distribution. The available themes include the base theme, which provides HTML templates and message bundles that all other themes, including custom ones, typically inherit from. The keycloak theme contains images and stylesheets for enhancing page CSS and is used by default if no custom theme is provided. Additionally, the keycloak.v2 theme is a React-based theme designed for the new Admin Console, with the older console set for deprecation. Modifying existing themes is not recommended, instead creating a new theme that extends one of them is the preferred approach.

For a complete customization, copying the contents from the base folder is ideal, but for partial modification, it’s more practical to start with the contents from the keycloak directory. As we’ve already said, only the parts of the theme that need to be overridden should be included in the new custom folder.

FreeMarker Template 

FTL themes in Keycloak refer to templates written in Freemarker Template Language that define the look and feel of various pages and emails in Keycloak. These themes allow you to customize everything from login pages to error messages and account management interfaces.

Keycloak themes are typically organized into four main categories:

1. Login: Customizes the appearance of login, registration, and password reset pages.
2. Account: Modifies the user account management interface.
3. Email: Tailors the content and appearance of emails sent by Keycloak (e.g., verification emails, password reset emails).
4. Admin: Allows customization of the Keycloak Admin Console.

Let’s take a look at a few quite relevant templates:

• login.ftl – the most commonly customized template in Keycloak. It is responsible for rendering the login page where users enter their credentials (username/email and password) to access your application.

• register.ftl – used for the registration page where new users can create an account.

• login-reset-password.ftl – used when a user initiates the password reset process.

• login-update-password.ftl – used when a user is required to update their password, either after a successful password reset or due to a policy requirement (e.g., periodic password changes).

Theme properties

In addition to the HTML templates, message bundles, images and stylesheets, a Keycloak theme includes a few more elements like theme properties. Each theme type has its own configuration file. For instance, consider the theme.properties file from the login theme:

parent=keycloak
import=common/keycloak

styles=css/login.css css/tile.css
stylesCommon=web_modules/@fortawesome/fontawesome-free/css/icons/all.css 
web_modules/@patternfly/react-core/dist/styles/base.css 
web_modules/@patternfly/react-core/dist/styles/app.css 
node_modules/patternfly/dist/css/patternfly.min.css 
node_modules/patternfly/dist/css/patternfly-additions.min.css lib/pficon/pficon.css

This file shows that the theme inherits from the base theme to utilize its HTML templates and message bundles. It also imports the common theme to include additional styles. Beyond that, the theme specifies its own stylesheet, css/login.css.

Messages and i18n

Keycloak supports internationalization in themes by allowing you to create language-specific properties files, which store translations for text used in templates. These files, named messages_<locale>.properties contain key-value pairs where the key represents a text element, and the value is its translation in the target language. In our FTL templates, we reference these keys using the ${msg()} directive, allowing our application to automatically display the appropriate translation.

It should refer to the language currently selected by the user. Keycloak determines the language based on browser settings, provided that the language is configured in the system.

For example, on the login page, you can provide a translation for the header “Sign in to your account,” which may not be translated by default in languages like Dutch or Spanish. To do this, you can edit the loginAccountTitle field in the messages file, adding the appropriate translation for each language. This way, when users select their language, they will see the translated version in the login interface.

messages.nl
loginAccountTitle=Inloggen

messages.es
loginAccountTitle=Iniciar sesi\u00F3n

messages.en
loginAccountTitle=Sign In

The final step is to configure the internationalization settings for your realm according to the provided screenshot. This ensures that the translations you added, such as for the loginAccountTitle field, are correctly applied based on the user’s selected language.

The original English version and the final result for the Spanish and Dutch versions is shown below.

Customizing our theme

Before diving into theme customization, ensure you have a working Keycloak instance. You’ll need access to the Keycloak server files and administrative privileges to apply the theme. If you’re running Keycloak in a Docker container, you can use a volume mount to access the theme files on your local machine.

Create a directory structure for your custom theme by following the example below. The default theme files are located in the Keycloak server distribution under themes/keycloak/login. To get started, copy these default theme files from the Keycloak distribution to your custom theme directory.

We’ll start with the basic login page, as shown below:

Locate and edit the CSS file that controls the styling of the login page. This is typically named login.css and is found in the resources/css directory of your custom theme. Now we can change background property and provide a custom .png file.

.login-pf-page::before {
content: "";
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 100%;  
opacity: 1;
background: rgba(255, 255, 255, 0.4) url("../img/fb-background.png") no-repeat;
background-size: cover;
     z-index: -1;
}

In addition to changing the background, we can also modify the color of the top border of the login screen and the color of the login button. Then we can add a custom logo. This can be done by modifying the following classes:

pf-m-primary {
color: black !important;
background-color: #B646AE !important;
}

.card-pf {
margin: 0 auto;
box-shadow: var(--pf-global--BoxShadow--lg);
padding: 0 20px;
max-width: 500px;
border-top: 4px solid;
border-color: #B646AE;
background-color: #fff;
}

#kc-header-wrapper::before {
content: "";
position: relative;
margin: auto;
display: block;
width: 200px;
background: url("../img/fb-logo.png") no-repeat;
background-size: auto;
}

The last step will be to activate the custom theme in the administrator console for a specific realm.

After the above changes, the final effect should look like this:

However, the final result can vary depending on the use of different image files and color definitions. By customizing these elements, you can easily achieve a unique appearance that aligns with your branding and design preferences. Just with different resources it can look like this:

As you can see now, customizing the Keycloak theme is pretty straightforward.

So far, we discussed how to customize Keycloak themes by adjusting visual elements. We covered the basics of Keycloak’s built-in themes, which include options for customizing the login page. In most cases, the process involves copying default theme files, modifying CSS for styling changes like background images and button colors, and editing FreeMarker templates for layout adjustments. Additionally, we explored how to use the theme.properties file to configure your custom theme. Now we have some basic tools to modify Keycloak’s appearance to better fit the brand and user needs.

Summary

• You can fully customize the login page to ensure it doesn’t resemble a Keycloak default theme. This not only improves the user experience but also helps users easily distinguish the legitimate login page from potential phishing attempts.
• Keycloak also allows you to customize the content and layout of email (i.e. password reset templates). By making unique, branded content you can help users recognize legitimate password reset requests, reducing the risk of falling victim to phishing attacks that mimic these emails.
• Beyond visual customization, themes support internationalization, enabling you to provide users with a familiar experience in their native language. This can include translating all text on login pages and in emails to the appropriate language. It enhances usability for global users.

Overall, customizing themes offers a range of possibilities to enhance the user experience and security of your IAM system.

Do you need assistance with Keycloak implementation, updates, or training? Contact me

Andrzej Chybicki 

CEO, Inero Software Sp. z o. o.
andy@inero-software.com
Phone: +48 695 875 588