Securing Applications and Services Guide

The most important endpoint to understand is the well-known configuration endpoint. It lists endpoints and other configuration options relevant to the OpenID Connect implementation in Keycloak. The endpoint is:

To obtain the full URL, add the base URL for Keycloak and replace {realm-name} with the name of your realm. For example:

http://localhost:8080/realms/master/.well-known/openid-configuration

Some RP libraries retrieve all required endpoints from this endpoint, but for others you might need to list the endpoints individually.

The Authorization Code flow redirects the user agent to Keycloak. Once the user has successfully authenticated with Keycloak, an Authorization Code is created and the user agent is redirected back to the application. The application then uses the authorization code along with its credentials to obtain an Access Token, Refresh Token and ID Token from Keycloak.

The flow is targeted towards web applications, but is also recommended for native applications, including mobile applications, where it is possible to embed a user agent.

For more details refer to the Authorization Code Flow in the OpenID Connect specification.

The Implicit flow works similarly to the Authorization Code flow, but instead of returning an Authorization Code, the Access Token and ID Token is returned. This approach reduces the need for the extra invocation to exchange the Authorization Code for an Access Token. However, it does not include a Refresh Token. This results in the need to permit Access Tokens with a long expiration; however, that approach is not practical because it is very hard to invalidate these tokens. Alternatively, you can require a new redirect to obtain a new Access Token once the initial Access Token has expired. The Implicit flow is useful if the application only wants to authenticate the user and deals with logout itself.

You can instead use a Hybrid flow where both the Access Token and an Authorization Code are returned.

One thing to note is that both the Implicit flow and Hybrid flow have potential security risks as the Access Token may be leaked through web server logs and browser history. You can somewhat mitigate this problem by using short expiration for Access Tokens.

For more details, see the Implicit Flow in the OpenID Connect specification.

Per current OAuth 2.0 Security Best Current Practice, this flow should not be used. This flow is removed from the future OAuth 2.1 specification.

Resource Owner Password Credentials, referred to as Direct Grant in Keycloak, allows exchanging user credentials for tokens. Per current OAuth 2.0 Security Best Practices, this flow should not be used, preferring alternative methods such as Device Authorization Grant or Authorization code.

The limitations of using this flow include:

Security concerns with this flow include:

For a client to be permitted to use the Resource Owner Password Credentials grant, the client has to have the Direct Access Grants Enabled option enabled.

This flow is not included in OpenID Connect, but is a part of the OAuth 2.0 specification. It is removed from the future OAuth 2.1 specification.

For more details, see the Resource Owner Password Credentials Grant chapter in the OAuth 2.0 specification.

Client Credentials are used when clients (applications and services) want to obtain access on behalf of themselves rather than on behalf of a user. For example, these credentials can be useful for background services that apply changes to the system in general rather than for a specific user.

Keycloak provides support for clients to authenticate either with a secret or with public/private keys.

This flow is not included in OpenID Connect, but is a part of the OAuth 2.0 specification.

For more details, see the Client Credentials Grant chapter in the OAuth 2.0 specification.

Device Authorization Grant is used by clients running on internet-connected devices that have limited input capabilities or lack a suitable browser.

For more details, see the OAuth 2.0 Device Authorization Grant specification.

Client Initiated Backchannel Authentication Grant is used by clients who want to initiate the authentication flow by communicating with the OpenID Provider directly without redirect through the user’s browser like OAuth 2.0’s authorization code grant.

The client requests from Keycloak an auth_req_id that identifies the authentication request made by the client. Keycloak creates the auth_req_id.

After receiving this auth_req_id, this client repeatedly needs to poll Keycloak to obtain an Access Token, Refresh Token, and ID Token from Keycloak in return for the auth_req_id until the user is authenticated.

In case that client uses ping mode, it does not need to repeatedly poll the token endpoint, but it can wait for the notification sent by Keycloak to the specified Client Notification Endpoint. The Client Notification Endpoint can be configured in the Keycloak Admin Console. The details of the contract for Client Notification Endpoint are described in the CIBA specification.

For more details, see OpenID Connect Client Initiated Backchannel Authentication Flow specification.

Also refer to other places of Keycloak documentation such as Backchannel Authentication Endpoint of this guide and Client Initiated Backchannel Authentication Grant section of Server Administration Guide. For the details about FAPI CIBA compliance, see the FAPI section of this guide.

The adapter is distributed in several ways, but we recommend that you install the keycloak-js package from NPM:

