Server Administration Guide

Every UI screen is internationalized in Keycloak. The default language is English, but if you turn on the Internationalization switch on the Theme tab you can choose which locales you want to support and what the default locale will be. The next time a user logs in, they will be able to choose a language on the login page to use for the login screens, User Account Management UI, and Admin Console. The Server Developer Guide explains how you can offer additional languages. All internationalized texts which are provided by the theme can be overwritten by realm-specific texts on the Localization tab.

If a user doesn’t have a password, or if the password has been deleted, the Set Password section will be shown on the page.

To create a password for a user, type in a new one. Click on the Set Password button after you’ve typed everything in. If the Temporary switch is on, this new password can only be used once and the user will be asked to change their password after they have logged in.

If a user already has a password, it can be reset in the Reset Password section.

Alternatively, if you have email set up, you can send an email to the user that asks them to reset their password. Choose Update Password from the Reset Actions list box and click Send Email. You can optionally set the validity of the e-mail link which defaults to the one preset in Tokens tab in the realm settings. The sent email contains a link that will bring the user to the update password screen.

Note that a user can only have a single credential of type password.

You cannot configure other types of credentials for a specific user within the Admin Console. This is the responsibility of the user. You can only delete credentials for a user on the Credentials tab, for example if the user has lost an OTP device, or if a credential has been compromised.

You can also specify required actions that will be added to an account whenever a new user is created, i.e. through the Add User button the user list screen, or via the user registration link on the login page. To specify the default required actions go to the Authentication left menu item and click on the Required Actions tab.

Simply click the checkbox in the Default Action column of the required actions that you want to be executed when a brand new user logs in.

Many organizations have a requirement that when a new user logs in for the first time, they need to agree to the terms and conditions of the website. Keycloak has this functionality implemented as a required action, but it requires some configuration. For one, you have to go to the Required Actions tab described earlier and enable the Terms and Conditions action. You must also edit the terms.ftl file in the base login theme. See the Server Developer Guide for more information on extending and creating themes.

To safeguard registration against bots, Keycloak has integration with Google reCAPTCHA. To enable this you need to first go to Google Recaptcha Website and create an API key so that you can get your reCAPTCHA site key and secret. (FYI, localhost works by default so you don’t have to specify a domain).

Next, there are a few steps you need to perform in the Keycloak Admin Console. Click the Authentication left menu item and go to the Flows tab. Select the Registration flow from the drop down list on this page.

Set the 'reCAPTCHA' requirement to Required by clicking the appropriate radio button. This will enable reCAPTCHA on the screen. Next, you have to enter in the reCAPTCHA site key and secret that you generated at the Google reCAPTCHA Website. Click on the 'Actions' button that is to the right of the reCAPTCHA flow entry, then "Config" link, and enter in the reCAPTCHA site key and secret on this config page.

The final step you have to do is to change some default HTTP response headers that Keycloak sets. Keycloak will prevent a website from including any login page within an iframe. This is to prevent clickjacking attacks. You need to authorize Google to use the registration page within an iframe. Go to the Realm Settings left menu item and then go to the Security Defenses tab. You will need to add https://www.google.com to the values of both the X-Frame-Options and Content-Security-Policy headers.

Once you do this, reCAPTCHA should show up on your registration page. You may want to edit register.ftl in your login theme to muck around with the placement and styling of the reCAPTCHA button. See the Server Developer Guide for more information on extending and creating themes.

In addition to enabling the declarative_user_profile feature, you should enable User Profile for a realm. To do that, click on the Realm Settings link on the left side menu and turn on the User Profile Enabled switch.

Once you enable it and click on the Save button, you can access the User Profile tab from where you can manage the configuration for user attributes.

By enabling the user profile for a realm, Keycloak is going to impose additional constraints on how attributes are managed based on the user profile configuration. In summary, here is the list of what you should expect when the feature is enabled:

In the next topics, we’ll be exploring how to manage the user profile configuration and how it affects your realm.

The user profile configuration is managed on a per-realm basis. For that, click on the Realm Settings link on the left side menu and then click on the User Profile tab.

In the Attributes sub-tab you have a list of the attributes currently associated with the user profile. By default, the configuration is created based on the user root attributes and each attribute is configured with some defaults in terms of validation and permissioning.

In the Attribute Groups sub-tab you can manage attribute groups. An attribute group allows you to correlate attributes so that they are displayed together when rendering user facing forms.

In the JSON Editor sub-tab you can view and edit the configuration using a well-defined JSON schema. Any change you make when at any other tab are reflected in the JSON configuration shown at this tab.

In the next section, you are going to learn how to manage the configuration from the Attributes sub-tab.

At the Attributes sub-tab you can create, edit, and delete the attributes associated with the user profile.

To define a new attribute and associate it with the user profile, click on the Create button in the top-right corner of the attribute listing.

When configuring the attribute you can define the following settings:

At the Attribute Groups sub-tab you can create, edit, and delete attribute groups. An attribute group allows you to define a container for correlated attributes so that they are rendered together when at the user-facing forms.

To create a new group, click on the Create button in the top-right corner of the attribute groups listing.

When configuring the group you can define the following settings:

The user profile configuration is stored using a well-defined JSON schema. You can choose from editing the user profile configuration directly by clicking on the JSON Editor sub-tab.

The JSON schema is defined as follows:

The schema supports as many attributes as you need.

For each attribute you should define a name and, optionally, the required, permission, and the annotations settings.