Alternatively, the library can be retrieved directly from the Keycloak server at /js/keycloak.js and is also distributed as a ZIP archive. We are however considering the inclusion of the adapter directly from the Keycloak server as deprecated, and this functionality might be removed in the future.

One important thing to consider about using client-side applications is that the client has to be a public client as there is no secure way to store client credentials in a client-side application. This consideration makes it very important to make sure the redirect URIs you have configured for the client are correct and as specific as possible.

To use the adapter, create a client for your application in the Keycloak Admin Console. Make the client public by toggling Client authentication to Off on the Capability config page.

You also need to configure Valid Redirect URIs and Web Origins. Be as specific as possible as failing to do so may result in a security vulnerability.

The following example shows how to initialize the adapter. Make sure that you replace the options passed to the Keycloak constructor with those of the client you have configured.

To authenticate, you call the login function. Two options exist to make the adapter automatically authenticate. You can pass login-required or check-sso to the init() function.

You can configure a silent check-sso option. With this feature enabled, your browser will not perform a full redirect to the Keycloak server and back to your application, but this action will be performed in a hidden iframe. Therefore, your application resources are only loaded and parsed once by the browser, namely when the application is initialized and not again after the redirect back from Keycloak to your application. This approach is particularly useful in case of SPAs (Single Page Applications).

To enable the silent check-sso, you provide a silentCheckSsoRedirectUri attribute in the init method. Make sure this URI is a valid endpoint in the application; it must be configured as a valid redirect for the client in the Keycloak Admin Console:

The page at the silent check-sso redirect uri is loaded in the iframe after successfully checking your authentication state and retrieving the tokens from the Keycloak server. It has no other task than sending the received tokens to the main application and should only look like this:

Remember that this page must be served by your application at the specified location in silentCheckSsoRedirectUri and is not part of the adapter.

To enable login-required set onLoad to login-required and pass to the init method:

After the user is authenticated the application can make requests to RESTful services secured by Keycloak by including the bearer token in the Authorization header. For example:

One thing to keep in mind is that the access token by default has a short life expiration so you may need to refresh the access token prior to sending the request. You refresh this token by calling the updateToken() method. This method returns a Promise, which makes it easy to invoke the service only if the token was successfully refreshed and displays an error to the user if it was not refreshed. For example:

By default, the adapter creates a hidden iframe that is used to detect if a Single-Sign Out has occurred. This iframe does not require any network traffic. Instead the status is retrieved by looking at a special status cookie. This feature can be disabled by setting checkLoginIframe: false in the options passed to the init() method.

You should not rely on looking at this cookie directly. Its format can change and it’s also associated with the URL of the Keycloak server, not your application.

By default, the adapter uses the Authorization Code flow.

With this flow, the Keycloak server returns an authorization code, not an authentication token, to the application. The JavaScript adapter exchanges the code for an access token and a refresh token after the browser is redirected back to the application.

Keycloak also supports the Implicit flow where an access token is sent immediately after successful authentication with Keycloak. This flow may have better performance than the standard flow because no additional request exists to exchange the code for tokens, but it has implications when the access token expires.

However, sending the access token in the URL fragment can be a security vulnerability. For example the token could be leaked through web server logs and or browser history.

To enable implicit flow, you enable the Implicit Flow Enabled flag for the client in the Keycloak Admin Console. You also pass the parameter flow with the value implicit to init method:

Note that only an access token is provided and no refresh token exists. This situation means that once the access token has expired, the application has to redirect to Keycloak again to obtain a new access token.

Keycloak also supports the Hybrid flow.

This flow requires the client to have both the Standard Flow and Implicit Flow enabled in the Admin Console. The Keycloak server then sends both the code and tokens to your application. The access token can be used immediately while the code can be exchanged for access and refresh tokens. Similar to the implicit flow, the hybrid flow is good for performance because the access token is available immediately. But, the token is still sent in the URL, and the security vulnerability mentioned earlier may still apply.

One advantage in the Hybrid flow is that the refresh token is made available to the application.

For the Hybrid flow, you need to pass the parameter flow with value hybrid to the init method:

Keycloak supports hybrid mobile apps developed with Apache Cordova. The adapter has two modes for this: cordova and cordova-native:

The default is cordova, which the adapter automatically selects if no adapter type has been explicitly configured and window.cordova is present. When logging in, it opens an InApp Browser that lets the user interact with Keycloak and afterwards returns to the app by redirecting to http://localhost. Because of this behavior, you whitelist this URL as a valid redirect-uri in the client configuration section of the Admin Console.

While this mode is easy to set up, it also has some disadvantages:

The alternative mode is`cordova-native`, which takes a different approach. It opens the login page using the system’s browser. After the user has authenticated, the browser redirects back into the application using a special URL. From there, the Keycloak adapter can finish the login by reading the code or token from the URL.

You can activate the native mode by passing the adapter type cordova-native to the init() method:

This adapter requires two additional plugins:

The technical details for linking to an app differ on each platform and special setup is needed. Please refer to the Android and iOS sections of the deeplinks plugin documentation for further instructions.

Different kinds of links exist for opening apps: * custom schemes, such as myapp://login or android-app://com.example.myapp/https/example.com/login * Universal Links (iOS)) / Deep Links (Android). While the former are easier to set up and tend to work more reliably, the latter offer extra security because they are unique and only the owner of a domain can register them. Custom-URLs are deprecated on iOS. For best reliability, we recommend that you use universal links combined with a fallback site that uses a custom-url link.

Furthermore, we recommend the following steps to improve compatibility with the adapter:

In some situations, you may need to run the adapter in environments that are not supported by default, such as Capacitor. To use the JavasScript client in these environments, you can pass a custom adapter. For example, a third-party library could provide such an adapter to make it possible to reliably run the adapter:

This specific package does not exist, but it gives a pretty good example of how such an adapter could be passed into the client.

It’s also possible to make your own adapter, to do so you will have to implement the methods described in the KeycloakAdapter interface. For example the following TypeScript code ensures that all the methods are properly implemented:

Naturally you can also do this without TypeScript by omitting the type information, but ensuring implementing the interface properly will then be left entirely up to you.

In the latest versions of some browsers, various cookies policies are applied to prevent tracking of the users by third parties, such as SameSite in Chrome or completely blocked third-party cookies. Those policies are likely to become more restrictive and adopted by other browsers over time. Eventually cookies in third-party contexts may become completely unsupported and blocked by the browsers. As a result, the affected adapter features might ultimately be deprecated.

The adapter relies on third-party cookies for Session Status iframe, silent check-sso and partially also for regular (non-silent) check-sso. Those features have limited functionality or are completely disabled based on how restrictive the browser is regarding cookies. The adapter tries to detect this setting and reacts accordingly.

Assuming you have already installed Node.js, create a folder for your application:

Use npm init command to create a package.json for your application. Now add the Keycloak connect adapter in the dependencies list:

In the root directory of your project create a file called server.js and add the following code:

Install the express-session dependency:

To start the server.js script, add the following command in the 'scripts' section of the package.json:

Now we have the ability to run our server with following command:

By default, this will locate a file named keycloak.json alongside the main executable of your application, in our case on the root folder, to initialize Keycloak specific settings such as public key, realm name, various URLs.

In that case a Keycloak deployment is necessary to access Keycloak admin console.

Please visit links on how to deploy a Keycloak admin console with Podman or Docker

Now we are ready to obtain the keycloak.json file by visiting the Keycloak Admin Console → clients (left sidebar) → choose your client → Installation → Format Option → Keycloak OIDC JSON → Download

Paste the downloaded file on the root folder of our project.

Instantiation with this method results in all the reasonable defaults being used. As alternative, it’s also possible to provide a configuration object, rather than the keycloak.json file:

Applications can also redirect users to their preferred identity provider by using:

Once instantiated, install the middleware into your connect-capable app:

In order to do so, first we have to install Express:

then require Express in our project as outlined below:

and configure Keycloak middleware in Express, by adding at the code below:

Last but not least, let’s set up our server to listen for HTTP requests on port 3000 by adding the following code to main.js:

If the application is running behind a proxy that terminates an SSL connection Express must be configured per the express behind proxies guide. Using an incorrect proxy configuration can result in invalid redirect URIs being generated.

Example configuration:

To secure a resource with an application role for a different app:

To secure a resource with a realm role:

The keycloak-enforcer method operates in two modes, depending on the value of the response_mode configuration option.

If response_mode is set to token, permissions are obtained from the server on behalf of the subject represented by the bearer token that was sent to your application. In this case, a new access token is issued by Keycloak with the permissions granted by the server. If the server did not respond with a token with the expected permissions, the request is denied. When using this mode, you should be able to obtain the token from the request as follows:

Prefer this mode when your application is using sessions and you want to cache previous decisions from the server, as well automatically handle refresh tokens. This mode is especially useful for applications acting as a client and resource server.

If response_mode is set to permissions (default mode), the server only returns the list of granted permissions, without issuing a new access token. In addition to not issuing a new token, this method exposes the permissions granted by the server through the request as follows:

Regardless of the response_mode in use, the keycloak.enforcer method will first try to check the permissions within the bearer token that was sent to your application. If the bearer token already carries the expected permissions, there is no need to interact with the server to obtain a decision. This is specially useful when your clients are capable of obtaining access tokens from the server with the expected permissions before accessing a protected resource, so they can use some capabilities provided by Keycloak Authorization Services such as incremental authorization and avoid additional requests to the server when keycloak.enforcer is enforcing access to the resource.

By default, the policy enforcer will use the client_id defined to the application (for instance, via keycloak.json) to reference a client in Keycloak that supports Keycloak Authorization Services. In this case, the client can not be public given that it is actually a resource server.

If your application is acting as both a public client(frontend) and resource server(backend), you can use the following configuration to reference a different client in Keycloak with the policies that you want to enforce:

It is recommended to use distinct clients in Keycloak to represent your frontend and backend.

If the application you are protecting is enabled with Keycloak authorization services and you have defined client credentials in keycloak.json, you can push additional claims to the server and make them available to your policies in order to make decisions. For that, you can define a claims configuration option which expects a function that returns a JSON with the claims you want to push:

For more details about how to configure Keycloak to protected your application resources, please take a look at the Authorization Services Guide.

Advanced Login Configuration:

By default, all unauthorized requests will be redirected to the Keycloak login page unless your client is bearer-only. However, a confidential or public client may host both browsable and API endpoints. To prevent redirects on unauthenticated API requests and instead return an HTTP 401, you can override the redirectToLogin function.

For example, this override checks if the URL contains /api/ and disables login redirects:

When the user-triggered logout is invoked a query parameter redirect_url can be passed:

This parameter is then used as the redirect url of the OIDC logout endpoint and the user will be redirected to https://example.com/logged/out.

A complete example using the Node.js adapter usage can be found in Keycloak quickstarts for Node.js

To make sure that your clients are FAPI compliant, you can configure Client Policies in your realm as described in the Server Administration Guide and link them to the global client profiles for FAPI support, which are automatically available in each realm. You can use either fapi-1-baseline or fapi-1-advanced profile based on which FAPI profile you need your clients to conform with. You can use also profiles fapi-2-security-profile or fapi-2-message-signing for the compliance with FAPI 2 Draft specifications.

In case you want to use Pushed Authorization Request (PAR), it is recommended that your client use both the fapi-1-baseline profile and fapi-1-advanced for PAR requests. Specifically, the fapi-1-baseline profile contains pkce-enforcer executor, which makes sure that client use PKCE with secured S256 algorithm. This is not required for FAPI Advanced clients unless they use PAR requests.

In case you want to use CIBA in a FAPI compliant way, make sure that your clients use both fapi-1-advanced and fapi-ciba client profiles. There is a need to use the fapi-1-advanced profile, or other client profile containing the requested executors, as the fapi-ciba profile contains just CIBA-specific executors. When enforcing the requirements of the FAPI CIBA specification, there is a need for more requirements, such as enforcement of confidential clients or certificate-bound access tokens.

Keycloak is compliant with the Open Finance Brasil Financial-grade API Security Profile 1.0 Implementers Draft 3. This one is stricter in some requirements than the FAPI 1 Advanced specification and hence it may be needed to configure Client Policies in the more strict way to enforce some of the requirements. Especially:

Keycloak is compliant with the Australia Consumer Data Right Security Profile.

If you want to apply the Australia CDR security profile, you need to use fapi-1-advanced profile because the Australia CDR security profile is based on FAPI 1.0 Advanced security profile. If your client also applies PAR, make sure that client applies RFC 7637 Proof Key for Code Exchange (PKCE) because the Australia CDR security profile requires that you apply PKCE when applying PAR. This can be achieved by using a client profile with the pkce-enforcer executor.