One of the main capabilities of User Profile is the possibility to dynamically render user-facing forms based on attributes metadata. When you have the feature enabled to your realm, forms like registration and update profile are rendered using specific theme templates to dynamically render pages based on the user profile configuration.

That said, you shouldn’t need to customize templates at all if the default rendering mechanisms serves to your needs. In case you still need customizations to themes, here are the templates you should be looking at:

The default rendering mechanism provides the following capabilities:

In order to make sure user profiles are in compliance with the configuration, administrators may use the VerifyProfile required action to eventually force users to update their profiles when authenticating to Keycloak.

When enabled, the VerifyProfile action is going to perform the following steps when the user is authenticating:

By default, the VerifyProfile action is disabled. To enabled it, click on the Authentication link on the left side menu and then click on the Required Actions tab. At this tab, click on the Register button and select the VerifyProfile action.

Before enabling the User Profile capabilities to a realm, there are some important considerations you should be aware of. By providing a single place to manage attribute metadata, the feature is very strict about the attributes that can be set to users and how they are managed.

In terms of user management, administrators are able to manage only the attributes defined in the user profile configuration. Any other attribute set to the user and not yet defined in the user profile configuration won’t be accessible. It is recommended to update your user profile configuration with all the user attributes you want to expose either to users or administrators.

The same recommendation applies for those accessing the User REST API to query user information.

In regards to Keycloak internal user attributes such as LDAP_ID, LDAP_ENTRY_DN, or KERBEROS_PRINCIPAL, if you want to be able to access those attributes you should have them as attributes in your user profile configuration. The recommendation is to mark these attributes as viewable only to administrators so that you can look at them when managing the user attributes through the administration console or querying users via User API.

In regards to theming, if you already have customizations to the legacy templates (those hardcoded with user root attributes) your custom templates won’t be used when rendering user-facing forms but the new templates that render these forms dynamically. Ideally, you should avoid having any customizations to templates and try to stick with the behavior provided by these new templates to dynamically render forms for you. If they are still not enough to address your requirements, you can either customize them or provide us with any feedback so that we discuss whether it makes sense to enhance the new templates.

Here’s an explanation of each policy type:

There are two different algorithms to choose from for your OTP generators. Time Based (TOTP) and Counter Based (HOTP). For TOTP, your token generator will hash the current time and a shared secret. The server validates the OTP by comparing all the hashes within a certain window of time to the submitted value. So, TOTPs are valid only for a short window of time (usually 30 seconds). For HOTP a shared counter is used instead of the current time. The server increments the counter with each successful OTP login. So, valid OTPs only change after a successful login.

TOTP is considered a little more secure because the matchable OTP is only valid for a short window of time while the OTP for HOTP can be valid for an indeterminate amount of time. HOTP is much more user friendly as the user won’t have to hurry to enter in their OTP before the time interval is up. With the way Keycloak has implemented TOTP this distinction becomes a little more blurry. HOTP requires a database update every time the server wants to increment the counter. This can be a performance drain on the authentication server when there is heavy load. So, to provide a more efficient alternative, TOTP does not remember passwords used. This bypasses the need to do any DB updates, but the downside is that TOTPs can be re-used in the valid time interval. For future versions of Keycloak it is planned that you will be able to configure whether TOTP checks older OTPs in the time interval.

Keycloak comes with a certain number of built-in flows. These flows cannot be modified, but the requirements can be modified to suit your needs.

This section does a walk-through of the built-in browser login flow. In the left drop-down list select browser to come to the screen shown below:

If you hover over the tooltip (the tiny question mark) to the right of the flow selection list, this will describe what the flow is and does.

The Auth Type column is the name of authentication or action that will be executed. If an authentication is indented this means it is in a sub-flow and may or may not be executed depending on the behavior of its parent. The Requirement column is a set of radio buttons which define whether or not the action will execute. Let’s describe what each radio button means in this context.

This section explains in greater depth how flows work, and how to create your own flows. Note that there are important functionality and security considerations when designing your own flow. A badly created flow could either let no one log in, let users in with less verification than you would like, or simply result in an error.

To create a flow, you can either:

When creating a new flow, you will have to create a top level flow

With the following options:

Once the flow is created, in addition to the New and Copy buttons, you now have, Delete, Add execution and Add flow.

What a flow finally does is determined by the structure of the flow and sub-flows, the executions in those flows, and the requirements set on the sub-flows and the executions.

Executions can be added with the Add execution button. Executions can have a wide variety of actions, from sending a reset email to validating an OTP. If you hover over the tooltip (the tiny question mark) next to Provider, this will describe what the execution does.

These can be divided into automatic executions and interactive executions. Automatic executions are similar to the Cookie execution, and will automatically perform their action when they are encountered in the flow. Interactive executions will halt the flow, usually to get some user input. Executions that execute successfully will get the success status. This is important, because this is part of whether a flow is successful or not. For example, an empty Browser flow would not allow anyone to log in. For that it would need at least one execution that successfully evaluates, for example a Username Password Form that is correctly filled and submitted.

Sub-flows can be added in top level flow with the Add flow button, which opens a Create Execution Flow page that is very similar to the Create Top Level Form page. The only difference is that the Flow Type can be either generic (like before), or form. The form type is used to construct a sub-flow that generates a single form for the user, like what is done for the built-in Registration flow. Sub-flows are a special type of execution that evaluate as successful depending on how the executions they contain evaluate (and this includes the evaluation of their contained sub-flows). And the logic of this evaluation depends on the Requirement of each execution and sub-flow.

Fully understanding this requires a more complete explanation of how requirements work when evaluating a flow, and this also applies to sub-flows. Refer to the execution requirements section above for more details.

Note that after adding an execution, you should check that the Requirement is set to the correct value. Even if there is only a single possible Requirement, it can happen that it is not set.

When constructing a flow, all elements added to the flow will have an Actions menu on the right-hand side. All elements added to the flow have a Delete option in this menu to remove it from the flow. Executions can contain a Config menu option to configure the execution, as is the case for the Identity Provider Redirector. Sub-flows can also have executions and sub-flows added to them, with their Add execution and Add flow menu options.

Finally, since the order of execution is important, you can move executions and sub-flows up and down within their respective flows with the up and down buttons that are set to left of their name.

To illustrate the creation of flows, this section describes the creation of a more advanced browser login flow. The purpose of this flow is to allow a user to choose between logging in in a password-less manner using WebAuthn, and a two-factor authentication with password and OTP. The flow to create is similar to the standard browser login, but diverges when reaching the username selection. Instead of copying the flow however, you’ll be creating the flow from the start:

The Username form is similar to "Browser" flow’s Username Password Form, but only asks for a username, allowing a user to perform a password-less login. However, note that this inevitably allows a user enumeration attack on your Keycloak server. This is an unavoidable security risk for the convenience, so the flow should make sure that an attacker cannot just have to guess a password to be able to enter.

The final flow that is produced is the following:

After entering the username, the way this flow works is the following:

It is important to note that since the WebAuthn Passwordless execution is set to Alternative instead of Required, this flow will never ask the user to register a WebAuthn credential. For a user to have a Webauthn credential, that user must have a required action added by an administrator. This is done first by making sure that the Webauthn Register Passwordless required action is enabled in the realm (see the WebAuthn documentation), and then by setting the required action by using the Credential Reset part of a user’s Credentials management menu.

Creating a more advanced flow such as this one can have some subtle side effects. For example, if you were to enable the ability to reset the password for the user, then this would be accessible from the password form. In the default "Reset Credentials" flow, the user has to enter his username. Since he’s already entered his username earlier in the "Browser Password-less" flow, this would be unnecessary for Keycloak, and a sub-optimal in terms of user experience. To correct this, you could:

This is platform dependent. Exact steps depend on your OS and the Kerberos vendor you’re going to use. Consult Windows Active Directory, MIT Kerberos and your OS documentation for how exactly to setup and configure Kerberos server.

At least you will need to:

Then add HTTP principal and export his key to a keytab file with the commands like:

The Keytab file /tmp/http.keytab will need to be accessible on the host where Keycloak server will be running.

You need to install a kerberos client on your machine. This is also platform dependent. If you are on Fedora, Ubuntu or RHEL, you can install the package freeipa-client, which contains a Kerberos client and several other utilities. Configure the kerberos client (on Linux it’s in file /etc/krb5.conf ). You need to put your Kerberos realm and at least configure the HTTP domains your server will be running on. For the example realm MYDOMAIN.ORG you may configure the domain_realm section like this:

Next you need to export the keytab file with the HTTP principal and make sure the file is accessible to the process under which Keycloak server is running. For production, it’s ideal if it’s readable just by this process and not by someone else. For the MIT Kerberos example above, we already exported keytab to /tmp/http.keytab . If your KDC and Keycloak are running on same host, you have that file already available.

Clients need to install kerberos client and setup krb5.conf as described above. Additionally they need to enable SPNEGO login support in their browser. See configuring Firefox for Kerberos if you are using that browser. URI .mydomain.org must be allowed in the network.negotiate-auth.trusted-uris config option.

In a Windows domain, clients usually don’t need to configure anything special as IE is already able to participate in SPNEGO authentication for the Windows domain.

For easier testing with Kerberos, we provided some example setups to test.

Kerberos 5 supports the concept of credential delegation. In this scenario, your applications may want access to the Kerberos ticket so that they can re-use it to interact with other services secured by Kerberos. Since the SPNEGO protocol is processed in the Keycloak server, you have to propagate the GSS credential to your application within the OpenID Connect token claim or a SAML assertion attribute that is transmitted to your application from the Keycloak server. To have this claim inserted into the token or assertion, each application will need to enable the built-in protocol mapper called gss delegation credential. This is enabled in the Mappers tab of the application’s client page. See Protocol Mappers chapter for more details.

Applications will need to deserialize the claim it receives from Keycloak before it can use it to make GSS calls against other services. Once you deserialize the credential from the access token to the GSSCredential object, the GSSContext will need to be created with this credential passed to the method GSSManager.createContext for example like this:

We have an example, that shows this in detail. It’s in examples/kerberos in the Keycloak example distribution or demo distribution download. You can also check the example sources directly here .

Note that you also need to configure forwardable kerberos tickets in krb5.conf file and add support for delegated credentials to your browser.

In the Kerberos V5 protocol, the realm is a set of Kerberos principals defined in the Kerberos database (typically LDAP server). The Kerberos protocol has a concept of cross-realm trust. For example, if there are 2 kerberos realms A and B, the cross-realm trust will allow the users from realm A to access resources (services) of realm B. This means that realm B trusts the realm A.

The Keycloak server has support for cross-realm trust. There are few things which need to be done to achieve this:

If you have issues, we recommend that you enable additional logging to debug the problem:

The regular expression filtering is applicable only if the Identity Source is set to either Match SubjectDN using regular expression or Match IssuerDN using regular expression.

The following sections describe how to configure WildFly/Undertow and the Keycloak Server to enable X.509 client certificate authentication.