As confidential information is being exchanged, all interactions shall be encrypted with TLS (HTTPS). Moreover, there are some requirements in the FAPI specification for the cipher suites and TLS protocol versions used. To match these requirements, you can consider configure allowed ciphers. This configuration can be done by setting the https-protocols and https-cipher-suites options. Keycloak uses TLSv1.3 by default and hence it is possibly not needed to change the default settings. However it may be needed to adjust ciphers if you need to fall back to lower TLS version for some reason. For more details, see Configuring TLS guide.

To make sure that your clients are OAuth 2.1 compliant, you can configure Client Policies in your realm as described in the Server Administration Guide and link them to the global client profiles for OAuth 2.1 support, which are automatically available in each realm. You can use either oauth-2-1-for-confidential-client profile for confidential clients or oauth-2-1-for-public-client profile for public clients.

If you need to manually validate access tokens issued by Keycloak, you can invoke the Introspection Endpoint. The downside to this approach is that you have to make a network invocation to the Keycloak server. This can be slow and possibly overload the server if you have too many validation requests going on at the same time. Keycloak issued access tokens are JSON Web Tokens (JWT) digitally signed and encoded using JSON Web Signature (JWS). Because they are encoded in this way, you can locally validate access tokens using the public key of the issuing realm. You can either hard code the realm’s public key in your validation code, or lookup and cache the public key using the certificate endpoint with the Key ID (KID) embedded within the JWS. Depending on what language you code in, many third party libraries exist and they can help you with JWS validation.

When using the redirect based flows, be sure to use valid redirect uris for your clients. The redirect uris should be as specific as possible. This especially applies to client-side (public clients) applications. Failing to do so could result in:

In production for web applications always use https for all redirect URIs. Do not allow redirects to http.

A few special redirect URIs also exist:

Each SAML client adapter supported by Keycloak can be configured by a simple XML text file. This is what one might look like:

Some of these configuration switches may be adapter specific and some are common across all adapters. For Java adapters you can use ${…​} enclosure as System property replacement. For example ${jboss.server.config.dir}.

To be able to secure WAR apps deployed on JBoss EAP or WildFly, you must install and configure the Keycloak SAML Adapter Subsystem.

You then provide a keycloak config, /WEB-INF/keycloak-saml.xml file in your WAR and change the auth-method to KEYCLOAK-SAML within web.xml.

For the WildFly 29 or newer, the SAML adapter is provided as a Galleon feature pack. More details about this is in the WildFly documentation. The same option will be provided for JBoss EAP 8 GA.

Keycloak provided adapter ZIP download in the past, but it is not provided anymore. For the older WildFly versions, it is recommended to upgrade to newer WildFly/EAP and use Galleon. Otherwise, you will need to stick with the older Keycloak adapters, but those are not maintained and officially supported. For JBoss EAP 7, it is possible to stick with the Red Hat Single Sign-On 7.6 adapters, which is still supported.

For more details on how to integrate Keycloak with JakartaEE applications running on latest Wildfly/EAP, take a look at the Jakarta EE quickstart in the Keycloak Quickstart GitHub Repository.

Below are the details on how to configure the SAML adapter secured by Galleon.

For each servlet-based adapter, the endpoint you register for the assert consumer service URL and single logout service must be the base URL of your servlet application with /saml appended to it, that is, https://example.com/contextPath/saml.

There are multiple ways you can log out from a web application. For Jakarta EE servlet containers, you can call HttpServletRequest.logout(). For any other browser application, you can point the browser at any url of your web application that has a security constraint and pass in a query parameter GLO, i.e. http://myapp?GLO=true. This will log you out if you have an SSO session with your browser.

After a successful SAML login, your application code may want to obtain attribute values passed with the SAML assertion. HttpServletRequest.getUserPrincipal() returns a Principal object that you can typecast into a Keycloak specific class called org.keycloak.adapters.saml.SamlPrincipal. This object allows you to look at the raw assertion and also has convenience functions to look up attribute values.

Keycloak has some error handling facilities for servlet based client adapters. When an error is encountered in authentication, the client adapter will call HttpServletResponse.sendError(). You can set up an error-page within your web.xml file to handle the error however you want. The client adapter can throw 400, 401, 403, and 500 errors.

The client adapter also sets an HttpServletRequest attribute that you can retrieve. The attribute name is org.keycloak.adapters.spi.AuthenticationError. Typecast this object to: org.keycloak.adapters.saml.SamlAuthenticationError. This class can tell you exactly what happened. If this attribute is not set, then the adapter was not responsible for the error code.

The best way to troubleshoot problems is to turn on debugging for SAML in both the client adapter and Keycloak Server. Using your logging framework, set the log level to DEBUG for the org.keycloak.saml package. Turning this on allows you to see the SAML requests and response documents being sent to and from the server.

SAML offers Multi Tenancy, meaning that a single target application (WAR) can be secured with multiple Keycloak realms. The realms can be located on the same Keycloak instance or on different instances.

To do this, the application must have multiple keycloak-saml.xml adapter configuration files.

While you could have multiple instances of your WAR with different adapter configuration files deployed to different context-paths, this may be inconvenient and you may also want to select the realm based on something other than context-path.

Keycloak makes it possible to have a custom config resolver, so you can choose which adapter config is used for each request. In SAML, the configuration is only interesting in the login processing; once the user is logged in, the session is authenticated and it does not matter if the keycloak-saml.xml returned is different. For that reason, returning the same configuration for the same session is the correct way to go.

To achieve this, create an implementation of org.keycloak.adapters.saml.SamlConfigResolver. The following example uses the Host header to locate the proper configuration and load it and the associated elements from the applications' Java classpath:

You must also configure which SamlConfigResolver implementation to use with the keycloak.config.resolver context-param in your web.xml:

There are two hosts involved:

All of the following steps need to performed on $sp_host with root privileges.

Browsers are planning to set the default value for the SameSite attribute for cookies to Lax. This setting means that cookies will be sent to applications only if the request originates in the same domain. This behavior can affect the SAML POST binding which may become non-functional. To preserve full functionality of the mod_auth_mellon module, we recommend setting the SameSite value to None for the cookie created by mod_auth_mellon. Not doing so may result in an inability to login using Keycloak.

To set the SameSite value to None, add the following configuration to <Location / > tag within your mellon.conf file.

The support for this configuration is available in the mod_auth_mellon module from version 0.16.0.

The bearer token can be issued on behalf of a user or a Service Account. The following permissions are required to invoke the endpoints (see Server Administration Guide for more details):

If you are using a bearer token to create clients it’s recommend to use a token from a Service Account with only the create-client role (see Server Administration Guide for more details).

The recommended approach to registering new clients is by using initial access tokens. An initial access token can only be used to create clients and has a configurable expiration as well as a configurable limit on how many clients can be created.

An initial access token can be created through the admin console. To create a new initial access token first select the realm in the admin console, then click on Client in the menu on the left, followed by Initial access token in the tabs displayed in the page.

You will now be able to see any existing initial access tokens. If you have access you can delete tokens that are no longer required. You can only retrieve the value of the token when you are creating it. To create a new token click on Create. You can now optionally add how long the token should be valid, also how many clients can be created using the token. After you click on Save the token value is displayed.

It is important that you copy/paste this token now as you won’t be able to retrieve it later. If you forget to copy/paste it, then delete the token and create another one.

The token value is used as a standard bearer token when invoking the Client Registration Services, by adding it to the Authorization header in the request. For example:

When you create a client through the Client Registration Service the response will include a registration access token. The registration access token provides access to retrieve the client configuration later, but also to update or delete the client. The registration access token is included with the request in the same way as a bearer token or initial access token.

By default, registration access token rotation is enabled. This means a registration access token is only valid once. When the token is used, the response will include a new token. Note that registration access token rotation can be disabled by using Client Policies.

If a client was created outside of the Client Registration Service it won’t have a registration access token associated with it. You can create one through the admin console. This can also be useful if you lose the token for a particular client. To create a new token find the client in the admin console and click on Credentials. Then click on Generate registration access token.

Regardless of the login method, the account that logs in needs proper permissions to be able to perform client registration operations. Keep in mind that any account in a non-master realm can only have permissions to manage clients within the same realm. If you need to manage different realms, you can either configure multiple users in different realms, or you can create a single user in the master realm and add roles for managing clients in different realms.

You cannot configure users with the Client Registration CLI. Use the Admin Console web interface or the Admin Client CLI to configure users. See Server Administration Guide for more details.

When kcreg successfully logs in, it receives authorization tokens and saves them in a private configuration file so the tokens can be used for subsequent invocations. See Working with alternative configurations for more information on configuration files.

See the built-in help for more information on using the Client Registration CLI.

For example, on:

See kcreg config credentials --help for more information about starting an authenticated session.

By default, the Client Registration CLI automatically maintains a configuration file at a default location, ./.keycloak/kcreg.config, under the user’s home directory. You can use the --config option to point to a different file or location to maintain multiple authenticated sessions in parallel. It is the safest way to perform operations tied to a single configuration file from a single thread.