When an HTTP request is sent directly to Keycloak server, the WildFly undertow subsystem will establish an SSL handshake and extract the client certificate. The client certificate will be then saved to the attribute javax.servlet.request.X509Certificate of the HTTP request, as specified in the servlet specification. The Keycloak X509 authenticator will be then able to lookup the certificate from this attribute.

However, when the Keycloak server listens to HTTP requests behind a load balancer or reverse proxy, it may be the proxy server which extracts the client certificate and establishes the mutual SSL connection. A reverse proxy usually puts the authenticated client certificate in the HTTP header of the underlying request and forwards it to the back end Keycloak server. In this case, Keycloak must be able to look up the X.509 certificate chain from the HTTP headers instead of from the attribute of HTTP request, as is done for Undertow.

If Keycloak is behind a reverse proxy, you usually need to configure alternative provider of the x509cert-lookup SPI in KEYCLOAK_HOME/standalone/configuration/standalone.xml. Along with the default provider, which looks up the certificate from the HTTP header, we also have two additional built-in providers: haproxy and apache, which are described next.

The setup procedure of WebAuthn support for 2FA is the following :

After registering a WebAuthn authenticator, the user carries out the following operations assuming that authentication flow configuration above with the conditional subflow using WebAuthn Authenticator was used:

When registering a WebAuthn authenticator, Keycloak verifies an attestation statement generated by this WebAuthn authenticator. On this verification process, Keycloak validates this attestation statement’s trustworthiness. It requires trust anchor’s certificates. Keycloak uses the Keycloak truststore so that you need to import these certificates onto it in advance.

If you want to omit this attestation statement trustworthiness validation, please disable this truststore or set the WebAuthn policy’s configuration item "Attestation Conveyance Preference" to "none".

WebAuthn is often used for two-factor authentication, however it can be desired to use it also as first factor authentication. In this case, a user with passwordless WebAuthn credential will be able to authenticate to Keycloak without a password. Keycloak allows to use WebAuthn as both the passwordless and two-factor authentication mechanism in the context of a single realm and even in the context of a single authentication flow.

Administrator may typically require that Security Keys registered by users for the WebAuthn passwordless authentication must meet different (usually stronger) requirements. For example, those security keys may require users to authenticate to that security key using a PIN, or the security key should be attested with stronger certificate authority.

Because of this situation, Keycloak allows administrator to configure separate WebAuthn Passwordless Policy. There is a separate required action of type Webauthn Register Passwordless and separate authenticator of type WebAuthn Passwordless Authenticator.

You can allow or deny access to resources in a conditional flow. The two authenticators Deny Access and Allow Access control access to the resources by conditions.

Here is an example how to deny access to all users who do not have the role role1 and show an error message defined by a property deny-role1. This example includes Condition - User Role and Deny Access executions.

The last thing is defining the property with an error message in the login theme messages_en.properties (for English):

OIDC has different ways for a client or application to authenticate a user and receive an identity and access token. Which path you use depends greatly on the type of application or client requesting access. All of these flows are described in the OIDC and OAuth 2.0 specifications so only a brief overview will be provided here.

OIDC has three different specifications relevant to logout mechanisms, all of these are currently in draft status:

Again since all of this is described in the OIDC specification we will only give a brief overview here.

Here’s a list of OIDC endpoints that the Keycloak publishes. These URLs are useful if you are using a non-Keycloak client adapter to talk OIDC with the auth server. These are all relative URLs and the root of the URL being the HTTP(S) protocol, hostname, and usually path prefixed with /auth, for example https://localhost:8080/auth.

You can also find these endpoints under "OpenID Endpoint Configuration" in your realm settings.

In all of these replace {realm-name} with the name of the realm.

SAML defines a few different ways to exchange XML documents when executing the authentication protocol. The Redirect and Post bindings cover browser based applications. The ECP binding covers REST invocations. There are other binding types but Keycloak only supports those three.

Keycloak really only has one endpoint for all SAML requests.

http(s)://authserver.host/auth/realms/{realm-name}/protocol/saml

All bindings use this endpoint.

The Docker API documentation best describes and illustrates this process, however a brief summary will be given below from the perspective of the Keycloak authentication server.

Keycloak really only has one endpoint for all Docker auth v2 requests.

http(s)://authserver.host/auth/realms/{realm-name}/protocol/docker-v2

OAuth 2.0 Mutual TLS Certificate Bound Access Tokens Enabled

Mutual TLS binds an access token and a refresh token with a client certificate exchanged during TLS handshake. This prevents an attacker who finds a way to steal these tokens from exercising the tokens. This type of token is called a holder-of-key token. Unlike bearer tokens, the recipient of a holder-of-key token can verify whether the sender of the token is legitimate.

If the following conditions are satisfied on a token request, Keycloak will bind an access token and a refresh token with a client certificate and issue them as holder-of-key tokens. If all conditions are not met, Keycloak rejects the token request.

To enable mutual TLS in Keycloak, see Enable mutual SSL in WildFly.

In the following cases, Keycloak will verify the client sending the access token or the refresh token; if verification fails, Keycloak rejects the token.

Please see Mutual TLS Client Certificate Bound Access Tokens in the OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens for more details.

Proof Key for Code Exchange (PKCE)

When an attacker steals an authorization code that was issued to a legitimate client, PKCE prevents the attacker from receiving the tokens that apply to that code.

The administrator can select the following three options:

Proof Key for Code Exchange Code Challenge Method

Please see RFC 7636 Proof Key for Code Exchange by OAuth Public Clients for more details.

Signed and Encrypted ID Token Support

Keycloak can encrypt ID token according to the Json Web Encryption (JWE) specification. The administrator can determine whether encrypting ID token or not per client. This feature is disabled as default.

The key for encrypting ID token is called Content Encryption Key (CEK). Keycloak and a client need to negotiate which CEK is used and how to deliver it. The way to do so is called Key Management Mode.

JWE specification determines 5 types of Key Management Mode. Keycloak supports Key Encryption among them.

In Key Encryption, the client generates a key pair of asymmetric cryptography. The public key is used to encrypt CEK. Keycloak generates CEK per ID token, encrypts the ID token by this generated CEK and encrypts this CEK by this client’s public key. The client decrypts this encrypted CEK by their private key, and decrypt the ID token by decrypted CEK. Therefore, any party other than the client is not able to decrypt ID token.

The client needs to pass their public key for encrypting CEK onto Keycloak. Keycloak supports downloading public keys from the URL the client provides. The client needs to provide their public keys according to Json Web Keys (JWK) specification. The way to do so is defined in Signed JWT of Confidential Client Credentials. The detailed procedure is as follows:

Key Encryption’s algorithms are defined in the Json Web Algorithm (JWA) specification. Keycloak supports RSAES-PKCS1-v1_5(RSA1_5), RSAES OAEP using default parameters (RSA-OAEP), and RSAES OAEP 256 using SHA-256 and MFG1 (RSA-OAEP-256). The detailed procedure to select this algorithm is as follows:

ID token encryption algorithms by CEK are also defined in the JWA specification. Keycloak supports AES_CBC_HMAC_SHA2 algorithms and AES GCM algorithms. The detailed procedure to select this algorithm is as follows:

OAuth 2.0 Pushed Authorization Requests

Basic features of OAuth 2.0 Pushed Authorization Requests has been supported.

For more details about PAR, see PAR Specification.

There are two configuration parameters. The former can be set up on Advanced Settings per client for activating and deactivating PAR.

The latter can be set up on Realm Setting’s Token tab per realm for determining lifetime of PAR’s Request URI.

If you’ve set the client’s access type to confidential in the client’s Settings tab, a new Credentials tab will show up. Note that the Credentials tab only shows up after you’ve clicked the Save button at the bottom of the settings screen with a confidential access type. As part of dealing with this type of client you have to configure the client’s credentials.

The Client Authenticator list box specifies the type of credential you are going to use for your confidential client. It defaults to client ID and secret. The secret is automatically generated for you and the Regenerate Secret button allows you to recreate this secret if you want or need to.

Alternatively, you can opt to use a signed Json Web Token (JWT) or x509 certificate validation (also called Mutual TLS) instead of a secret.

When choosing this credential type you will have to also generate a private key and certificate for the client in the tab Keys. The private key will be used to sign the JWT, while the certificate is used by the server to verify the signature.

Click on the Generate new keys and certificate button to start this process.

When you generate these keys, Keycloak will store the certificate, and you’ll need to download the private key and certificate for your client to use. Pick the archive format you want and specify the password for the private key and store.

You can also opt to generate these via an external tool and just import the client’s certificate.

There are multiple formats you can import from, just choose the archive format you have the certificate stored in, select the file, and click the Import button.

Finally note that you don’t even need to import certificate if you choose to Use JWKS URL . In that case, you can provide the URL where client publishes its public key in JWK format. This is flexible because when client changes its keys, Keycloak will automatically download them without need to re-import anything on Keycloak side.

If you use client secured by Keycloak adapter, you can configure the JWKS URL like https://myhost.com/myapp/k_jwks assuming that https://myhost.com/myapp is the root URL of your client application. See Server Developer Guide for additional details.

If you select this option in the Client Authenticator list box, you can use a JWT signed by client secret instead of the private key.

This client secret will be used to sign the JWT by the client.

By enabling this option Keycloak will validate if the client uses proper X509 certificate during the TLS Handshake.

The validator checks also the certificate’s Subject DN field with configured regexp validation expression. For some use cases, it is sufficient to accept all certificates. In that case, you can use (.*?)(?:$) expression.

There are two ways for Keycloak to obtain the Client ID from the request. The first option is the client_id parameter in the query (described in Section 2.2 of the OAuth 2.0 Specification). The second option is to supply client_id as a form parameter.

Each OIDC client has a built-in service account which allows it to obtain an access token. This is covered in the OAuth 2.0 specifiation under Client Credentials Grant. To use this feature you must set the Access Type of your client to confidential. When you do this, the Service Accounts Enabled switch will appear. You need to turn on this switch. Also make sure that you have configured your client credentials.

To use it you must have registered a valid confidential Client and you need to check the switch Service Accounts Enabled in Keycloak admin console for this client. In tab Service Account Roles you can configure the roles available to the service account retrieved on behalf of this client. Remember that you must have the roles available in Role Scope Mappings (tab Scope) of this client as well, unless you have Full Scope Allowed on. As in a normal login, roles from access token are the intersection of:

The REST URL to invoke on is /auth/realms/{realm-name}/protocol/openid-connect/token. Invoking on this URL is a POST request and requires you to post the client credentials. By default, client credentials are represented by clientId and clientSecret of the client in Authorization: Basic header, but you can also authenticate the client with a signed JWT assertion or any other custom mechanism for client authentication. You also need to use the parameter grant_type=client_credentials as per the OAuth2 specification.

For example the POST invocation to retrieve a service account can look like this:

The response would be this standard JSON document from the OAuth 2.0 specification.