You might want to avoid storing secrets inside a configuration file by using the --no-config option with all of your commands, even though it is less convenient and requires more token requests to do so. Specify all authentication information with each kcreg invocation.

Developers who do not have an account configured at the Keycloak server they want to use can use the Client Registration CLI. This is possible only when the realm administrator issues a developer an Initial Access Token. It is up to the realm administrator to decide how and when to issue and distribute these tokens. The realm administrator can limit the maximum age of the Initial Access Token and the total number of clients that can be created with it.

Once a developer has an Initial Access Token, the developer can use it to create new clients without authenticating with kcreg config credentials. The Initial Access Token can be stored in the configuration file or specified as part of the kcreg create command.

For example, on:

or

or

When using an Initial Access Token, the server response includes a newly issued Registration Access Token. Any subsequent operation for that client needs to be performed by authenticating with that token, which is only valid for that client.

The Client Registration CLI automatically uses its private configuration file to save and use this token with its associated client. As long as the same configuration file is used for all client operations, the developer does not need to authenticate to read, update, or delete a client that was created this way.

See Client Registration for more information about Initial Access and Registration Access Tokens.

Run the kcreg config initial-token --help and kcreg config registration-token --help commands for more information on how to configure tokens with the Client Registration CLI.

The first task after authenticating with credentials or configuring an Initial Access Token is usually to create a new client. Often you might want to use a prepared JSON file as a template and set or override some of the attributes.

The following example shows how to read a JSON file, override any client id it may contain, set any other attributes, and print the configuration to a standard output after successful creation.

Run the kcreg create --help for more information about the kcreg create command.

You can use kcreg attrs to list available attributes. Keep in mind that many configuration attributes are not checked for validity or consistency. It is up to you to specify proper values. Remember that you should not have any id fields in your template and should not specify them as arguments to the kcreg create command.

You can retrieve an existing client by using the kcreg get command.

For example, on:

You can also retrieve the client configuration as an adapter configuration file, which you can package with your web application.

For example, on:

Run the kcreg get --help command for more information about the kcreg get command.

There are two methods for updating a client configuration.

One method is to submit a complete new state to the server after getting the current configuration, saving it to a file, editing it, and posting it back to the server.

For example, on:

The second method fetches the current client, sets or deletes fields on it, and posts it back in one step.

For example, on:

You can also use a file that contains only changes to be applied so you do not have to specify too many values as arguments. In this case, specify --merge to tell the Client Registration CLI that rather than treating the JSON file as a full, new configuration, it should treat it as a set of attributes to be applied over the existing configuration.

For example, on:

Run the kcreg update --help command for more information about the kcreg update command.

Use the following example to delete a client.

Run the kcreg delete --help command for more information about the kcreg delete command.

When performing a create, read, update, and delete (CRUD) operation using the --no-config mode, the Client Registration CLI cannot handle Registration Access Tokens for you. In that case, it is possible to lose track of the most recently issued Registration Access Token for a client, which makes it impossible to perform any further CRUD operations on that client without authenticating with an account that has manage-clients permissions.

If you have permissions, you can issue a new Registration Access Token for the client and have it printed to a standard output or saved to a configuration file of your choice. Otherwise, you have to ask the realm administrator to issue a new Registration Access Token for your client and send it to you. You can then pass it to any CRUD command via the --token option. You can also use the kcreg config registration-token command to save the new token in a configuration file and have the Client Registration CLI automatically handle it for you from that point on.

Run the kcreg update-token --help command for more information about the kcreg update-token command.

A successful response from an exchange invocation will return the HTTP 200 response code with a content type that depends on the requested-token-type and requested_issuer the client asks for. OAuth requested token types will return a JSON document as described in the OAuth Token Exchange specification.

Clients requesting a refresh token will get back both an access and refresh token in the response. Clients requesting only access token type will only get an access token in the response. Expiration information may or may not be included for clients requesting an external issuer through the requested_issuer parameter.

Error responses generally fall under the 400 HTTP response code category, but other error status codes may be returned depending on the severity of the error. Error responses may include content depending on the requested_issuer. OAuth based exchanges may return a JSON document as follows:

Additional error claims may be returned depending on the exchange type. For example, OAuth Identity Providers may include an additional account-link-url claim if the user does not have a link to an identity provider. This link can be used for a client initiated link request.