There is the only access token returned by default. There is no refresh token returned and there is also no user session created on the Keycloak side upon successful authentication by default. Due the lack of refresh token, there is a need to re-authenticate when access token expires, however this does not mean any additional overhead on Keycloak server side due the fact that sessions are not created by default.

Due to this, there is no need for logout, however issued access tokens can be revoked by sending request to the OAuth2 Revocation Endpoint described in the OpenID Connect Endpoints section.

The typical environment where the Keycloak is deployed generally consists of a set of confidential or public client applications (frontend client applications) which use Keycloak for authentication.

There are also services (called Resource Servers in the OAuth 2 specification), which serve requests from frontend client applications and provide resources. These services typically require an Access token (Bearer token) to be sent to them to authenticate for a particular request. This token was previously obtained by the frontend application when it tries to log in against Keycloak.

In the environment where the trust among services is low, you may encounter this scenario:

This flow may not be an issue in many environments with the high level of trust among services. However in other environments, where the trust among services is lower, this can be problematic.

To prevent any misuse of the access token as in the example above, it is recommended to limit Audience on the token and configure your services to verify the audience on the token. If this is done, the flow above will change, like this:

If the client wants to invoke the good-service later, it will need to obtain another token by issuing the SSO login with the scope=good-service. The returned token will then contain good-service as an audience:

and can be used to invoke good-service.

IDP Initiated Login is a feature that allows you to set up an endpoint on the Keycloak server that will log you into a specific application/client. In the Settings tab for your client, you need to specify the IDP Initiated SSO URL Name. This is a simple string with no whitespace in it. After this you can reference your client at the following URL: root/auth/realms/{realm}/protocol/saml/clients/{url-name}

The IDP initiated login implementation prefers POST over REDIRECT binding (check saml bindings for more information). Therefore the final binding and SP URL are selected in the following way:

If your client requires a special relay state, you can also configure this on the Settings tab in the IDP Initiated SSO Relay State field. Alternatively, browsers can specify the relay state in a RelayState query parameter, i.e. root/auth/realms/{realm}/protocol/saml/clients/{url-name}?RelayState=thestate.

When using identity brokering, it is possible to set up an IDP Initiated Login for a client from an external IDP. The actual client is set up for IDP Initiated Login at broker IDP as described above. The external IDP has to set up the client for application IDP Initiated Login that will point to a special URL pointing to the broker and representing IDP Initiated Login endpoint for a selected client at the brokering IDP. This means that in client settings at the external IDP:

Please note that you can import basic client settings from the brokering IDP into client settings of the external IDP - just use SP Descriptor available from the settings of the identity provider in the brokering IDP, and add clients/client-id to the endpoint URL.

Instead of manually registering a SAML 2.0 client, you can import it via a standard SAML Entity Descriptor XML file. There is an Import option on the Add Client page.

Click the Select File button and load your entity descriptor file. You should review all the information there to make sure everything is set up correctly.

Some SAML client adapters like mod-auth-mellon need the XML Entity Descriptor for the IDP. You can obtain this by going to this public URL: root/auth/realms/{realm}/protocol/saml/descriptor

Mapper implementations have priority order. This priority order is not the configuration property of the mapper; rather, it is the property of the concrete implementation of the mapper.

Mappers are sorted in the admin console by the order in the list of mappers and the changes in the token or assertion will be applied using that order with the lowest being applied first. This means that implementations which are dependent on other implementations are processed in the needed order.

For example, when we first want to compute the roles which will be included with a token, we first resolve audiences based on those roles. Then, we process a JavaScript script that uses the roles and audiences already available in the token.

User session details are defined via mappers and depend on various criteria. User session details are automatically included when you use or enable a feature on a client. You can also click the Add builtin button to include session details.

Impersonated user sessions provide the following details:

Service account sessions provide the following details:

The Script Mapper allows you to map claims to tokens by running a user-defined JavaScript code. For more details about how to deploy scripts to the server, please take a look at JavaScript Providers.

Once you have your scripts deployed, you should be able to select the scripts you deployed from the list of available mappers.

When you are creating the client scope, you must choose the Protocol. Only the clients which use same protocol can then be linked with this client scope.

Once you have created new realm, you can see that there is a list of pre-defined (builtin) client scopes in the menu.

The client scope, offline_access, is useful when client wants to obtain offline tokens. Learn about offline tokens in the Offline Access section or in the OpenID Connect specification, where scope parameter is defined with the value offline_access.

The client scopes profile, email, address and phone are also defined in the OpenID Connect specification. These client scopes do not have any role scope mappings defined, but they have some protocol mappers defined, and these mappers correspond to the claims defined in the OpenID Connect specification.

For example, when you click to open the phone client scope and open the Mappers tab, you will see the protocol mappers, which correspond to the claims defined in the specification for the scope phone.

When the phone client scope is linked to a client, that client automatically inherits all the protocol mappers defined in the phone client scope. Access tokens issued for this client will contain the phone number information about the user, assuming that the user has a defined phone number.

Builtin client scopes contain exactly the protocol mappers as defined per the specification, however you are free to edit client scopes and create/update/remove any protocol mappers (or role scope mappings).

The client scope roles is not defined in the OpenID Connect specification and it is also not added automatically to the scope claim in the access token. This client scope has some mappers, which are used to add roles of the user to the access token and possibly add some audiences for the clients with at least one client role as described in the Audience section.

The client scope web-origins is also not defined in the OpenID Connect specification and not added to the scope claim. This is used to add allowed web origins to the access token allowed-origins claim.