The rest of this chapter discusses the setup requirements and provides examples for different exchange scenarios. For simplicity’s sake, let’s call a token minted by the current realm as an internal token and a token minted by an external realm or identity provider as an external token.

Clients that want to exchange tokens for a different client need to be authorized in the Admin Console. You need to define a token-exchange fine grain permission in the target client you want permission to exchange to.

Your client now has permission to invoke. If you do not do this correctly, you will get a 403 Forbidden response if you try to make an exchange.

When your client is exchanging an existing token for a token targeting another client, you use the audience parameter. This parameter must be the client identifier for the target client that you configured in the Admin Console.

The subject_token parameter must be an access token for the target realm. If your requested_token_type parameter is a refresh token type, then the response will contain both an access token, refresh token, and expiration. Here’s an example JSON response you get back from this call.

When the audience parameter is not set, the value of the parameter defaults to the client making the token exchange request.

Unlike with confidential clients, public clients are not allowed to perform token exchanges using tokens from other clients. If you are passing a subject_token, the (confidential) client that was issued the token should either match the client making the request or, if issued to a different client, the client making the request should be among the audiences set to the token.

If you are explicitly setting a target audience (with a client different from the client making the request), you should also make sure that the token-exchange scope permission is configured for the client set to the audience parameter to allow the client making the request to successfully complete the exchange.

Internal to external token exchange requests will be denied with a 403, Forbidden response until you grant permission for the calling client to exchange tokens with the external identity provider. To grant permission to the client, you go to the identity provider’s configuration page to the Permissions tab.

Your client now has permission to invoke. If you do not do this correctly, you will get a 403 Forbidden response if you try to make an exchange.

When your client is exchanging an existing internal token to an external one, you provide the requested_issuer parameter. The parameter must be the alias of a configured identity provider.

The subject_token parameter must be an access token for the target realm. The requested_token_type parameter must be urn:ietf:params:oauth:token-type:access_token or left blank. No other requested token type is supported at this time. Here’s an example successful JSON response you get back from this call.

If the external identity provider is not linked for whatever reason, you will get an HTTP 400 response code with this JSON document:

The error claim will be either token_expired or not_linked. The account-link-url claim is provided so that the client can perform Client Initiated Account Linking. Most, if not all, providers require linking through browser OAuth protocol. With the account-link-url just add a redirect_uri query parameter to it and you can forward browsers to perform the link.

Before external token exchanges can be done, you grant permission for the calling client to make the exchange. This permission is granted in the same manner as internal to external permission is granted.

If you also provide an audience parameter whose value points to a different client other than the calling one, you must also grant the calling client permission to exchange to the target client specific in the audience parameter. How to do this is discussed earlier in this section.

The subject_token_type must either be urn:ietf:params:oauth:token-type:access_token or urn:ietf:params:oauth:token-type:jwt. If the type is urn:ietf:params:oauth:token-type:access_token you specify the subject_issuer parameter and it must be the alias of the configured identity provider. If the type is urn:ietf:params:oauth:token-type:jwt, the provider will be matched via the iss (issuer) claim within the JWT which must be the alias of the provider, or a registered issuer within the providers configuration.

For validation, if the token is an access token, the provider’s user info service will be invoked to validate the token. A successful call will mean that the access token is valid. If the subject token is a JWT and if the provider has signature validation enabled, that will be attempted, otherwise, it will default to also invoking on the user info service to validate the token.

By default, the internal token minted will use the calling client to determine what’s in the token using the protocol mappers defined for the calling client. Alternatively, you can specify a different target client using the audience parameter.

If your requested_token_type parameter is a refresh token type, then the response will contain both an access token, refresh token, and expiration. Here’s an example JSON response you get back from this call.

The user that the subject token represents must have permission to impersonate other users. See the Server Administration Guide on how to enable this permission. It can be done through a role or through fine grain admin permissions.

Make the request as described in other chapters except additionally specify the requested_subject parameter. The value of this parameter must be a username or user id.

If the audience parameter is provided, then the calling client must have permission to exchange to the client. How to set this up is discussed earlier in this chapter.

Additionally, the calling client must be granted permission to impersonate users.

Your client now has permission to impersonate users. If you do not do this correctly, you will get a 403 Forbidden response if you try to make this type of exchange.

To make the request, simply specify the requested_subject parameter. This must be the username or user id of a valid user. You can also specify an audience parameter if you wish.