The client scope microprofile-jwt was created to handle the claims defined in the MicroProfile/JWT Auth Specification. This client scope defines a user property mapper for the upn claim and also a realm role mapper for the groups claim. These mappers can be changed as needed so that different properties can be used to create the MicroProfile/JWT specific claims.

Client scope contains options related to the consent screen. Those options are useful only if the linked client is configured to require consent (if the Consent Required switch is enabled on the client).

Linking between client scope and client is configured in the Client Scopes tab of the particular client. There are 2 ways of linking between client scope and client.

The tabs Mappers and Scope of the client contain the protocol mappers and role scope mappings declared solely for this client. They do not contain the mappers and scope mappings inherited from client scopes. However, it may be useful to see what the effective protocol mappers will be (protocol mappers defined on the client itself as well as inherited from the linked client scopes) and the effective role scope mappings used when you generate the token for the particular client.

You can see all of these when you click the Client Scopes tab for the client and then open the sub-tab Evaluate. From here you can select the optional client scopes that you want to apply. This will also show you the value of the scope parameter, which needs to be sent from the application to the Keycloak OpenID Connect authorization endpoint.

When issuing tokens for a particular user, the client scope is applied only if the user is permitted to use it. In the case that a client scope does not have any role scope mappings defined on itself, then each user is automatically permitted to use this client scope. However, when a client scope has any role scope mappings defined on itself, then the user must be a member of at least one of the roles. In other words, there must be an intersection between the user roles and the roles of the client scope. Composite roles are taken into account when evaluating this intersection.

If a user is not permitted to use the client scope, then no protocol mappers or role scope mappings will be used when generating tokens and the client scope will not appear in the scope value in the token.

The Realm Default Client Scopes allow you to define set of client scopes, which will be automatically linked to newly created clients.

Open the left menu item Client Scopes and then select Default Client Scopes.

From here, select the client scopes that you want to add as Default Client Scopes to newly created clients and Optional Client Scopes to newly created clients.

Once the client is created, you can unlink the default client scopes, if needed. This is similar to how you remove Default Roles.

The term scope is used in Keycloak on few places. Various occurrences of scopes are related to each other, but may have a different context and meaning. To clarify, here we explain the various scopes used in Keycloak.

Client Policies realize the following points mentioned as follows.

The client policy concept is independent of any specific protocol. However, Keycloak currently supports it only just for the OpenID Connect (OIDC) protocol.

Client Policies consists of the four building blocks: Condition, Executor, Profile and Policy.

Policies, profiles, conditions, executors can be configured by Admin REST API, which means also the Admin Console. To do so, there is a tab Realm → Realm Settings → Client Policies , which means the administrator can have client policies per realm.

The Global Client Profiles are automatically available in each realm. However there are no client policies configured by default. This means that the administrator is always required to create any client policy if they want for example the clients of his realm to be FAPI compliant. Global profiles cannot be updated, but the administrator can easily use them as a template and create their own profile if they want to do some slight changes in the global profile configurations. There is JSON Editor available in the Admin Console, which simplifies the creation of new profile based on some global profile.

Client Policies can replace Client Registration Policies described in the Securing Applications and Services Guide. However, Client Registration Policies also still co-exist. This means that for example during a Dynamic Client Registration request to create/update a client, both client policies and client registration policies are applied.

The current plans are for the Client Registration Policies feature to be removed and the existing client registration policies will be migrated into new client policies automatically. == Roles

Roles identify a type or category of user. Admin, user, manager, and employee are all typical roles that may exist in an organization. Applications often assign access and permissions to specific roles rather than individual users as dealing with users can be too fine grained and hard to manage. For example, the Admin Console has specific roles which give permission to users to access parts of the Admin Console UI and perform certain actions. There is a global namespace for roles and each client also has its own dedicated namespace where roles can be defined.

Default roles allow you to automatically assign user role mappings when any user is newly created or imported through Identity Brokering. To specify default roles go to the Roles left menu item, and click the Default Roles tab or alternatively you can search for default-roles-${realmName} role in the Realm Roles tab and then click Edit. Please note the default-roles-${realmName} role cannot be removed because it serves as a container for both realm and client default roles.

As you can see from the screenshot, there are already a number of default roles set up by default.

There are two realm-level roles in the master realm. These are:

Users with the admin role are super users and have full access to manage any realm on the server. Users with the create-realm role are allowed to create new realms. They will be granted full access to any new realm they create.

Admin users within the master realm can be granted management privileges to one or more other realms in the system. Each realm in Keycloak is represented by a client in the master realm. The name of the client is <realm name>-realm. These clients each have client-level roles defined which define varying level of access to manage an individual realm.

The roles available are:

Assign the roles you want to your users and they will only be able to use that specific part of the administration console.

Let’s look first at allowing an admin to manage one client and one client only. In our example, we have a realm called test and a client called sales-application. In the realm test we will give a user in that realm permission to only manage that application.

Another thing you might want to do is to restrict the set of roles an admin is allowed to assign to a user. Continuing our last example, let’s expand the permission set of the 'sales-admin' user so that he can also control which users are allowed to access this application. Through fine grain permissions, we can enable it so that the sales-admin can only assign roles that grant specific access to the sales-application. We can also restrict it so that the admin can only map roles and not perform any other types of user administration.

The sales-application has defined three different client roles.

We want the sales-admin user to be able to map these roles to any user in the system. The first step to do this is to allow the role to be mapped by the admin. If we click on the viewLeads role, you’ll see that there is a Permissions tab for this role.

If we click on that tab and turn the Permissions Enabled on, you’ll see that there are a number of actions we can apply policies to.

The one we are interested in is map-role. Click on this permission and add the same User Policy that was created in the earlier example.

What we’ve done is say that the sales-admin can map the viewLeads role. What we have not done is specify which users the admin is allowed to map this role too. To do that we must go to the Users section of the admin console for this realm. Clicking on the Users left menu item brings us to the users interface of the realm. You should see a Permissions tab. Click on that and enable it.

The permission we are interested in is map-roles. This is a restrictive policy in that it only allows admins the ability to map roles to a user. If we click on the map-roles permission and again add the User Policy we created for this, our sales-admin will be able to map roles to any user.

The last thing we have to do is add the view-users role to the sales-admin. This will allow the admin to view users in the realm he wants to add the sales-application roles to.

You can do a lot more with fine grain permissions beyond managing a specific client or the specific roles of a client. This chapter defines the whole list of permission types that can be described for a realm.

It’s recommended to regularly rotate keys. To do so you should start by creating new keys with a higher priority than the existing active keys. Or create new keys with the same priority and making the previous keys passive.

Once new keys are available all new tokens and cookies will be signed with the new keys. When a user authenticates to an application the SSO cookie is updated with the new signature. When OpenID Connect tokens are refreshed new tokens are signed with the new keys. This means that over time all cookies and tokens will use the new keys and after a while the old keys can be removed.

How long you wait to delete old keys is a tradeoff between security and making sure all cookies and tokens are updated. In general it should be acceptable to drop old keys after a few weeks. Users that have not been active in the period between the new keys where added and the old keys removed will have to re-authenticate.

This also applies to offline tokens. To make sure they are updated the applications need to refresh the tokens before the old keys are removed.

As a guideline, it may be a good idea to create new keys every 3-6 months and delete old keys 1-2 months after the new keys were created.

To add a new generated keypair select Providers and choose rsa-generated from the dropdown. You can change the priority to make sure the new keypair becomes the active keypair. You can also change the keysize if you want smaller or larger keys (default is 2048, supported values are 1024, 2048 and 4096).

Click Save to add the new keys. This will generated a new keypair including a self-signed certificate.

Changing the priority for a provider will not cause the keys to be re-generated, but if you want to change the keysize you can edit the provider and new keys will be generated.

To add a keypair and certificate obtained elsewhere select Providers and choose rsa from the dropdown. You can change the priority to make sure the new keypair becomes the active keypair.

Click on Select file for Private RSA Key to upload your private key. The file should be encoded in PEM format. You don’t need to upload the public key as it is automatically extracted from the private key.

If you have a signed certificate for the keys click on Select file next to X509 Certificate. If you don’t have one you can skip this and a self-signed certificate will be generated.

To add a keypair and certificate stored in a Java Keystore file on the host select Providers and choose java-keystore from the dropdown. You can change the priority to make sure the new keypair becomes the active keypair.

Fill in the values for Keystore, Keystore Password, Key Alias and Key Password and click on Save.

Locate the keypair in Active then click on the provider in the Provider column. This will take you to the configuration screen for the key provider for the keys. Click on Active to turn it OFF, then click on Save. The keys will no longer be active and can only be used for verifying signatures.

Locate the keypair in Active then click on the provider in the Provider column. This will take you to the configuration screen for the key provider for the keys. Click on Enabled to turn it OFF, then click on Save. The keys will no longer be enabled.

Alternatively, you can delete the provider from the Providers table.

Keycloak has the signing keys stored just locally and they are never shared with the client applications, users or other entities. However if you think that your realm signing key was compromised, you should first generate new keypair as described above and then immediately remove the compromised keypair.

Then to ensure that client applications won’t accept the tokens signed by the compromised key, you should update and push not-before policy for the realm, which is doable from the admin console. Pushing new policy will ensure that client applications won’t accept the existing tokens signed by the compromised key, but also the client application will be forced to download new keypair from the Keycloak, hence the tokens signed by the compromised key won’t be valid anymore. Note that your REST and confidential clients must have set Admin URL, so that Keycloak is able to send them the request about pushed not-before policy.

There are a number of steps you have to complete to be able to enable login with Bitbucket.

First, open the Identity Providers left menu item and select Bitbucket from the Add provider drop down list. This will bring you to the Add identity provider page.

Before you can click Save, you must obtain a Client ID and Client Secret from Bitbucket.

To enable login with Bitbucket you must first register an application project in OAuth on Bitbucket Cloud.

Click the Add consumer button.

Copy the Redirect URI from the Keycloak Add Identity Provider page and enter it into the Callback URL field on the Bitbucket Add OAuth Consumer page.

On the same page, mark the Email and Read boxes under Account to allow your application to read user email.

When you are done registering, click Save. This will open the application management page in Bitbucket. Find the client ID and secret from this page so you can enter them into the Keycloak Add identity provider page. Click Save.

There are a number of steps you have to complete to be able to enable login with Facebook. First, go to the Identity Providers left menu item and select Facebook from the Add provider drop down list. This will bring you to the Add identity provider page.

You can’t click save yet, as you’ll need to obtain a Client ID and Client Secret from Facebook. One piece of data you’ll need from this page is the Redirect URI. You’ll have to provide that to Facebook when you register Keycloak as a client there, so copy this URI to your clipboard.

To enable login with Facebook you first have to create a project and a client in the Facebook Developer Console.

Once you’ve logged into the console there is a pull down menu in the top right corner of the screen that says My Apps. Select the Add a New App menu item.

Select the Website icon. Click the Skip and Create App ID button.