1. Planning for securing applications and services
As an OAuth2, OpenID Connect, and SAML compliant server, Keycloak can secure any application and service as long as the technology stack they are using supports any of these protocols. For more details about the security protocols supported by Keycloak, consider looking at Server Administration Guide.
Most of the support for some of these protocols is already available from the programming language, framework, or reverse proxy they are using. Leveraging the support already available from the application ecosystem is a key aspect to make your application fully compliant with security standards and best practices, so that you avoid vendor lock-in.
For some programming languages, Keycloak provides libraries that try to fill the gap for the lack of support of a particular security protocol or to provide a more rich and tightly coupled integration with the server. These libraries are known by Keycloak Client Adapters, and they should be used as a last resort if you cannot rely on what is available from the application ecosystem.
1.1. Basic steps to secure applications and services
These are the basic steps for securing an application or a service in Keycloak.
-
Register a client to a realm using one of these options:
-
The Keycloak Admin Console
-
The client registration service
-
The CLI
-
-
Enable OpenID Connect or SAML protocols in your application using one these options:
-
Leveraging existing OpenID Connect and SAML support from the application ecosystem
-
Using a Keycloak Adapter
-
This guide provides the detailed instructions for these steps. You can find more details in the Server Administration Guide about how to register a client to Keycloak through the administration console.
1.2. Getting Started
The Keycloak Quickstarts Repository provides examples about how to secure applications and services using different programming languages and frameworks. By going through their documentation and codebase, you will understand the bare minimum changes required in your application and service in order to secure it with Keycloak.
Also, see the following sections for recommendations for trusted and well-known client-side implementations for both OpenID Connect and SAML protocols.
1.2.1. OpenID Connect
Java
-
Keycloak Wildfly Adapter (Deprecated)
-
Keycloak Tomcat Adapter (Deprecated)
-
Keycloak Jetty 9 (Deprecated)
-
Keycloak Servlet Filter (Deprecated)
-
Keycloak Spring Boot (Deprecated)
-
Keycloak Spring Security (Deprecated)
1.3. Terminology
These terms are used in this guide:
-
Clients
are entities that interact with Keycloak to authenticate users and obtain tokens. Most often, clients are applications and services acting on behalf of users that provide a single sign-on experience to their users and access other services using the tokens issued by the server. Clients can also be entities only interested in obtaining tokens and acting on their own behalf for accessing other services. -
Applications
include a wide range of applications that work for specific platforms for each protocol -
Client adapters
are libraries that make it easy to secure applications and services with Keycloak. They provide a tight integration to the underlying platform and framework. -
Creating a client
andregistering a client
are the same action.Creating a Client
is the term used to create a client by using the Admin Console.Registering a client
is the term used to register a client by using the Keycloak Client Registration Service. -
A service account
is a type of client that is able to obtain tokens on its own behalf.
2. Using OpenID Connect to secure applications and services
This section describes how you can secure applications and services with OpenID Connect using Keycloak.
2.1. Available Endpoints
As a fully-compliant OpenID Connect Provider implementation, Keycloak exposes a set of endpoints that applications and services can use to authenticate and authorize their users.
This section describes some of the key endpoints that your application and service should use when interacting with Keycloak.
2.1.1. Endpoints
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:
/realms/{realm-name}/.well-known/openid-configuration
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.
Authorization endpoint
/realms/{realm-name}/protocol/openid-connect/auth
The authorization endpoint performs authentication of the end-user. This authentication is done by redirecting the user agent to this endpoint.
For more details see the Authorization Endpoint section in the OpenID Connect specification.
Token endpoint
/realms/{realm-name}/protocol/openid-connect/token
The token endpoint is used to obtain tokens. Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used. The token endpoint is also used to obtain new access tokens when they expire.
For more details, see the Token Endpoint section in the OpenID Connect specification.
Userinfo endpoint
/realms/{realm-name}/protocol/openid-connect/userinfo
The userinfo endpoint returns standard claims about the authenticated user; this endpoint is protected by a bearer token.
For more details, see the Userinfo Endpoint section in the OpenID Connect specification.
Logout endpoint
/realms/{realm-name}/protocol/openid-connect/logout
The logout endpoint logs out the authenticated user.
The user agent can be redirected to the endpoint, which causes the active user session to be logged out. The user agent is then redirected back to the application.
The endpoint can also be invoked directly by the application. To invoke this endpoint directly, the refresh token needs to be included as well as the credentials required to authenticate the client.
Certificate endpoint
/realms/{realm-name}/protocol/openid-connect/certs
The certificate endpoint returns the public keys enabled by the realm, encoded as a JSON Web Key (JWK). Depending on the realm settings, one or more keys can be enabled for verifying tokens. For more information, see the Server Administration Guide and the JSON Web Key specification.
Introspection endpoint
/realms/{realm-name}/protocol/openid-connect/token/introspect
The introspection endpoint is used to retrieve the active state of a token. In other words, you can use it to validate an access or refresh token. This endpoint can only be invoked by confidential clients.
For more details on how to invoke on this endpoint, see OAuth 2.0 Token Introspection specification.
Dynamic Client Registration endpoint
/realms/{realm-name}/clients-registrations/openid-connect
The dynamic client registration endpoint is used to dynamically register clients.
For more details, see the Client Registration chapter and the OpenID Connect Dynamic Client Registration specification.
Token Revocation endpoint
/realms/{realm-name}/protocol/openid-connect/revoke
The token revocation endpoint is used to revoke tokens. Both refresh tokens and access tokens are supported by this endpoint. When revoking a refresh token, the user consent for the corresponding client is also revoked.
For more details on how to invoke on this endpoint, see OAuth 2.0 Token Revocation specification.
Device Authorization endpoint
/realms/{realm-name}/protocol/openid-connect/auth/device
The device authorization endpoint is used to obtain a device code and a user code. It can be invoked by confidential or public clients.
For more details on how to invoke on this endpoint, see OAuth 2.0 Device Authorization Grant specification.
Backchannel Authentication endpoint
/realms/{realm-name}/protocol/openid-connect/ext/ciba/auth
The backchannel authentication endpoint is used to obtain an auth_req_id that identifies the authentication request made by the client. It can only be invoked by confidential clients.
For more details on how to invoke on this endpoint, see OpenID Connect Client Initiated Backchannel Authentication Flow specification.
Also refer to other places of Keycloak documentation like Client Initiated Backchannel Authentication Grant section of this guide and Client Initiated Backchannel Authentication Grant section of Server Administration Guide.
2.2. Supported Grant Types
This section describes the different grant types available to relaying parties.
2.2.1. Authorization code
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.
2.2.2. Implicit
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.
2.2.3. Resource Owner Password Credentials
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:
-
User credentials are exposed to the application
-
Applications need login pages
-
Application needs to be aware of the authentication scheme
-
Changes to authentication flow requires changes to application
-
No support for identity brokering or social login
-
Flows are not supported (user self-registration, required actions, and so on.)
Security concerns with this flow include:
-
Involving more than Keycloak in handling of credentials
-
Increased vulnerable surface area where credential leaks can happen
-
Creating an ecosystem where users trust another application for entering their credentials and not Keycloak
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.
Example using CURL
The following example shows how to obtain an access token for a user in the realm master
with username user
and password password
. The example is using
the confidential client myclient
:
curl \
-d "client_id=myclient" \
-d "client_secret=40cc097b-2a57-4c17-b36a-8fdf3fc2d578" \
-d "username=user" \
-d "password=password" \
-d "grant_type=password" \
"http://localhost:8080/realms/master/protocol/openid-connect/token"
2.2.4. Client credentials
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.
2.2.5. Device Authorization Grant
Device Authorization Grant is used by clients running on internet-connected devices that have limited input capabilities or lack a suitable browser.
-
The application requests that Keycloak provide a device code and a user code.
-
Keycloak creates a device code and a user code.
-
Keycloak returns a response including the device code and the user code to the application.
-
The application provides the user with the user code and the verification URI. The user accesses a verification URI to be authenticated by using another browser.
-
The application repeatedly polls Keycloak until Keycloak completes the user authorization.
-
If user authentication is complete, the application obtains the device code.
-
The application uses the device code along with its credentials to obtain an Access Token, Refresh Token and ID Token from Keycloak.
For more details, see the OAuth 2.0 Device Authorization Grant specification.
2.2.6. Client Initiated Backchannel Authentication Grant
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.
2.3. Keycloak Java adapters
Keycloak Java Adapters are now deprecated and will be removed in a future release. No further enhancements or features will be added to the adapters until then. For more details about how to integrate Keycloak with Java applications, consider looking at the Keycloak Quickstart GitHub Repository. |
Keycloak comes with a range of different adapters for Java application. Selecting the correct adapter depends on the target platform.
All Java adapters share a set of common configuration options described in the Java Adapters Config chapter.
2.3.1. Configuration
Each Java adapter supported by Keycloak can be configured by a simple JSON file. This is what one might look like:
{
"realm" : "demo",
"resource" : "customer-portal",
"realm-public-key" : "MIGfMA0GCSqGSIb3D...31LwIDAQAB",
"auth-server-url" : "https://localhost:8443",
"ssl-required" : "external",
"use-resource-role-mappings" : false,
"enable-cors" : true,
"cors-max-age" : 1000,
"cors-allowed-methods" : "POST, PUT, DELETE, GET",
"cors-exposed-headers" : "WWW-Authenticate, My-custom-exposed-Header",
"bearer-only" : false,
"enable-basic-auth" : false,
"expose-token" : true,
"verify-token-audience" : true,
"credentials" : {
"secret" : "234234-234234-234234"
},
"connection-pool-size" : 20,
"socket-timeout-millis" : 5000,
"connection-timeout-millis" : 6000,
"connection-ttl-millis" : 500,
"disable-trust-manager" : false,
"allow-any-hostname" : false,
"truststore" : "path/to/truststore.jks",
"truststore-password" : "geheim",
"client-keystore" : "path/to/client-keystore.jks",
"client-keystore-password" : "geheim",
"client-key-password" : "geheim",
"token-minimum-time-to-live" : 10,
"min-time-between-jwks-requests" : 10,
"public-key-cache-ttl" : 86400,
"redirect-rewrite-rules" : {
"^/wsmaster/api/(.*)$" : "/api/$1"
}
}
You can use ${…}
enclosure for system property replacement. For example ${jboss.server.config.dir}
would be replaced by /path/to/Keycloak
.
Replacement of environment variables is also supported via the env
prefix, for example ${env.MY_ENVIRONMENT_VARIABLE}
. You can also define a default value ${…:default_value}
, which is used if the system property ${jboss.server.config.dir:default_value}
or the environment variable ${env.MY_ENVIRONMENT_VARIABLE:default_value}
is absent.
The initial config file can be obtained from the admin console. This can be done by opening the admin console, select Clients
from the menu and clicking
on the corresponding client. Once the page for the client is opened click on the Installation
tab and select Keycloak OIDC JSON
.
Here is a description of each configuration option:
- realm
-
REQUIRED. Name of the realm.
- resource
-
REQUIRED. The client-id of the application. Each application has a client-id that is used to identify the application.
- realm-public-key
-
OPTIONAL and it’s not recommended to set it. PEM format of the realm public key. You can obtain this from the Admin Console. If not set, the adapter will download this from Keycloak and it will always re-download it when needed (e.g. Keycloak rotates its keys). However if realm-public-key is set, then adapter will never download new keys from Keycloak, so when Keycloak rotate its keys, adapter will break.
- auth-server-url
-
REQUIRED. The base URL of the Keycloak server. All other Keycloak pages and REST service endpoints are derived from this. It is usually of the form
https://host:port
. - ssl-required
-
OPTIONAL. Ensures that all communication to and from the Keycloak server is over HTTPS. In production this should be set to
all
.The default value is _external_ meaning that HTTPS is required by default for external requests. Valid values are 'all', 'external' and 'none'.
- confidential-port
-
OPTIONAL. The confidential port used by the Keycloak server for secure connections over SSL/TLS. The default value is 8443.
- use-resource-role-mappings
-
OPTIONAL. If set to true, the adapter will look inside the token for application level role mappings for the user. If false, it will look at the realm level for user role mappings. The default value is false.
- public-client
-
OPTIONAL. If set to true, the adapter will not send credentials for the client to Keycloak. The default value is false.
- enable-cors
-
OPTIONAL. This enables CORS support. It will handle CORS preflight requests. It will also look into the access token to determine valid origins. The default value is false.
- cors-max-age
-
OPTIONAL. If CORS is enabled, this sets the value of the
Access-Control-Max-Age
header. If not set, this header is not returned in CORS responses. - cors-allowed-methods
-
OPTIONAL. If CORS is enabled, this sets the value of the
Access-Control-Allow-Methods
header. This should be a comma-separated string. If not set, this header is not returned in CORS responses. - cors-allowed-headers
-
OPTIONAL. If CORS is enabled, this sets the value of the
Access-Control-Allow-Headers
header. This should be a comma-separated string. If not set, this header is not returned in CORS responses. - cors-exposed-headers
-
OPTIONAL. If CORS is enabled, this sets the value of the
Access-Control-Expose-Headers
header. This should be a comma-separated string. If not set, this header is not returned in CORS responses. - bearer-only
-
OPTIONAL. This should be set to true for services. If enabled the adapter will not attempt to authenticate users, but only verify bearer tokens. The default value is false.
- autodetect-bearer-only
-
This should be set to true if your application serves both a web application and web services (for example SOAP or REST). It allows you to redirect unauthenticated users of the web application to the Keycloak login page, but send an HTTP
401
status code to unauthenticated SOAP or REST clients instead as they would not understand a redirect to the login page. Keycloak auto-detects SOAP or REST clients based on typical headers likeX-Requested-With
,SOAPAction
orAccept
. The default value is false. - enable-basic-auth
-
OPTIONAL. This tells the adapter to also support basic authentication. If this option is enabled, then secret must also be provided. The default value is false.
- expose-token
-
OPTIONAL. If
true
, an authenticated browser client (via a JavaScript HTTP invocation) can obtain the signed access token via the URLroot/k_query_bearer_token
. The default value is false. - credentials
-
REQUIRED only for clients with 'Confidential' access type. Specify the credentials of the application. This is an object notation where the key is the credential type and the value is the value of the credential type. Currently password and jwt is supported. T
- connection-pool-size
-
OPTIONAL. This config option defines how many connections to the Keycloak server should be pooled. The default value is
20
. - socket-timeout-millis
-
OPTIONAL. Timeout for socket waiting for data after establishing the connection in milliseconds. Maximum time of inactivity between two data packets. A timeout value of zero is interpreted as an infinite timeout. A negative value is interpreted as undefined (system default if applicable). The default value is
-1
. - connection-timeout-millis
-
Timeout for establishing the connection with the remote host in milliseconds. A timeout value of zero is interpreted as an infinite timeout. A negative value is interpreted as undefined (system default if applicable). The default value is
-1
. - connection-ttl-millis
-
OPTIONAL. Connection time-to-live for client in milliseconds. A value less than or equal to zero is interpreted as an infinite value. The default value is
-1
. - disable-trust-manager
-
OPTIONAL. If the Keycloak server requires HTTPS and this config option is set to
true
you do not have to specify a truststore. This setting should only be used during development and never in production as it will disable verification of SSL certificates. The default value isfalse
. - allow-any-hostname
-
OPTIONAL. If the Keycloak server requires HTTPS and this config option is set to
true
the Keycloak server’s certificate is validated via the truststore, but host name validation is not done. This setting should only be used during development and never in production as it will disable verification of SSL certificates. This setting may be useful in test environments This is OPTIONAL. The default value isfalse
. - proxy-url
-
The URL for the HTTP proxy if one is used.
- truststore
-
The value is the file path to a truststore file. If you prefix the path with
classpath:
, then the truststore will be obtained from the deployment’s classpath instead. Used for outgoing HTTPS communications to the Keycloak server. Client making HTTPS requests need a way to verify the host of the server they are talking to. This is what the truststore does. The keystore contains one or more trusted host certificates or certificate authorities. You can create this truststore by extracting the public certificate of the Keycloak server’s SSL keystore. REQUIRED unlessssl-required
isnone
ordisable-trust-manager
istrue
. - truststore-password
-
Password for the truststore. REQUIRED if
truststore
is set and the truststore requires a password. - client-keystore
-
OPTIONAL. This is the file path to a keystore file. This keystore contains client certificate for two-way SSL when the adapter makes HTTPS requests to the Keycloak server.
- client-keystore-password
-
REQUIRED if
client-keystore
is set. Password for the client keystore. - client-key-password
-
REQUIRED if
client-keystore
is set. Password for the client’s key. - always-refresh-token
-
If true, the adapter will refresh token in every request. Warning - when enabled this will result in a request to Keycloak for every request to your application.
- register-node-at-startup
-
If true, then adapter will send registration request to Keycloak. It’s false by default and useful only when application is clustered. See Application Clustering for details
- register-node-period
-
Period for re-registration adapter to Keycloak. Useful when application is clustered. See Application Clustering for details
- token-store
-
Possible values are session and cookie. Default is session, which means that adapter stores account info in HTTP Session. Alternative cookie means storage of info in cookie. See Application Clustering for details
- token-cookie-path
-
When using a cookie store, this option sets the path of the cookie used to store account info. If it’s a relative path, then it is assumed that the application is running in a context root, and is interpreted relative to that context root. If it’s an absolute path, then the absolute path is used to set the cookie path. Defaults to use paths relative to the context root.
- principal-attribute
-
OpenID Connect ID Token attribute to populate the UserPrincipal name with. If token attribute is null, defaults to
sub
. Possible values aresub
,preferred_username
,email
,name
,nickname
,given_name
,family_name
. - turn-off-change-session-id-on-login
-
OPTIONAL. The session id is changed by default on a successful login on some platforms to plug a security attack vector. Change this to true if you want to turn this off The default value is false.
- token-minimum-time-to-live
-
OPTIONAL. Amount of time, in seconds, to preemptively refresh an active access token with the Keycloak server before it expires. This is especially useful when the access token is sent to another REST client where it could expire before being evaluated. This value should never exceed the realm’s access token lifespan. The default value is
0
seconds, so adapter will refresh access token just if it’s expired. - min-time-between-jwks-requests
-
Amount of time, in seconds, specifying minimum interval between two requests to Keycloak to retrieve new public keys. It is 10 seconds by default. Adapter will always try to download new public key when it recognizes token with unknown
kid
. However it won’t try it more than once per 10 seconds (by default). This is to avoid DoS when attacker sends lots of tokens with badkid
forcing adapter to send lots of requests to Keycloak. - public-key-cache-ttl
-
Amount of time, in seconds, specifying maximum interval between two requests to Keycloak to retrieve new public keys. It is 86400 seconds (1 day) by default. Adapter will always try to download new public key when it recognizes token with unknown
kid
. If it recognizes token with knownkid
, it will just use the public key downloaded previously. However at least once per this configured interval (1 day by default) will be new public key always downloaded even if thekid
of token is already known. - ignore-oauth-query-parameter
-
Defaults to
false
, if set totrue
will turn off processing of theaccess_token
query parameter for bearer token processing. Users will not be able to authenticate if they only pass in anaccess_token
- redirect-rewrite-rules
-
If needed, specify the Redirect URI rewrite rule. This is an object notation where the key is the regular expression to which the Redirect URI is to be matched and the value is the replacement String.
$
character can be used for backreferences in the replacement String. - verify-token-audience
-
If set to
true
, then during authentication with the bearer token, the adapter will verify whether the token contains this client name (resource) as an audience. The option is especially useful for services, which primarily serve requests authenticated by the bearer token. This is set tofalse
by default, however for improved security, it is recommended to enable this. See Audience Support for more details about audience
2.3.2. JBoss EAP/WildFly adapter
Keycloak provided this adapter in the past, but it is not provided anymore.
We recommend that you switch to the Elytron OIDC library to secure your applications. This library has a similar configuration to the Keycloak WildFly adapters, so you can expect a smooth migration of your applications if you used this adapter with the older Keycloak versions.
Elytron OIDC library works with WildFly 28 or newer versions. For the older WildFly versions or for JBoss EAP 7, it is recommended to upgrade to newer WildFly/EAP or look for some alternative OIDC client library. Otherwise, you will need to stick with the older Keycloak adapters, but those are not maintained and officially supported.
For more details on how to integrate Keycloak with JakartaEE applications running on latest Wildfly/EAP, take a look at the Jakarta EE quickstarts within the Keycloak Quickstart GitHub Repository.
2.3.3. Spring Boot adapter
This adapter is deprecated and will be removed in a future release of Keycloak. No further enhancements or new features will be added to this adapter. We recommend that you leverage the OAuth2/OpenID Connect support from Spring Security. For more details about how to integrate Keycloak with Spring Boot applications, consider looking at the Keycloak Quickstart GitHub Repository. |
Installing the Spring Boot adapter
To be able to secure Spring Boot apps you must add the Keycloak Spring Boot adapter JAR to your app.
You then have to provide some extra configuration via normal Spring Boot configuration (application.properties
).
The Keycloak Spring Boot adapter takes advantage of Spring Boot’s autoconfiguration so all you need to do is add this adapter Keycloak Spring Boot starter to your project.
-
To add the starter to your project using Maven, add the following to your dependencies:
<dependency> <groupId>org.keycloak</groupId> <artifactId>keycloak-spring-boot-starter</artifactId> </dependency>
-
Add the Adapter BOM dependency:
<dependencyManagement> <dependencies> <dependency> <groupId>org.keycloak.bom</groupId> <artifactId>keycloak-adapter-bom</artifactId> <version>23.0.2</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>
Currently the following embedded containers are supported and do not require any extra dependencies if using the Starter:
-
Tomcat
-
Undertow
-
Jetty
Configuring the Spring Boot Adapter
Use the procedure to configure your Spring Boot app to use Keycloak.
-
Instead of a
keycloak.json
file, you configure the realm for the Spring Boot adapter via the normal Spring Boot configuration. For example:keycloak.realm = demorealm keycloak.auth-server-url = http://127.0.0.1:8080 keycloak.ssl-required = external keycloak.resource = demoapp keycloak.credentials.secret = 11111111-1111-1111-1111-111111111111 keycloak.use-resource-role-mappings = true
You can disable the Keycloak Spring Boot Adapter (for example in tests) by setting
keycloak.enabled = false
. -
To configure a Policy Enforcer, unlike keycloak.json, use
policy-enforcer-config
instead of justpolicy-enforcer
. -
Specify the Jakarta EE security config that would normally go in the
web.xml
.The Spring Boot Adapter will set the
login-method
toKEYCLOAK
and configure thesecurity-constraints
at startup time. Here’s an example configuration:keycloak.securityConstraints[0].authRoles[0] = admin keycloak.securityConstraints[0].authRoles[1] = user keycloak.securityConstraints[0].securityCollections[0].name = insecure stuff keycloak.securityConstraints[0].securityCollections[0].patterns[0] = /insecure keycloak.securityConstraints[1].authRoles[0] = admin keycloak.securityConstraints[1].securityCollections[0].name = admin stuff keycloak.securityConstraints[1].securityCollections[0].patterns[0] = /admin
If you plan to deploy your Spring Application as a WAR then you should not use the Spring Boot Adapter and use the dedicated adapter for the application server or servlet container you are using. Your Spring Boot should also contain a web.xml file.
|
2.3.4. Tomcat 8 and 9 adapters
This adapter is deprecated and will be removed in a future release of Keycloak. No further enhancements or new features will be added to this adapter. |
To be able to secure WAR apps deployed on Tomcat 8, and 9, you install the Keycloak Tomcat adapter into your Tomcat installation. You then perform extra configuration to secure each WAR you deploy to Tomcat.
Installing the adapter
Adapters are no longer included with the appliance or war distribution. Each adapter is a separate download on the Keycloak Downloads site. They are also available as a maven artifact.
-
Download the adapter for the Tomcat version on your system from the Keycloak Downloads site.
-
Install on Tomcat 8 or 9:
$ cd $TOMCAT_HOME/lib $ unzip keycloak-tomcat-adapter-dist.zip
-
Including the adapter’s jars within your WEB-INF/lib directory will not work. The Keycloak adapter is implemented as a Valve and valve code must reside in Tomcat’s main lib/ directory. |
Securing a WAR
This section describes how to secure a WAR directly by adding config and editing files within your WAR package.
-
Create a
META-INF/context.xml
file in your WAR package.This is a Tomcat specific config file and you must define a Keycloak specific Valve.
<Context path="/your-context-path"> <Valve className="org.keycloak.adapters.tomcat.KeycloakAuthenticatorValve"/> </Context>
-
Create a
keycloak.json
adapter config file within theWEB-INF
directory of your WAR.The format of this config file is described in the Java adapter configuration
-
Specify both a
login-config
and use standard servlet security to specify role-base constraints on your URLs. Here’s an example:<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" version="3.0"> <module-name>customer-portal</module-name> <security-constraint> <web-resource-collection> <web-resource-name>Customers</web-resource-name> <url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>user</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>BASIC</auth-method> <realm-name>this is ignored currently</realm-name> </login-config> <security-role> <role-name>admin</role-name> </security-role> <security-role> <role-name>user</role-name> </security-role> </web-app>
2.3.5. Jetty 9.4 adapter
This adapter is deprecated and will be removed in a future release of Keycloak. No further enhancements or new features will be added to this adapter. |
Keycloak has a separate adapter for Jetty 9.4 that you will have to install into your Jetty installation. You then have to provide some extra configuration in each WAR you deploy to Jetty.
Installing the adapter
Adapters are no longer included with the appliance or war distribution. Each adapter is a separate download on the Keycloak downloads site. They are also available as a maven artifact.
-
Download the Keycloak Jetty 9.4 adapter ZIP archive from the Keycloak Downloads site.
-
Unzip the Jetty 9.4 distro into Jetty 9.4’s base directory. In the example below, the Jetty base is named
your-base
:$ cd your-base $ unzip keycloak-jetty94-adapter-dist-23.0.2.Final.zip
-
Enable the
keycloak
module for your Jetty base:$ java -jar $JETTY_HOME/start.jar --add-to-startd=keycloak
Including the adapter’s jars within your WEB-INF/lib directory will not work.
Jetty 9 Securing a WAR
Use this procedure to secure a WAR directly by adding config and editing files within your WAR package.
-
Create a
WEB-INF/jetty-web.xml
file in your WAR package. This is a Jetty specific config fil. You define a Keycloak specific authenticator within it.<?xml version="1.0"?> <!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Get name="securityHandler"> <Set name="authenticator"> <New class="org.keycloak.adapters.jetty.KeycloakJettyAuthenticator"> </New> </Set> </Get> </Configure>
-
Create a
keycloak.json
adapter config file within theWEB-INF
directory of your WAR.The format of this config file is described in the Java adapter configuration section.
The Jetty 9.4 adapter will not be able to find the keycloak.json
file. You will have to define all adapter settings within thejetty-web.xml
file as described below. Instead of using keycloak.json, you can define everything within thejetty-web.xml
. You’ll just have to figure out how the json settings match to theorg.keycloak.representations.adapters.config.AdapterConfig
class.<?xml version="1.0"?> <!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Get name="securityHandler"> <Set name="authenticator"> <New class="org.keycloak.adapters.jetty.KeycloakJettyAuthenticator"> <Set name="adapterConfig"> <New class="org.keycloak.representations.adapters.config.AdapterConfig"> <Set name="realm">tomcat</Set> <Set name="resource">customer-portal</Set> <Set name="authServerUrl">http://localhost:8081</Set> <Set name="sslRequired">external</Set> <Set name="credentials"> <Map> <Entry> <Item>secret</Item> <Item>password</Item> </Entry> </Map> </Set> </New> </Set> </New> </Set> </Get> </Configure>
-
Create the jetty-web.xml file in your webapps directory with the name of yourwar.xml. Jetty should pick it up. You do not need to open your WAR to secure it with Keycloak. In this mode, you declare keycloak.json configuration directly within the xml file.
-
Specify both a
login-config
and use standard servlet security to specify role-base constraints on your URLs. Here’s an example:<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" version="3.0"> <module-name>customer-portal</module-name> <security-constraint> <web-resource-collection> <web-resource-name>Customers</web-resource-name> <url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>user</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> </security-constraint> <login-config> <auth-method>BASIC</auth-method> <realm-name>this is ignored currently</realm-name> </login-config> <security-role> <role-name>admin</role-name> </security-role> <security-role> <role-name>user</role-name> </security-role> </web-app>
2.3.6. Spring Security adapter
This adapter is deprecated and will be removed in a future release of Keycloak. No further enhancements or new features will be added to this adapter. We recommend that you leverage the OAuth2/OpenID Connect support from Spring Security. For more details about how to integrate Keycloak with Spring Boot applications, consider looking at the Keycloak Quickstart GitHub Repository. |
To secure an application with Spring Security and Keycloak, add this adapter as a dependency to your project. You then have to provide some extra beans in your Spring Security configuration file and add the Keycloak security filter to your pipeline.
Unlike the other Keycloak Adapters, you should not configure your security in web.xml. However, keycloak.json is still required. In order for Single Sign Out to work properly you have to define a session listener.
-
in web.xml (for pure Spring Security environments):
<listener> <listener-class>org.springframework.security.web.session.HttpSessionEventPublisher</listener-class> </listener>
-
as a Spring bean (in Spring Boot environments using Spring Security adapter)
@Bean public ServletListenerRegistrationBean<HttpSessionEventPublisher> httpSessionEventPublisher() { return new ServletListenerRegistrationBean<HttpSessionEventPublisher>(new HttpSessionEventPublisher()); }
Installing the adapter
Add Keycloak Spring Security adapter as a dependency to your Maven POM or Gradle build.
<dependency>
<groupId>org.keycloak</groupId>
<artifactId>keycloak-spring-security-adapter</artifactId>
<version>23.0.2</version>
</dependency>
Configuring the Spring Security Adapter
The Keycloak Spring Security adapter takes advantage of Spring Security’s flexible security configuration syntax.
Java configuration
Keycloak provides a KeycloakWebSecurityConfigurerAdapter as a convenient base class for creating a WebSecurityConfigurer instance. The implementation allows customization by overriding methods. While its use is not required, it greatly simplifies your security context configuration.
@KeycloakConfiguration
public class SecurityConfig extends KeycloakWebSecurityConfigurerAdapter
{
/**
* Registers the KeycloakAuthenticationProvider with the authentication manager.
*/
@Autowired
public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
auth.authenticationProvider(keycloakAuthenticationProvider());
}
/**
* Defines the session authentication strategy.
*/
@Bean
@Override
protected SessionAuthenticationStrategy sessionAuthenticationStrategy() {
return new RegisterSessionAuthenticationStrategy(buildSessionRegistry());
}
@Bean
protected SessionRegistry buildSessionRegistry() {
return new SessionRegistryImpl();
}
@Override
protected void configure(HttpSecurity http) throws Exception
{
super.configure(http);
http
.authorizeRequests()
.antMatchers("/customers*").hasRole("USER")
.antMatchers("/admin*").hasRole("ADMIN")
.anyRequest().permitAll();
}
}
You must provide a session authentication strategy bean which should be of type RegisterSessionAuthenticationStrategy
for public or confidential applications and NullAuthenticatedSessionStrategy
for bearer-only applications.
Spring Security’s SessionFixationProtectionStrategy
is currently not supported because it changes the session identifier after login via Keycloak.
If the session identifier changes, universal log out will not work because Keycloak is unaware of the new session identifier.
The @KeycloakConfiguration annotation is a metadata annotation that defines all annotations that are needed to integrate
Keycloak in Spring Security. If you have a complex Spring Security setup you can simply have a look at the annotations of
the @KeycloakConfiguration annotation and create your own custom meta annotation or just use specific Spring annotations
for the Keycloak adapter.
|
XML configuration
While Spring Security’s XML namespace simplifies configuration, customizing the configuration can be a bit verbose.
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:security="http://www.springframework.org/schema/security"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd
http://www.springframework.org/schema/security
http://www.springframework.org/schema/security/spring-security.xsd">
<context:component-scan base-package="org.keycloak.adapters.springsecurity" />
<security:authentication-manager alias="authenticationManager">
<security:authentication-provider ref="keycloakAuthenticationProvider" />
</security:authentication-manager>
<bean id="adapterDeploymentContext" class="org.keycloak.adapters.springsecurity.AdapterDeploymentContextFactoryBean">
<constructor-arg value="/WEB-INF/keycloak.json" />
</bean>
<bean id="keycloakAuthenticationEntryPoint" class="org.keycloak.adapters.springsecurity.authentication.KeycloakAuthenticationEntryPoint">
<constructor-arg ref="adapterDeploymentContext" />
</bean>
<bean id="keycloakAuthenticationProvider" class="org.keycloak.adapters.springsecurity.authentication.KeycloakAuthenticationProvider" />
<bean id="keycloakPreAuthActionsFilter" class="org.keycloak.adapters.springsecurity.filter.KeycloakPreAuthActionsFilter" />
<bean id="keycloakAuthenticationProcessingFilter" class="org.keycloak.adapters.springsecurity.filter.KeycloakAuthenticationProcessingFilter">
<constructor-arg name="authenticationManager" ref="authenticationManager" />
</bean>
<bean id="keycloakSecurityContextRequestFilter"
class="org.keycloak.adapters.springsecurity.filter.KeycloakSecurityContextRequestFilter" />
<bean id="keycloakSecurityContextRequestFilter"
class="org.keycloak.adapters.springsecurity.filter.KeycloakSecurityContextRequestFilter" />
<bean id="keycloakLogoutHandler" class="org.keycloak.adapters.springsecurity.authentication.KeycloakLogoutHandler">
<constructor-arg ref="adapterDeploymentContext" />
</bean>
<bean id="logoutFilter" class="org.springframework.security.web.authentication.logout.LogoutFilter">
<constructor-arg name="logoutSuccessUrl" value="/" />
<constructor-arg name="handlers">
<list>
<ref bean="keycloakLogoutHandler" />
<bean class="org.springframework.security.web.authentication.logout.SecurityContextLogoutHandler" />
</list>
</constructor-arg>
<property name="logoutRequestMatcher">
<bean class="org.springframework.security.web.util.matcher.AntPathRequestMatcher">
<constructor-arg name="pattern" value="/sso/logout**" />
<constructor-arg name="httpMethod" value="GET" />
</bean>
</property>
</bean>
<security:http auto-config="false" entry-point-ref="keycloakAuthenticationEntryPoint">
<security:custom-filter ref="keycloakPreAuthActionsFilter" before="LOGOUT_FILTER" />
<security:custom-filter ref="keycloakAuthenticationProcessingFilter" before="FORM_LOGIN_FILTER" />
<security:custom-filter ref="keycloakSecurityContextRequestFilter" after="FORM_LOGIN_FILTER" />
<security:intercept-url pattern="/customers**" access="ROLE_USER" />
<security:intercept-url pattern="/admin**" access="ROLE_ADMIN" />
<security:custom-filter ref="logoutFilter" position="LOGOUT_FILTER" />
</security:http>
</beans>
Multi Tenancy
The Keycloak Spring Security adapter also supports Multi Tenancy.
Instead of injecting AdapterDeploymentContextFactoryBean
with the path to keycloak.json
you can inject an implementation of the KeycloakConfigResolver
interface.
More details on how to implement the KeycloakConfigResolver
can be found in Multi Tenancy.
Naming security roles
Spring Security, when using role-based authentication, requires that role names start with ROLE_
.
For example, an administrator role must be declared in Keycloak as ROLE_ADMIN
or similar, not simply ADMIN
.
The class org.keycloak.adapters.springsecurity.authentication.KeycloakAuthenticationProvider
supports an optional org.springframework.security.core.authority.mapping.GrantedAuthoritiesMapper
which can be used to map roles coming from Keycloak to roles recognized by Spring Security.
Use, for example, org.springframework.security.core.authority.mapping.SimpleAuthorityMapper
, which allows for case conversion and the addition of a prefix (which defaults to ROLE_
).
The following code will convert the role names to upper case and, by default, add the ROLE_
prefix to them:
@KeycloakConfiguration
public class SecurityConfig extends KeycloakWebSecurityConfigurerAdapter {
@Autowired
public void configureGlobal(AuthenticationManagerBuilder auth) {
auth.authenticationProvider(getKeycloakAuthenticationProvider());
}
private KeycloakAuthenticationProvider getKeycloakAuthenticationProvider() {
KeycloakAuthenticationProvider authenticationProvider = keycloakAuthenticationProvider();
SimpleAuthorityMapper mapper = new SimpleAuthorityMapper();
mapper.setConvertToUpperCase(true);
authenticationProvider.setGrantedAuthoritiesMapper(mapper);
return authenticationProvider;
}
...
}
Client to Client Support
To simplify communication between clients, Keycloak provides an extension of Spring’s RestTemplate
that handles bearer token authentication for you.
To enable this feature your security configuration must add the KeycloakRestTemplate
bean.
Note that it must be scoped as a prototype to function correctly.
For Java configuration:
@Configuration
@EnableWebSecurity
@ComponentScan(basePackageClasses = KeycloakSecurityComponents.class)
public class SecurityConfig extends KeycloakWebSecurityConfigurerAdapter {
...
@Autowired
public KeycloakClientRequestFactory keycloakClientRequestFactory;
@Bean
@Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE)
public KeycloakRestTemplate keycloakRestTemplate() {
return new KeycloakRestTemplate(keycloakClientRequestFactory);
}
...
}
For XML configuration:
<bean id="keycloakRestTemplate" class="org.keycloak.adapters.springsecurity.client.KeycloakRestTemplate" scope="prototype">
<constructor-arg name="factory" ref="keycloakClientRequestFactory" />
</bean>
Your application code can then use KeycloakRestTemplate
any time it needs to make a call to another client.
For example:
@Service
public class RemoteProductService implements ProductService {
@Autowired
private KeycloakRestTemplate template;
private String endpoint;
@Override
public List<String> getProducts() {
ResponseEntity<String[]> response = template.getForEntity(endpoint, String[].class);
return Arrays.asList(response.getBody());
}
}
Spring Boot Integration
The Spring Boot and the Spring Security adapters can be combined.
If you are using the Keycloak Spring Boot Starter to make use of the Spring Security adapter you just need to add the Spring Security starter :
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
Using Spring Boot Configuration
By Default, the Spring Security Adapter looks for a keycloak.json
configuration file. You can make sure it looks at the configuration provided by the Spring Boot Adapter by adding this bean:
@Configuration
public class CustomKeycloakConfig {
@Bean
public KeycloakConfigResolver keycloakConfigResolver() {
return new KeycloakSpringBootConfigResolver();
}
}
Do not declare the KeycloakConfigResolver
bean in a configuration class that extends KeycloakWebSecurityConfigurerAdapter
as this will cause a Circular References
problem in Spring Boot starting with version 2.6.0.
Avoid double bean registration
Spring Boot attempts to eagerly register filter beans with the web application context.
Therefore, when running the Keycloak Spring Security adapter in a Spring Boot environment, it may be necessary to add FilterRegistrationBean
s to your security configuration to prevent the Keycloak filters from being registered twice.
Spring Boot 2.1 also disables spring.main.allow-bean-definition-overriding
by default. This can mean that an BeanDefinitionOverrideException
will be encountered if a Configuration
class extending KeycloakWebSecurityConfigurerAdapter
registers a bean that is already detected by a @ComponentScan
. This can be avoided by overriding the registration to use the Boot-specific @ConditionalOnMissingBean
annotation, as with HttpSessionManager
below.
@Configuration
@EnableWebSecurity
public class SecurityConfig extends KeycloakWebSecurityConfigurerAdapter
{
...
@Bean
public FilterRegistrationBean keycloakAuthenticationProcessingFilterRegistrationBean(
KeycloakAuthenticationProcessingFilter filter) {
FilterRegistrationBean registrationBean = new FilterRegistrationBean(filter);
registrationBean.setEnabled(false);
return registrationBean;
}
@Bean
public FilterRegistrationBean keycloakPreAuthActionsFilterRegistrationBean(
KeycloakPreAuthActionsFilter filter) {
FilterRegistrationBean registrationBean = new FilterRegistrationBean(filter);
registrationBean.setEnabled(false);
return registrationBean;
}
@Bean
public FilterRegistrationBean keycloakAuthenticatedActionsFilterBean(
KeycloakAuthenticatedActionsFilter filter) {
FilterRegistrationBean registrationBean = new FilterRegistrationBean(filter);
registrationBean.setEnabled(false);
return registrationBean;
}
@Bean
public FilterRegistrationBean keycloakSecurityContextRequestFilterBean(
KeycloakSecurityContextRequestFilter filter) {
FilterRegistrationBean registrationBean = new FilterRegistrationBean(filter);
registrationBean.setEnabled(false);
return registrationBean;
}
@Bean
@Override
@ConditionalOnMissingBean(HttpSessionManager.class)
protected HttpSessionManager httpSessionManager() {
return new HttpSessionManager();
}
...
}
2.3.7. Java servlet filter adapter
This adapter is deprecated and will be removed in a future release of Keycloak. No further enhancements or new features will be added to this adapter. |
If you are deploying your Java Servlet application on a platform where there is no Keycloak adapter you opt to use the servlet filter adapter. This adapter works a bit differently than the other adapters. You do not define security constraints in web.xml. Instead you define a filter mapping using the Keycloak servlet filter adapter to secure the url patterns you want to secure.
Backchannel logout works a bit differently than the standard adapters. Instead of invalidating the HTTP session it marks the session id as logged out. There’s no standard way to invalidate an HTTP session based on a session id. |
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">
<module-name>application</module-name>
<filter>
<filter-name>Keycloak Filter</filter-name>
<filter-class>org.keycloak.adapters.servlet.KeycloakOIDCFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>Keycloak Filter</filter-name>
<url-pattern>/keycloak/*</url-pattern>
<url-pattern>/protected/*</url-pattern>
</filter-mapping>
</web-app>
In the snippet above there are two url-patterns. /protected/* are the files we want protected, while the /keycloak/* url-pattern handles callbacks from the Keycloak server.
If you need to exclude some paths beneath the configured url-patterns
you can use the Filter init-param keycloak.config.skipPattern
to configure
a regular expression that describes a path-pattern for which the keycloak filter should immediately delegate to the filter-chain.
By default no skipPattern is configured.
Patterns are matched against the requestURI
without the context-path
. Given the context-path /myapp
a request for /myapp/index.html
will be matched with /index.html
against the skip pattern.
<init-param>
<param-name>keycloak.config.skipPattern</param-name>
<param-value>^/(path1|path2|path3).*</param-value>
</init-param>
Note that you should configure your client in the Keycloak Admin Console with an Admin URL that points to a secured section covered by the filter’s url-pattern.
The Admin URL will make callbacks to the Admin URL to do things like backchannel logout.
So, the Admin URL in this example should be http[s]://hostname/{context-root}/keycloak
.
If you need to customize the session ID mapper, you can configure the fully qualified name of the class in the Filter init-param keycloak.config.idMapper. Session ID mapper is a mapper that is used to map user IDs and session IDs. By default org.keycloak.adapters.spi.InMemorySessionIdMapper is configured.
<init-param>
<param-name>keycloak.config.idMapper</param-name>
<param-value>org.keycloak.adapters.spi.InMemorySessionIdMapper</param-value>
</init-param>
The Keycloak filter has the same configuration parameters as the other adapters except you must define them as filter init params instead of context params.
To use this filter, include this maven artifact in your WAR poms:
<dependency>
<groupId>org.keycloak</groupId>
<artifactId>keycloak-servlet-filter-adapter</artifactId>
<version>23.0.2</version>
</dependency>
Using on OSGi
The servlet filter adapter is packaged as an OSGi bundle, and thus is usable in a generic OSGi environment (R6 and above) with HTTP Service and HTTP Whiteboard.
Installation
The adapter and its dependencies are distributed as Maven artifacts, so you’ll need either working Internet connection to access Maven Central, or have the artifacts cached in your local Maven repo.
If you are using Apache Karaf, you can simply install a feature from the Keycloak feature repo:
karaf@root()> feature:repo-add mvn:org.keycloak/keycloak-osgi-features/23.0.2/xml/features
karaf@root()> feature:install keycloak-servlet-filter-adapter
For other OSGi runtimes, please refer to the runtime documentation on how to install the adapter bundle and its dependencies.
If your OSGi platform is Apache Karaf with Pax Web, you should consider using Red Hat Single Sign-On 7.x JBoss Fuse 7 adapters instead. |
Configuration
First, the adapter needs to be registered as a servlet filter with the OSGi HTTP Service. The most common ways to do this are programmatic (for example via bundle activator) and declarative (using OSGi annotations). We recommend using the latter since it simplifies the process of dynamically registering and un-registering the filter:
package mypackage;
import javax.servlet.Filter;
import org.keycloak.adapters.servlet.KeycloakOIDCFilter;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.http.whiteboard.HttpWhiteboardConstants;
@Component(
immediate = true,
service = Filter.class,
property = {
KeycloakOIDCFilter.CONFIG_FILE_PARAM + "=" + "keycloak.json",
HttpWhiteboardConstants.HTTP_WHITEBOARD_FILTER_PATTERN + "=" +"/*",
HttpWhiteboardConstants.HTTP_WHITEBOARD_CONTEXT_SELECT + "=" + "(osgi.http.whiteboard.context.name=mycontext)"
}
)
public class KeycloakFilter extends KeycloakOIDCFilter {
//
}
The above snippet uses OSGi declarative service specification to expose the filter as an OSGI service under javax.servlet.Filter
class.
Once the class is published in the OSGi service registry, it is going to be picked up by OSGi HTTP Service implementation and used for filtering requests for the specified servlet context. This will trigger Keycloak adapter for every request that matches servlet context path + filter path.
Since the component is put under the control of OSGi Configuration Admin Service, it’s properties can be configured dynamically.
To do that, either create a mypackage.KeycloakFilter.cfg
file under the standard config location for your OSGi runtime:
keycloak.config.file = /path/to/keycloak.json
osgi.http.whiteboard.filter.pattern = /secure/*
or use interactive console, if your runtime allows for that:
karaf@root()> config:edit mypackage.KeycloakFilter
karaf@root()> config:property-set keycloak.config.file '${karaf.etc}/keycloak.json'
karaf@root()> config:update
If you need more control, for example, providing custom KeycloakConfigResolver
to implement multi tenancy, you can register the filter programmatically:
public class Activator implements BundleActivator {
private ServiceRegistration registration;
public void start(BundleContext context) throws Exception {
Hashtable props = new Hashtable();
props.put(HttpWhiteboardConstants.HTTP_WHITEBOARD_FILTER_PATTERN, "/secure/*");
props.put(KeycloakOIDCFilter.CONFIG_RESOLVER_PARAM, new MyConfigResolver());
this.registration = context.registerService(Filter.class.getName(), new KeycloakOIDCFilter(), props);
}
public void stop(BundleContext context) throws Exception {
this.registration.unregister();
}
}
Please refer to Apache Felix HTTP Service for more info on programmatic registration.
2.3.8. JAAS plugin
This adapter is deprecated and will be removed in a future release of Keycloak. No further enhancements or new features will be added to this adapter. |
It’s generally not needed to use JAAS for most of the applications, especially if they are HTTP based, and you should most likely choose one of our other adapters. However, some applications and systems may still rely on pure legacy JAAS solution. Keycloak provides two login modules to help in these situations.
The provided login modules are:
- org.keycloak.adapters.jaas.DirectAccessGrantsLoginModule
-
This login module allows to authenticate with username/password from Keycloak. It’s using Resource Owner Password Credentials flow to validate if the provided username/password is valid. It’s useful for non-web based systems, which need to rely on JAAS and want to use Keycloak, but can’t use the standard browser based flows due to their non-web nature. Example of such application could be messaging or SSH.
- org.keycloak.adapters.jaas.BearerTokenLoginModule
-
This login module allows to authenticate with Keycloak access token passed to it through CallbackHandler as password. It may be useful for example in case, when you have Keycloak access token from standard based authentication flow and your web application then needs to talk to external non-web based system, which rely on JAAS. For example a messaging system.
Both modules use the following configuration properties:
- keycloak-config-file
-
The location of the
keycloak.json
configuration file. The configuration file can either be located on the filesystem or on the classpath. If it’s located on the classpath you need to prefix the location withclasspath:
(for exampleclasspath:/path/keycloak.json
). This is REQUIRED. role-principal-class
-
Configure alternative class for Role principals attached to JAAS Subject. Default value is
org.keycloak.adapters.jaas.RolePrincipal
. Note: The class is required to have a constructor with a singleString
argument. scope
-
This option is only applicable to the
DirectAccessGrantsLoginModule
. The specified value will be used as the OAuth2scope
parameter in the Resource Owner Password Credentials Grant request.
2.3.9. CLI / Desktop Applications
Keycloak supports securing desktop
(for example Swing, JavaFX) or CLI applications via the
KeycloakInstalled
adapter by performing the authentication step via the system browser.
The KeycloakInstalled
adapter supports a desktop
and a manual
variant. The desktop variant uses the system browser
to gather the user credentials. The manual variant
reads the user credentials from STDIN
.
How it works
To authenticate a user with the desktop
variant the KeycloakInstalled
adapter opens a desktop browser window where a user uses the regular Keycloak
login pages to log in when the loginDesktop()
method is called on the KeycloakInstalled
object.
The login page URL is opened with redirect parameter
that points to a local ServerSocket
listening on a free ephemeral port
on localhost
which is started by the adapter.
After a successful login the KeycloakInstalled
receives the authorization code
from the incoming HTTP request and performs the authorization code flow.
Once the code to token exchange is completed the ServerSocket
is shutdown.
If the user already has an active Keycloak session then the login form is not shown but the code to token exchange is continued, which enables a smooth Web based SSO experience. |
The client eventually receives the tokens (access_token, refresh_token, id_token) which can then be used to call backend services.
The KeycloakInstalled
adapter provides support for renewal of stale tokens.
Installing the adapter
<dependency>
<groupId>org.keycloak</groupId>
<artifactId>keycloak-installed-adapter</artifactId>
<version>23.0.2</version>
</dependency>
Client configuration
The application needs to be configured as a public
OpenID Connect client with
Standard Flow Enabled
and http://localhost as an allowed Valid Redirect URI
.
The KeycloakInstalled adapter supports the PKCE [RFC 7636] mechanism to provide additional protection during
code to token exchanges in the OIDC protocol. PKCE can be enabled with the "enable-pkce": true setting
in the adapter configuration. Enabling PKCE is highly recommended, to avoid code injection and code replay attacks.
|
Usage
The KeycloakInstalled
adapter reads its configuration from
META-INF/keycloak.json
on the classpath. Custom configurations
can be supplied with an InputStream
or a KeycloakDeployment
through the KeycloakInstalled
constructor.
In the example below, the client configuration for desktop-app
uses the following keycloak.json
:
{
"realm": "desktop-app-auth",
"auth-server-url": "http://localhost:8081",
"ssl-required": "external",
"resource": "desktop-app",
"public-client": true,
"use-resource-role-mappings": true,
"enable-pkce": true
}
the following sketch demonstrates working with the KeycloakInstalled
adapter:
// reads the configuration from classpath: META-INF/keycloak.json
KeycloakInstalled keycloak = new KeycloakInstalled();
// opens desktop browser
keycloak.loginDesktop();
AccessToken token = keycloak.getToken();
// use token to send backend request
// ensure token is valid for at least 30 seconds
long minValidity = 30L;
String tokenString = keycloak.getTokenString(minValidity, TimeUnit.SECONDS);
// when you want to logout the user.
keycloak.logout();
The KeycloakInstalled class supports customization of the http responses returned by
login / logout requests via the loginResponseWriter and logoutResponseWriter attributes.
|
Example
The following provides an example for the configuration mentioned above.
import java.util.Locale;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;
import org.keycloak.adapters.installed.KeycloakInstalled;
import org.keycloak.representations.AccessToken;
public class DesktopApp {
public static void main(String[] args) throws Exception {
KeycloakInstalled keycloak = new KeycloakInstalled();
keycloak.setLocale(Locale.ENGLISH);
keycloak.loginDesktop();
AccessToken token = keycloak.getToken();
Executors.newSingleThreadExecutor().submit(() -> {
System.out.println("Logged in...");
System.out.println("Token: " + token.getSubject());
System.out.println("Username: " + token.getPreferredUsername());
try {
System.out.println("AccessToken: " + keycloak.getTokenString());
} catch (Exception ex) {
ex.printStackTrace();
}
int timeoutSeconds = 20;
System.out.printf("Logging out in...%d Seconds%n", timeoutSeconds);
try {
TimeUnit.SECONDS.sleep(timeoutSeconds);
} catch (Exception e) {
e.printStackTrace();
}
try {
keycloak.logout();
} catch (Exception e) {
e.printStackTrace();
}
System.out.println("Exiting...");
System.exit(0);
});
}
}
2.3.10. Security Context
The KeycloakSecurityContext
interface is available if you need to access to the tokens directly. This could be useful if you want to retrieve additional
details from the token (such as user profile information) or you want to invoke a RESTful service that is protected by Keycloak.
In servlet environments it is available in secured invocations as an attribute in HttpServletRequest:
httpServletRequest
.getAttribute(KeycloakSecurityContext.class.getName());
Or, it is available in insecured requests in the HttpSession:
httpServletRequest.getSession()
.getAttribute(KeycloakSecurityContext.class.getName());
2.3.11. Error handling
Keycloak has some error handling facilities for servlet based client adapters.
When an error is encountered in authentication, Keycloak will call HttpServletResponse.sendError()
.
You can set up an error-page within your web.xml
file to handle the error however you want.
Keycloak can throw 400, 401, 403, and 500 errors.
<error-page>
<error-code>403</error-code>
<location>/ErrorHandler</location>
</error-page>
Keycloak also sets a HttpServletRequest
attribute that you can retrieve.
The attribute name is org.keycloak.adapters.spi.AuthenticationError
, which should be cast to org.keycloak.adapters.OIDCAuthenticationError
.
For example:
import org.keycloak.adapters.OIDCAuthenticationError;
import org.keycloak.adapters.OIDCAuthenticationError.Reason;
...
OIDCAuthenticationError error = (OIDCAuthenticationError) httpServletRequest
.getAttribute('org.keycloak.adapters.spi.AuthenticationError');
Reason reason = error.getReason();
System.out.println(reason.name());
2.3.12. Logout
You can log out of a web application in multiple ways.
For Jakarta EE servlet containers, you can call HttpServletRequest.logout()
. For other browser applications, you can redirect the browser to
http://auth-server/realms/{realm-name}/protocol/openid-connect/logout
, which logs the user out if that user has an SSO session with his browser. The actual logout is done once
the user confirms the logout. You can optionally include parameters such as id_token_hint
, post_logout_redirect_uri
, client_id
and others as described in the
OpenID Connect RP-Initiated Logout. As a result, that logout does not need to be explicitly confirmed
by the user if you include the id_token_hint
parameter. After logout, the user will be automatically redirected to the specified post_logout_redirect_uri
as long as it is provided.
Note that you need to include either the client_id
or id_token_hint
parameter in case that post_logout_redirect_uri
is included.
If you want to avoid logging out of an external identity provider as part of the logout process, you can supply the parameter initiating_idp
, with the value being
the identity (alias) of the identity provider in question. This parameter is useful when the logout endpoint is invoked as part of single logout initiated by the external identity provider.
The parameter initiating_idp
is the supported parameter of the Keycloak logout endpoint in addition to the parameters described in the RP-Initiated Logout specification.
When using the HttpServletRequest.logout()
option the adapter executes a back-channel POST call against the Keycloak server passing the refresh token.
If the method is executed from an unprotected page (a page that does not check for a valid token) the refresh token can be unavailable and, in that case,
the adapter skips the call. For this reason, using a protected page to execute HttpServletRequest.logout()
is recommended so that current tokens are always
taken into account and an interaction with the Keycloak server is performed if needed.
2.3.13. Parameters forwarding
The Keycloak initial authorization endpoint request has support for various parameters. Most of the parameters are described in OIDC specification. Some parameters are added automatically by the adapter based on the adapter configuration. However, there are also a few parameters that can be added on a per-invocation basis. When you open the secured application URI, the particular parameter will be forwarded to the Keycloak authorization endpoint.
For example, if you request an offline token, then you can open the secured application URI with the scope
parameter like:
http://myappserver/mysecuredapp?scope=offline_access
and the parameter scope=offline_access
will be automatically forwarded to the Keycloak authorization endpoint.
The supported parameters are:
-
scope - Use a space-delimited list of scopes. A space-delimited list typically references Client scopes defined on particular client. Note that the scope
openid
will be always be added to the list of scopes by the adapter. For example, if you enter the scope optionsaddress phone
, then the request to Keycloak will contain the scope parameterscope=openid address phone
. -
prompt - Keycloak supports these settings:
-
login
- SSO will be ignored and the Keycloak login page will always be shown, even if the user is already authenticated -
consent
- Applicable only for the clients withConsent Required
. If it is used, the Consent page will always be displayed, even if the user previously granted consent to this client. -
none
- The login page will never be shown; instead the user will be redirected to the application, with an error if the user is not yet authenticated. This setting allows you to create a filter/interceptor on the application side and show a custom error page to the user. See more details in the specification.
-
-
max_age - Used only if a user is already authenticated. Specifies maximum permitted time for the authentication to persist, measured from when the user authenticated. If user is authenticated longer than
maxAge
, the SSO is ignored and he must re-authenticate. -
login_hint - Used to pre-fill the username/email field on the login form.
-
kc_idp_hint - Used to tell Keycloak to skip showing login page and automatically redirect to specified identity provider instead. More info in the Identity Provider documentation.
Most of the parameters are described in the OIDC specification.
The only exception is parameter kc_idp_hint
, which is specific to Keycloak and contains the name of the identity provider to automatically use.
For more information see the Identity Brokering
section in the Server Administration Guide.
If you open the URL using the attached parameters, the adapter will not redirect you to Keycloak if you are already authenticated
in the application. For example, opening http://myappserver/mysecuredapp?prompt=login will not automatically redirect you to
the Keycloak login page if you are already authenticated to the application mysecuredapp . This behavior may be changed in the future.
|
2.3.14. Client authentication
When a confidential OIDC client needs to send a backchannel request (for example, to exchange code for the token, or to refresh the token) it needs to authenticate against the Keycloak server. By default, there are three ways to authenticate the client: client ID and client secret, client authentication with signed JWT, or client authentication with signed JWT using client secret.
Client ID and Client Secret
This is the traditional method described in the OAuth2 specification. The client has a secret, which needs to be known to both the adapter (application) and the Keycloak server.
You can generate the secret for a particular client in the Keycloak Admin Console, and then paste this secret into the keycloak.json
file on the application side:
"credentials": {
"secret": "19666a4f-32dd-4049-b082-684c74115f28"
}
Client authentication with Signed JWT
This is based on the RFC7523 specification. It works this way:
-
The client must have the private key and certificate. For Keycloak this is available through the traditional
keystore
file, which is either available on the client application’s classpath or somewhere on the file system. -
Once the client application is started, it allows to download its public key in JWKS format using a URL such as http://myhost.com/myapp/k_jwks, assuming that http://myhost.com/myapp is the base URL of your client application. This URL can be used by Keycloak (see below).
-
During authentication, the client generates a JWT token and signs it with its private key and sends it to Keycloak in the particular backchannel request (for example, code-to-token request) in the
client_assertion
parameter. -
Keycloak must have the public key or certificate of the client so that it can verify the signature on JWT. In Keycloak you need to configure client credentials for your client. First you need to choose
Signed JWT
as the method of authenticating your client in the tabCredentials
in the Admin Console. Then you can choose to either in the tabKeys
:-
Configure the JWKS URL where Keycloak can download the client’s public keys. This can be a URL such as http://myhost.com/myapp/k_jwks (see details above). This option is the most flexible, since the client can rotate its keys anytime and Keycloak then always downloads new keys when needed without needing to change the configuration. More accurately, Keycloak downloads new keys when it sees the token signed by an unknown
kid
(Key ID). -
Upload the client’s public key or certificate, either in PEM format, in JWK format, or from the keystore. With this option, the public key is hardcoded and must be changed when the client generates a new key pair. You can even generate your own keystore from the Keycloak Admin Console if you don’t have your own available. For more details on how to set up the Keycloak Admin Console, see the Server Administration Guide.
-
For set up on the adapter side you need to have something like this in your keycloak.json
file:
"credentials": {
"jwt": {
"client-keystore-file": "classpath:keystore-client.jks",
"client-keystore-type": "JKS",
"client-keystore-password": "storepass",
"client-key-password": "keypass",
"client-key-alias": "clientkey",
"token-expiration": 10
}
}
With this configuration, the keystore file keystore-client.jks
must be available on classpath in your WAR. If you do not use the prefix classpath:
you can point to any file on the file system where the client application is running.
For inspiration, you can take a look at the examples distribution into the main demo example into the product-portal
application.
Client authentication with Signed JWT using client secret
This is the same as Client Authentication with Signed JWT except for using the client secret instead of the private key and certificate.
The client has a secret, which needs to be known to both the adapter (application) and the Keycloak server. You need to choose Signed JWT with Client Secret
as the method of authenticating your client in the tab Credentials
in the Admin Console, and then paste this secret into the keycloak.json
file on the application side:
"credentials": {
"secret-jwt": {
"secret": "19666a4f-32dd-4049-b082-684c74115f28",
"algorithm": "HS512"
}
}
The "algorithm" field specifies the algorithm for Signed JWT using Client Secret. It needs to be one of the following values : HS256, HS384, and HS512. For details, please refer to JSON Web Algorithms (JWA).
This "algorithm" field is optional so that HS256 is applied automatically if the "algorithm" field does not exist on the keycloak.json
file.
Add your own client authentication method
You can add your own client authentication method as well. You will need to implement both client-side and server-side providers. For more details see the Authentication SPI
section in Server Developer Guide.
2.3.15. Multi Tenancy
Multi Tenancy, in our context, means 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.
In practice, this means that the application needs to have multiple keycloak.json
adapter configuration files.
You could have multiple instances of your WAR with different adapter configuration files deployed to different context-paths. However, this may be inconvenient and you may also want to select the realm based on something else than context-path.
Keycloak makes it possible to have a custom config resolver so you can choose what adapter config is used for each request.
To achieve this first you need to create an implementation of org.keycloak.adapters.KeycloakConfigResolver
. For example:
package example;
import org.keycloak.adapters.KeycloakConfigResolver;
import org.keycloak.adapters.KeycloakDeployment;
import org.keycloak.adapters.KeycloakDeploymentBuilder;
public class PathBasedKeycloakConfigResolver implements KeycloakConfigResolver {
@Override
public KeycloakDeployment resolve(OIDCHttpFacade.Request request) {
if (path.startsWith("alternative")) {
KeycloakDeployment deployment = cache.get(realm);
if (null == deployment) {
InputStream is = getClass().getResourceAsStream("/tenant1-keycloak.json");
return KeycloakDeploymentBuilder.build(is);
}
} else {
InputStream is = getClass().getResourceAsStream("/default-keycloak.json");
return KeycloakDeploymentBuilder.build(is);
}
}
}
You also need to configure which KeycloakConfigResolver
implementation to use with the keycloak.config.resolver
context-param in your web.xml
:
<web-app>
...
<context-param>
<param-name>keycloak.config.resolver</param-name>
<param-value>example.PathBasedKeycloakConfigResolver</param-value>
</context-param>
</web-app>
2.3.16. Application clustering
This chapter is related to supporting clustered applications deployed to JBoss EAP, WildFly and JBoss AS.
There are a few options available depending on whether your application is:
-
Stateless or stateful
-
Distributable (replicated http session) or non-distributable
-
Relying on sticky sessions provided by load balancer
-
Hosted on same domain as Keycloak
Dealing with clustering is not quite as simple as for a regular application. Mainly due to the fact that both the browser and the server-side application sends requests to Keycloak, so it’s not as simple as enabling sticky sessions on your load balancer.
Stateless token store
By default, the web application secured by Keycloak uses the HTTP session to store security context. This means that you either have to enable sticky sessions or replicate the HTTP session.
As an alternative to storing the security context in the HTTP session the adapter can be configured to store this in a cookie instead. This is useful if you want to make your application stateless or if you don’t want to store the security context in the HTTP session.
To use the cookie store for saving the security context, edit your applications WEB-INF/keycloak.json
and add:
"token-store": "cookie"
The default value for token-store is session , which stores the security context in the HTTP session.
|
One limitation of using the cookie store is that the whole security context is passed in the cookie for every HTTP request. This may impact performance.
Another small limitation is limited support for Single-Sign Out. It works without issues if you init servlet logout (HttpServletRequest.logout) from the application itself as the adapter will delete the KEYCLOAK_ADAPTER_STATE cookie. However, back-channel logout initialized from a different application isn’t propagated by Keycloak to applications using cookie store. Hence it’s recommended to use a short value for the access token timeout (for example 1 minute).
Some load balancers do not allow any configuration of the sticky session cookie name or contents, such as Amazon ALB. For these, it is recommended to set the shouldAttachRoute option to false .
|
Relative URI optimization
In deployment scenarios where Keycloak and the application is hosted on the same domain (through a reverse proxy or load balancer) it can be convenient to use relative URI options in your client configuration.
With relative URIs the URI is resolved as relative to the URL used to access Keycloak.
For example if the URL to your application is https://acme.org/myapp
and the URL to Keycloak is https://acme.org
, then you can use
the redirect-uri /myapp
instead of https://acme.org/myapp
.
Admin URL configuration
Admin URL for a particular client can be configured in the Keycloak Admin Console. It’s used by the Keycloak server to send backend requests to the application for various tasks, like logout users or push revocation policies.
For example the way backchannel logout works is:
-
User sends logout request from one application
-
The application sends logout request to Keycloak
-
The Keycloak server invalidates the user session
-
The Keycloak server then sends a backchannel request to application with an admin url that are associated with the session
-
When an application receives the logout request it invalidates the corresponding HTTP session
If admin URL contains ${application.session.host}
it will be replaced with the URL to the node associated with the HTTP session.
Registration of application nodes
The previous section describes how Keycloak can send logout request to node associated with a specific HTTP session. However, in some cases admin may want to propagate admin tasks to all registered cluster nodes, not just one of them. For example to push a new not before policy to the application or to log out all users from the application.
In this case Keycloak needs to be aware of all application cluster nodes, so it can send the event to all of them. To achieve this, we support auto-discovery mechanism:
-
When a new application node joins the cluster, it sends a registration request to the Keycloak server
-
The request may be re-sent to Keycloak in configured periodic intervals
-
If the Keycloak server doesn’t receive a re-registration request within a specified timeout then it automatically unregisters the specific node
-
The node is also unregistered in Keycloak when it sends an unregistration request, which is usually during node shutdown or application undeployment. This may not work properly for forced shutdown when undeployment listeners are not invoked, which results in the need for automatic unregistration
Sending startup registrations and periodic re-registration is disabled by default as it’s only required for some clustered applications.
To enable the feature edit the WEB-INF/keycloak.json
file for your application and add:
"register-node-at-startup": true,
"register-node-period": 600,
This means the adapter will send the registration request on startup and re-register every 10 minutes.
In the Keycloak Admin Console you can specify the maximum node re-registration timeout (should be larger than register-node-period from the adapter configuration). You can also manually add and remove cluster nodes in through the Admin Console, which is useful if you don’t want to rely on the automatic registration feature or if you want to remove stale application nodes in the event you’re not using the automatic unregistration feature.
Refresh token in each request
By default the application adapter will only refresh the access token when it’s expired. However, you can also configure the adapter to refresh the token on every request. This may have a performance impact as your application will send more requests to the Keycloak server.
To enable the feature edit the WEB-INF/keycloak.json
file for your application and add:
"always-refresh-token": true
This may have a significant impact on performance. Only enable this feature if you can’t rely on backchannel messages to propagate logout and not before policies. Another thing to consider is that by default access tokens has a short expiration so even if logout is not propagated the token will expire within minutes of the logout. |
2.4. Keycloak JavaScript adapter
Keycloak comes with a client-side JavaScript library called keycloak-js
that can be used to secure web applications. The adapter also comes with built-in support for Cordova applications.
2.4.1. Installation
The adapter is distributed in several ways, but we recommend that you install the keycloak-js
package from NPM:
npm install keycloak-js
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.
2.4.2. Keycloak server configuration
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.
2.4.3. Using the adapter
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.
import Keycloak from 'keycloak-js';
const keycloak = new Keycloak({
url: 'http://keycloak-server${kc_base_path}',
realm: 'myrealm',
clientId: 'myapp'
});
try {
const authenticated = await keycloak.init();
console.log(`User is ${authenticated ? 'authenticated' : 'not authenticated'}`);
} catch (error) {
console.error('Failed to initialize adapter:', error);
}
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.
-
login-required
authenticates the client if the user is logged in to Keycloak or displays the login page if the user is not logged in. -
check-sso
only authenticates the client if the user is already logged in. If the user is not logged in, the browser is redirected back to the application and remains unauthenticated.
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:
keycloak.init({
onLoad: 'check-sso',
silentCheckSsoRedirectUri: `${location.origin}/silent-check-sso.html`
});
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:
<!doctype html>
<html>
<body>
<script>
parent.postMessage(location.href, location.origin);
</script>
</body>
</html>
Remember that this page must be served by your application at the specified location in silentCheckSsoRedirectUri
and is not part of the adapter.
Silent check-sso functionality is limited in some modern browsers. Please see the Modern Browsers with Tracking Protection Section.
|
To enable login-required
set onLoad
to login-required
and pass to the init method:
keycloak.init({
onLoad: 'login-required'
});
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:
async function fetchUsers() {
const response = await fetch('/api/users', {
headers: {
accept: 'application/json',
authorization: `Bearer ${keycloak.token}`
}
});
return response.json();
}
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:
try {
await keycloak.updateToken(30);
} catch (error) {
console.error('Failed to refresh token:', error);
}
const users = await fetchUsers();
2.4.4. Session Status iframe
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.
Session Status iframe functionality is limited in some modern browsers. Please see Modern Browsers with Tracking Protection Section. |
2.4.5. Implicit and hybrid flow
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:
keycloak.init({
flow: 'implicit'
})
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.init({
flow: 'hybrid'
});
2.4.6. Hybrid Apps with Cordova
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 InApp-Browser is a browser embedded in the app and is not the phone’s default browser. Therefore it will have different settings and stored credentials will not be available.
-
The InApp-Browser might also be slower, especially when rendering more complex themes.
-
There are security concerns to consider, before using this mode, such as that it is possible for the app to gain access to the credentials of the user, as it has full control of the browser rendering the login page, so do not allow its use in apps you do not trust.
Use this example app to help you get started: https://github.com/keycloak/keycloak/tree/master/examples/cordova
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:
keycloak.init({
adapter: 'cordova-native'
});
This adapter requires two additional plugins:
-
cordova-plugin-browsertab: allows the app to open webpages in the system’s browser
-
cordova-plugin-deeplinks: allow the browser to redirect back to your app by special URLs
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:
-
Universal Links on iOS seem to work more reliably with
response-mode
set toquery
-
To prevent Android from opening a new instance of your app on redirect add the following snippet to
config.xml
:
<preference name="AndroidLaunchMode" value="singleTask" />
There is an example app that shows how to use the native-mode: https://github.com/keycloak/keycloak/tree/master/examples/cordova-native
2.4.7. Custom Adapters
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:
import Keycloak from 'keycloak-js';
import KeycloakCapacitorAdapter from 'keycloak-capacitor-adapter';
const keycloak = new Keycloak();
keycloak.init({
adapter: KeycloakCapacitorAdapter,
});
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:
import Keycloak, { KeycloakAdapter } from 'keycloak-js';
// Implement the 'KeycloakAdapter' interface so that all required methods are guaranteed to be present.
const MyCustomAdapter: KeycloakAdapter = {
login(options) {
// Write your own implementation here.
}
// The other methods go here...
};
const keycloak = new Keycloak();
keycloak.init({
adapter: MyCustomAdapter,
});
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.
2.4.8. Modern Browsers with Tracking Protection
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.
Browsers with "SameSite=Lax by Default" Policy
All features are supported if SSL / TLS connection is configured on the Keycloak side as well as on the application side. For example, Chrome is affected starting with version 84.
Browsers with Blocked Third-Party Cookies
Session Status iframe is not supported and is automatically disabled if such browser behavior is detected by the adapter. This means the adapter cannot use a session cookie for Single Sign-Out detection and must rely purely on tokens. As a result, when a user logs out in another window, the application using the adapter will not be logged out until the application tries to refresh the Access Token. Therefore, consider setting the Access Token Lifespan to a relatively short time, so that the logout is detected as soon as possible. For more details, see Session and Token Timeouts.
Silent check-sso
is not supported and falls back to regular (non-silent) check-sso
by default. This behavior can be changed by setting silentCheckSsoFallback: false
in the options passed to the init
method. In this case, check-sso
will be completely disabled if restrictive browser behavior is detected.
Regular check-sso
is affected as well. Since Session Status iframe is unsupported, an additional redirect to Keycloak has to be made when the adapter is initialized to check the user’s login status. This check is different from the standard behavior when the iframe is used to tell whether the user is logged in, and the redirect is performed only when the user is logged out.
An affected browser is for example Safari starting with version 13.1.
2.4.9. API Reference
Constructor
new Keycloak();
new Keycloak('http://localhost/keycloak.json');
new Keycloak({ url: 'http://localhost', realm: 'myrealm', clientId: 'myApp' });
Properties
- authenticated
-
Is
true
if the user is authenticated,false
otherwise. - token
-
The base64 encoded token that can be sent in the
Authorization
header in requests to services. - tokenParsed
-
The parsed token as a JavaScript object.
- subject
-
The user id.
- idToken
-
The base64 encoded ID token.
- idTokenParsed
-
The parsed id token as a JavaScript object.
- realmAccess
-
The realm roles associated with the token.
- resourceAccess
-
The resource roles associated with the token.
- refreshToken
-
The base64 encoded refresh token that can be used to retrieve a new token.
- refreshTokenParsed
-
The parsed refresh token as a JavaScript object.
- timeSkew
-
The estimated time difference between the browser time and the Keycloak server in seconds. This value is just an estimation, but is accurate enough when determining if a token is expired or not.
- responseMode
-
Response mode passed in init (default value is fragment).
- flow
-
Flow passed in init.
- adapter
-
Allows you to override the way that redirects and other browser-related functions will be handled by the library. Available options:
-
"default" - the library uses the browser api for redirects (this is the default)
-
"cordova" - the library will try to use the InAppBrowser cordova plugin to load keycloak login/registration pages (this is used automatically when the library is working in a cordova ecosystem)
-
"cordova-native" - the library tries to open the login and registration page using the phone’s system browser using the BrowserTabs cordova plugin. This requires extra setup for redirecting back to the app (see Hybrid Apps with Cordova).
-
"custom" - allows you to implement a custom adapter (only for advanced use cases)
-
- responseType
-
Response type sent to Keycloak with login requests. This is determined based on the flow value used during initialization, but can be overridden by setting this value.
Methods
init(options)
Called to initialize the adapter.
Options is an Object, where:
-
useNonce - Adds a cryptographic nonce to verify that the authentication response matches the request (default is
true
). -
onLoad - Specifies an action to do on load. Supported values are
login-required
orcheck-sso
. -
silentCheckSsoRedirectUri - Set the redirect uri for silent authentication check if onLoad is set to 'check-sso'.
-
silentCheckSsoFallback - Enables fall back to regular
check-sso
when silentcheck-sso
is not supported by the browser (default istrue
). -
token - Set an initial value for the token.
-
refreshToken - Set an initial value for the refresh token.
-
idToken - Set an initial value for the id token (only together with token or refreshToken).
-
scope - Set the default scope parameter to the Keycloak login endpoint. Use a space-delimited list of scopes. Those typically reference Client scopes defined on a particular client. Note that the scope
openid
will always be added to the list of scopes by the adapter. For example, if you enter the scope optionsaddress phone
, then the request to Keycloak will contain the scope parameterscope=openid address phone
. Note that the default scope specified here is overwritten if thelogin()
options specify scope explicitly. -
timeSkew - Set an initial value for skew between local time and Keycloak server in seconds (only together with token or refreshToken).
-
checkLoginIframe - Set to enable/disable monitoring login state (default is
true
). -
checkLoginIframeInterval - Set the interval to check login state (default is 5 seconds).
-
responseMode - Set the OpenID Connect response mode send to Keycloak server at login request. Valid values are
query
orfragment
. Default value isfragment
, which means that after successful authentication will Keycloak redirect to JavaScript application with OpenID Connect parameters added in URL fragment. This is generally safer and recommended overquery
. -
flow - Set the OpenID Connect flow. Valid values are
standard
,implicit
orhybrid
. -
enableLogging - Enables logging messages from Keycloak to the console (default is
false
). -
pkceMethod - The method for Proof Key Code Exchange (PKCE) to use. Configuring this value enables the PKCE mechanism. Available options:
-
"S256" - The SHA256 based PKCE method
-
-
acrValues - Generates the
acr_values
parameter which refers to authentication context class reference and allows clients to declare the required assurance level requirements, e.g. authentication mechanisms. See Section 4. acr_values request values and level of assurance in OpenID Connect MODRNA Authentication Profile 1.0. -
messageReceiveTimeout - Set a timeout in milliseconds for waiting for message responses from the Keycloak server. This is used, for example, when waiting for a message during 3rd party cookies check. The default value is 10000.
-
locale - When onLoad is 'login-required', sets the 'ui_locales' query param in compliance with section 3.1.2.1 of the OIDC 1.0 specification.
Returns a promise that resolves when initialization completes.
login(options)
Redirects to login form.
Options is an optional Object, where:
-
redirectUri - Specifies the uri to redirect to after login.
-
prompt - This parameter allows to slightly customize the login flow on the Keycloak server side. For example enforce displaying the login screen in case of value
login
. See Parameters Forwarding Section for the details and all the possible values of theprompt
parameter. -
maxAge - Used just if user is already authenticated. Specifies maximum time since the authentication of user happened. If user is already authenticated for longer time than
maxAge
, the SSO is ignored and he will need to re-authenticate again. -
loginHint - Used to pre-fill the username/email field on the login form.
-
scope - Override the scope configured in
init
with a different value for this specific login. -
idpHint - Used to tell Keycloak to skip showing the login page and automatically redirect to the specified identity provider instead. More info in the Identity Provider documentation.
-
acr - Contains the information about
acr
claim, which will be sent insideclaims
parameter to the Keycloak server. Typical usage is for step-up authentication. Example of use{ values: ["silver", "gold"], essential: true }
. See OpenID Connect specification and Step-up authentication documentation for more details. -
acrValues - Generates the
acr_values
parameter which refers to authentication context class reference and allows clients to declare the required assurance level requirements, e.g. authentication mechanisms. See Section 4. acr_values request values and level of assurance in OpenID Connect MODRNA Authentication Profile 1.0. -
action - If value is
register
then user is redirected to registration page, if the value isUPDATE_PASSWORD
then the user will be redirected to the reset password page (if not authenticated will send user to login page first and redirect after authenticated), otherwise to login page. -
locale - Sets the 'ui_locales' query param in compliance with section 3.1.2.1 of the OIDC 1.0 specification.
-
cordovaOptions - Specifies the arguments that are passed to the Cordova in-app-browser (if applicable). Options
hidden
andlocation
are not affected by these arguments. All available options are defined at https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-inappbrowser/. Example of use:{ zoom: "no", hardwareback: "yes" }
;
createLoginUrl(options)
Returns the URL to login form.
Options is an optional Object, which supports same options as the function login
.
logout(options)
Redirects to logout.
Options is an Object, where:
-
redirectUri - Specifies the uri to redirect to after logout.
createLogoutUrl(options)
Returns the URL to log out the user.
Options is an Object, where:
-
redirectUri - Specifies the uri to redirect to after logout.
register(options)
Redirects to registration form. Shortcut for login with option action = 'register'
Options are same as for the login method but 'action' is set to 'register'
createRegisterUrl(options)
Returns the url to registration page. Shortcut for createLoginUrl with option action = 'register'
Options are same as for the createLoginUrl method but 'action' is set to 'register'
accountManagement()
Redirects to the Account Management Console.
createAccountUrl(options)
Returns the URL to the Account Management Console.
Options is an Object, where:
-
redirectUri - Specifies the uri to redirect to when redirecting back to the application.
hasRealmRole(role)
Returns true if the token has the given realm role.
hasResourceRole(role, resource)
Returns true if the token has the given role for the resource (resource is optional, if not specified clientId is used).
loadUserProfile()
Loads the users profile.
Returns a promise that resolves with the profile.
For example:
try {
const profile = await keycloak.loadUserProfile();
console.log('Retrieved user profile:', profile);
} catch (error) {
console.error('Failed to load user profile:', error);
}
isTokenExpired(minValidity)
Returns true if the token has less than minValidity seconds left before it expires (minValidity is optional, if not specified 0 is used).
updateToken(minValidity)
If the token expires within minValidity seconds (minValidity is optional, if not specified 5 is used) the token is refreshed. If -1 is passed as the minValidity, the token will be forcibly refreshed. If the session status iframe is enabled, the session status is also checked.
Returns a promise that resolves with a boolean indicating whether or not the token has been refreshed.
For example:
try {
const refreshed = await keycloak.updateToken(5);
console.log(refreshed ? 'Token was refreshed' : 'Token is still valid');
} catch (error) {
console.error('Failed to refresh the token:', error);
}
clearToken()
Clear authentication state, including tokens. This can be useful if application has detected the session was expired, for example if updating token fails.
Invoking this results in onAuthLogout callback listener being invoked.
Callback Events
The adapter supports setting callback listeners for certain events. Keep in mind that these have to be set before the call to the init()
method.
For example:
keycloak.onAuthSuccess = () => console.log('Authenticated!');
The available events are:
-
onReady(authenticated) - Called when the adapter is initialized.
-
onAuthSuccess - Called when a user is successfully authenticated.
-
onAuthError - Called if there was an error during authentication.
-
onAuthRefreshSuccess - Called when the token is refreshed.
-
onAuthRefreshError - Called if there was an error while trying to refresh the token.
-
onAuthLogout - Called if the user is logged out (will only be called if the session status iframe is enabled, or in Cordova mode).
-
onTokenExpired - Called when the access token is expired. If a refresh token is available the token can be refreshed with updateToken, or in cases where it is not (that is, with implicit flow) you can redirect to the login screen to obtain a new access token.
2.5. Keycloak Node.js adapter
Keycloak provides a Node.js adapter built on top of Connect to protect server-side JavaScript apps - the goal was to be flexible enough to integrate with frameworks like Express.js.
The library can be downloaded directly from Keycloak organization and the source is available at GitHub.
To use the Node.js adapter, first you must create a client for your application in the Keycloak Admin Console. The adapter supports public, confidential, and bearer-only access type. Which one to choose depends on the use-case scenario.
Once the client is created click the Installation
tab, select Keycloak OIDC JSON
for Format Option
, and then click Download
. The downloaded keycloak.json
file should be at the root folder of your project.
2.5.1. Installation
Assuming you’ve already installed Node.js, create a folder for your application:
mkdir myapp && cd myapp
Use npm init
command to create a package.json
for your application. Now add the Keycloak connect adapter in the dependencies list:
"dependencies": {
"keycloak-connect": "23.0.2"
}
2.5.2. Usage
- Instantiate a Keycloak class
-
The
Keycloak
class provides a central point for configuration and integration with your application. The simplest creation involves no arguments.
In the root directory of your project create a file called server.js
and add the following code:
const session = require('express-session');
const Keycloak = require('keycloak-connect');
const memoryStore = new session.MemoryStore();
const keycloak = new Keycloak({ store: memoryStore });
Install the express-session
dependency:
npm install express-session
To start the server.js
script, add the following command in the 'scripts' section of the package.json
:
"scripts": { "test": "echo \"Error: no test specified\" && exit 1", "start": "node server.js" },
Now we have the ability to run our server with following command:
npm run start
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.
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:
const kcConfig = {
clientId: 'myclient',
bearerOnly: true,
serverUrl: 'http://localhost:8080',
realm: 'myrealm',
realmPublicKey: 'MIIBIjANB...'
};
const keycloak = new Keycloak({ store: memoryStore }, kcConfig);
Applications can also redirect users to their preferred identity provider by using:
const keycloak = new Keycloak({ store: memoryStore, idpHint: myIdP }, kcConfig);
- Configuring a web session store
-
If you want to use web sessions to manage server-side state for authentication, you need to initialize the
Keycloak(…)
with at least astore
parameter, passing in the actual session store thatexpress-session
is using.
const session = require('express-session');
const memoryStore = new session.MemoryStore();
// Configure session
app.use(
session({
secret: 'mySecret',
resave: false,
saveUninitialized: true,
store: memoryStore,
})
);
const keycloak = new Keycloak({ store: memoryStore });
- Passing a custom scope value
-
By default, the scope value
openid
is passed as a query parameter to Keycloak’s login URL, but you can add an additional custom value:
const keycloak = new Keycloak({ scope: 'offline_access' });
2.5.3. Installing middleware
Once instantiated, install the middleware into your connect-capable app:
In order to do so, first we have to install Express:
npm install express
then require Express in our project as outlined below:
const express = require('express');
const app = express();
and configure Keycloak middleware in Express, by adding at the code below:
app.use( keycloak.middleware() );
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
:
app.listen(3000, function () {
console.log('App listening on port 3000');
});
2.5.4. Configuration for proxies
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:
const app = express();
app.set( 'trust proxy', true );
app.use( keycloak.middleware() );
2.5.5. Protecting resources
- Simple authentication
-
To enforce that a user must be authenticated before accessing a resource, simply use a no-argument version of
keycloak.protect()
:
app.get( '/complain', keycloak.protect(), complaintHandler );
- Role-based authorization
-
To secure a resource with an application role for the current app:
app.get( '/special', keycloak.protect('special'), specialHandler );
To secure a resource with an application role for a different app:
app.get( '/extra-special', keycloak.protect('other-app:special'), extraSpecialHandler );
To secure a resource with a realm role:
app.get( '/admin', keycloak.protect( 'realm:admin' ), adminHandler );
- Resource-Based Authorization
-
Resource-Based Authorization allows you to protect resources, and their specific methods/actions,** based on a set of policies defined in Keycloak, thus externalizing authorization from your application. This is achieved by exposing a
keycloak.enforcer
method which you can use to protect resources.*
app.get('/apis/me', keycloak.enforcer('user:profile'), userProfileHandler);
The keycloak-enforcer
method operates in two modes, depending on the value of the response_mode
configuration option.
app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'token'}), userProfileHandler);
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:
app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'token'}), function (req, res) {
const token = req.kauth.grant.access_token.content;
const permissions = token.authorization ? token.authorization.permissions : undefined;
// show user profile
});
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:
app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'permissions'}), function (req, res) {
const permissions = req.permissions;
// show user profile
});
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:
keycloak.enforcer('user:profile', {resource_server_id: 'my-apiserver'})
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:
app.get('/protected/resource', keycloak.enforcer(['resource:view', 'resource:write'], {
claims: function(request) {
return {
"http.uri": ["/protected/resource"],
"user.agent": // get user agent from request
}
}
}), function (req, res) {
// access granted
For more details about how to configure Keycloak to protected your application resources, please take a look at the Authorization Services Guide.
- Advanced authorization
-
To secure resources based on parts of the URL itself, assuming a role exists for each section:
function protectBySection(token, request) {
return token.hasRole( request.params.section );
}
app.get( '/:section/:page', keycloak.protect( protectBySection ), sectionHandler );
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:
Keycloak.prototype.redirectToLogin = function(req) {
const apiReqMatcher = /\/api\//i;
return !apiReqMatcher.test(req.originalUrl || req.url);
};
2.5.6. Additional URLs
- Explicit user-triggered logout
-
By default, the middleware catches calls to
/logout
to send the user through a Keycloak-centric logout workflow. This can be changed by specifying alogout
configuration parameter to themiddleware()
call:
app.use( keycloak.middleware( { logout: '/logoff' } ));
When the user-triggered logout is invoked a query parameter redirect_url
can be passed:
https://example.com/logoff?redirect_url=https%3A%2F%2Fexample.com%3A3000%2Flogged%2Fout
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
.
- Keycloak Admin Callbacks
-
Also, the middleware supports callbacks from the Keycloak console to log out a single session or all sessions. By default, these type of admin callbacks occur relative to the root URL of
/
but can be changed by providing anadmin
parameter to themiddleware()
call:
app.use( keycloak.middleware( { admin: '/callbacks' } );
2.5.7. Complete example
A complete example using the Node.js adapter usage can be found in Keycloak quickstarts for Node.js
2.6. mod_auth_openidc Apache HTTPD Module
The mod_auth_openidc is an Apache HTTP plugin for OpenID Connect. If your language/environment supports using Apache HTTPD as a proxy, then you can use mod_auth_openidc to secure your web application with OpenID Connect. Configuration of this module is beyond the scope of this document. Please see the mod_auth_openidc GitHub repo for more details on configuration.
To configure mod_auth_openidc you’ll need
-
The client_id.
-
The client_secret.
-
The redirect_uri to your application.
-
The Keycloak openid-configuration url
-
mod_auth_openidc specific Apache HTTPD module config.
An example configuration would look like the following.
LoadModule auth_openidc_module modules/mod_auth_openidc.so
ServerName ${HOSTIP}
<VirtualHost *:80>
ServerAdmin webmaster@localhost
DocumentRoot /var/www/html
#this is required by mod_auth_openidc
OIDCCryptoPassphrase a-random-secret-used-by-apache-oidc-and-balancer
OIDCProviderMetadataURL ${KC_ADDR}/realms/${KC_REALM}/.well-known/openid-configuration
OIDCClientID ${CLIENT_ID}
OIDCClientSecret ${CLIENT_SECRET}
OIDCRedirectURI http://${HOSTIP}/${CLIENT_APP_NAME}/redirect_uri
# maps the preferred_username claim to the REMOTE_USER environment variable
OIDCRemoteUserClaim preferred_username
<Location /${CLIENT_APP_NAME}/>
AuthType openid-connect
Require valid-user
</Location>
</VirtualHost>
Further information on how to configure mod_auth_openidc can be found on the mod_auth_openidc project page.
2.7. Financial-grade API (FAPI) Support
Keycloak makes it easier for administrators to make sure that their clients are compliant with these specifications:
This compliance means that the Keycloak server will verify the requirements for the authorization server, which are mentioned in the specifications. Keycloak adapters do not have any specific support for the FAPI, hence the required validations on the client (application) side may need to be still done manually or through some other third-party solutions.
2.7.1. FAPI client profiles
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.
2.7.2. Open Finance Brasil Financial-grade API Security Profile
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:
-
If your client does not use PAR, make sure that it uses encrypted OIDC request objects. This can be achieved by using a client profile with the
secure-request-object
executor configured withEncryption Required
enabled. -
Make sure that for JWS, the client uses the
PS256
algorithm. For JWE, the client should use theRSA-OAEP
withA256GCM
. This may need to be set in all the Client Settings where these algorithms are applicable.
2.7.3. TLS considerations
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.
2.8. Recommendations
This section describes some recommendations when securing your applications with Keycloak.
2.8.1. Validating access tokens
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.
2.8.2. Redirect URIs
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:
-
Open redirects - this can allow attackers to create spoof links that looks like they are coming from your domain
-
Unauthorized entry - when users are already authenticated with Keycloak, an attacker can use a public client where redirect uris have not be configured correctly to gain access by redirecting the user without the users knowledge
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:
http://127.0.0.1
-
This redirect URI is useful for native applications and allows the native application to create a web server on a random port that can be used to obtain the authorization code. This redirect uri allows any port. Note that per OAuth 2.0 for Native Apps, the use of
localhost
is not recommended and the IP literal127.0.0.1
should be used instead.
urn:ietf:wg:oauth:2.0:oob
-
If you cannot start a web server in the client (or a browser is not available), you can use the special
urn:ietf:wg:oauth:2.0:oob
redirect uri. When this redirect uri is used, Keycloak displays a page with the code in the title and in a box on the page. The application can either detect that the browser title has changed, or the user can copy and paste the code manually to the application. With this redirect uri, a user can use a different device to obtain a code to paste back to the application.
3. Using SAML to secure applications and services
This section describes how you can secure applications and services with SAML using either Keycloak client adapters or generic SAML provider libraries.
3.1. Keycloak Java adapters
Keycloak comes with a range of different adapters for Java application. Selecting the correct adapter depends on the target platform.
3.1.1. General Adapter Config
Each SAML client adapter supported by Keycloak can be configured by a simple XML text file. This is what one might look like:
<keycloak-saml-adapter xmlns="urn:keycloak:saml:adapter"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:keycloak:saml:adapter https://www.keycloak.org/schema/keycloak_saml_adapter_1_10.xsd">
<SP entityID="http://localhost:8081/sales-post-sig/"
sslPolicy="EXTERNAL"
nameIDPolicyFormat="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
logoutPage="/logout.jsp"
forceAuthentication="false"
isPassive="false"
turnOffChangeSessionIdOnLogin="false"
autodetectBearerOnly="false">
<Keys>
<Key signing="true" >
<KeyStore resource="/WEB-INF/keystore.jks" password="store123">
<PrivateKey alias="http://localhost:8080/sales-post-sig/" password="test123"/>
<Certificate alias="http://localhost:8080/sales-post-sig/"/>
</KeyStore>
</Key>
</Keys>
<PrincipalNameMapping policy="FROM_NAME_ID"/>
<RoleIdentifiers>
<Attribute name="Role"/>
</RoleIdentifiers>
<RoleMappingsProvider id="properties-based-role-mapper">
<Property name="properties.resource.location" value="/WEB-INF/role-mappings.properties"/>
</RoleMappingsProvider>
<IDP entityID="idp"
signaturesRequired="true">
<SingleSignOnService requestBinding="POST"
bindingUrl="http://localhost:8081/realms/demo/protocol/saml"
/>
<SingleLogoutService
requestBinding="POST"
responseBinding="POST"
postBindingUrl="http://localhost:8081/realms/demo/protocol/saml"
redirectBindingUrl="http://localhost:8081/realms/demo/protocol/saml"
/>
<Keys>
<Key signing="true">
<KeyStore resource="/WEB-INF/keystore.jks" password="store123">
<Certificate alias="demo"/>
</KeyStore>
</Key>
</Keys>
</IDP>
</SP>
</keycloak-saml-adapter>
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}
.
SP element
Here is the explanation of the SP element attributes:
<SP entityID="sp"
sslPolicy="ssl"
nameIDPolicyFormat="format"
forceAuthentication="true"
isPassive="false"
keepDOMAssertion="true"
autodetectBearerOnly="false">
...
</SP>
- entityID
-
This is the identifier for this client. The IdP needs this value to determine who the client is that is communicating with it. This setting is REQUIRED.
- sslPolicy
-
This is the SSL policy the adapter will enforce. Valid values are:
ALL
,EXTERNAL
, andNONE
. ForALL
, all requests must come in via HTTPS. ForEXTERNAL
, only non-private IP addresses must come over the wire via HTTPS. ForNONE
, no requests are required to come over via HTTPS. This setting is OPTIONAL. Default value isEXTERNAL
. - nameIDPolicyFormat
-
SAML clients can request a specific NameID Subject format. Fill in this value if you want a specific format. It must be a standard SAML format identifier:
urn:oasis:names:tc:SAML:2.0:nameid-format:transient
. This setting is OPTIONAL. By default, no special format is requested. - forceAuthentication
-
SAML clients can request that a user is re-authenticated even if they are already logged in at the IdP. Set this to
true
to enable. This setting is OPTIONAL. Default value isfalse
. - isPassive
-
SAML clients can request that a user is never asked to authenticate even if they are not logged in at the IdP. Set this to
true
if you want this. Do not use together withforceAuthentication
as they are opposite. This setting is OPTIONAL. Default value isfalse
. - turnOffChangeSessionIdOnLogin
-
The session ID is changed by default on a successful login on some platforms to plug a security attack vector. Change this to
true
to disable this. It is recommended you do not turn it off. Default value isfalse
. - autodetectBearerOnly
-
This should be set to true if your application serves both a web application and web services (for example SOAP or REST). It allows you to redirect unauthenticated users of the web application to the Keycloak login page, but send an HTTP
401
status code to unauthenticated SOAP or REST clients instead as they would not understand a redirect to the login page. Keycloak auto-detects SOAP or REST clients based on typical headers likeX-Requested-With
,SOAPAction
orAccept
. The default value is false. - logoutPage
-
This sets the page to display after logout. If the page is a full URL, such as
http://web.example.com/logout.html
, the user is redirected after logout to that page using the HTTP302
status code. If a link without scheme part is specified, such as/logout.jsp
, the page is displayed after logout, regardless of whether it lies in a protected area according tosecurity-constraint
declarations in web.xml, and the page is resolved relative to the deployment context root. - keepDOMAssertion
-
This attribute should be set to true to make the adapter store the DOM representation of the assertion in its original form inside the
SamlPrincipal
associated to the request. The assertion document can be retrieved using the methodgetAssertionDocument
inside the principal. This is specially useful when re-playing a signed assertion. The returned document is the one that was generated parsing the SAML response received by the Keycloak server. This setting is OPTIONAL and its default value is false (the document is not saved inside the principal).
Service Provider keys and key elements
If the IdP requires that the client application (or SP) sign all of its requests and/or if the IdP will encrypt assertions, you must define the keys used to do this. For client-signed documents you must define both the private and public key or certificate that is used to sign documents. For encryption, you only have to define the private key that is used to decrypt it.
There are two ways to describe your keys.
They can be stored within a Java KeyStore or you can copy/paste the keys directly within keycloak-saml.xml
in the PEM format.
<Keys>
<Key signing="true" >
...
</Key>
</Keys>
The Key
element has two optional attributes signing
and encryption
.
When set to true these tell the adapter what the key will be used for.
If both attributes are set to true, then the key will be used for both signing documents and decrypting encrypted assertions.
You must set at least one of these attributes to true.
KeyStore element
Within the Key
element you can load your keys and certificates from a Java Keystore. This is declared within
a KeyStore
element.
<Keys>
<Key signing="true" >
<KeyStore resource="/WEB-INF/keystore.jks" password="store123">
<PrivateKey alias="myPrivate" password="test123"/>
<Certificate alias="myCertAlias"/>
</KeyStore>
</Key>
</Keys>
Here are the XML config attributes that are defined with the KeyStore
element.
- file
-
File path to the key store. This option is OPTIONAL. The file or resource attribute must be set.
- resource
-
WAR resource path to the KeyStore. This is a path used in method call to ServletContext.getResourceAsStream(). This option is OPTIONAL. The file or resource attribute must be set.
- password
-
The password of the KeyStore. This option is REQUIRED.
If you are defining keys that the SP will use to sign document, you must also specify references to your private keys
and certificates within the Java KeyStore.
The PrivateKey
and Certificate
elements in the above example define an alias
that points to the key or cert
within the keystore. Keystores require an additional password to access private keys.
In the PrivateKey
element you must define this password within a password
attribute.
Key PEMS
Within the Key
element you declare your keys and certificates directly using the sub elements
PrivateKeyPem
, PublicKeyPem
, and CertificatePem
.
The values contained in these elements must conform to the PEM key format.
You usually use this option if you are generating keys using openssl
or similar command line tool.
<Keys>
<Key signing="true">
<PrivateKeyPem>
2341251234AB31234==231BB998311222423522334
</PrivateKeyPem>
<CertificatePem>
211111341251234AB31234==231BB998311222423522334
</CertificatePem>
</Key>
</Keys>
SP PrincipalNameMapping element
This element is optional.
When creating a Java Principal object that you obtain from methods such as HttpServletRequest.getUserPrincipal()
, you can define what name is returned by the Principal.getName()
method.
<SP ...>
<PrincipalNameMapping policy="FROM_NAME_ID"/>
</SP>
<SP ...>
<PrincipalNameMapping policy="FROM_ATTRIBUTE" attribute="email" />
</SP>
The policy
attribute defines the policy used to populate this value.
The possible values for this attribute are:
- FROM_NAME_ID
-
This policy just uses whatever the SAML subject value is. This is the default setting
- FROM_ATTRIBUTE
-
This will pull the value from one of the attributes declared in the SAML assertion received from the server. You’ll need to specify the name of the SAML assertion attribute to use within the
attribute
XML attribute.
RoleIdentifiers element
The RoleIdentifiers
element defines what SAML attributes within the assertion received from the user should be used
as role identifiers within the Jakarta EE Security Context for the user.
<RoleIdentifiers>
<Attribute name="Role"/>
<Attribute name="member"/>
<Attribute name="memberOf"/>
</RoleIdentifiers>
By default Role
attribute values are converted to Jakarta EE roles.
Some IdPs send roles using a member
or memberOf
attribute assertion.
You can define one or more Attribute
elements to specify which SAML attributes must be converted into roles.
RoleMappingsProvider element
The RoleMappingsProvider
is an optional element that allows for the specification of the id and configuration of the
org.keycloak.adapters.saml.RoleMappingsProvider
SPI implementation that is to be used by the SAML adapter.
When Keycloak is used as the IDP, it is possible to use the built-in role mappers to map any roles before adding them to the
SAML assertion. However, the SAML adapters can be used to send SAML requests to third party IDPs and in this case it might be
necessary to map the roles extracted from the assertion into a different set of roles as required by the SP. The
RoleMappingsProvider
SPI allows for the configuration of pluggable role mappers that can be used to perform the necessary
mappings.
The configuration of the provider looks as follows:
...
<RoleIdentifiers>
...
</RoleIdentifiers>
<RoleMappingsProvider id="properties-based-role-mapper">
<Property name="properties.resource.location" value="/WEB-INF/role-mappings.properties"/>
</RoleMappingsProvider>
<IDP>
...
</IDP>
The id
attribute identifies which of the installed providers is to be used. The Property
sub-element can be used multiple times
to specify configuration properties for the provider.
Properties Based role mappings provider
Keycloak includes a RoleMappingsProvider
implementation that performs the role mappings using a properties
file. This
provider is identified by the id properties-based-role-mapper
and is implemented by the org.keycloak.adapters.saml.PropertiesBasedRoleMapper
class.
This provider relies on two configuration properties that can be used to specify the location of the properties
file
that will be used. First, it checks if the properties.file.location
property has been specified, using the configured
value to locate the properties
file in the filesystem. If the configured file is not located, the provider throws a
RuntimeException
. The following snippet shows an example of provider using the properties.file.configuration
option to load the roles.properties
file from the /opt/mappers/
directory in the filesystem:
<RoleMappingsProvider id="properties-based-role-mapper">
<Property name="properties.file.location" value="/opt/mappers/roles.properties"/>
</RoleMappingsProvider>
If the properties.file.location
configuration has not been set, the provider checks the properties.resource.location
property, using the configured value to load the properties
file from the WAR
resource. If this configuration property is
also not present, the provider attempts to load the file from /WEB-INF/role-mappings.properties
by default. Failure to load the file
from the resource will result in the provider throwing a RuntimeException
. The following snippet shows an example of provider
using the properties.resource.location
to load the roles.properties
file from the application’s /WEB-INF/conf/
directory:
<RoleMappingsProvider id="properties-based-role-mapper">
<Property name="properties.resource.location" value="/WEB-INF/conf/roles.properties"/>
</RoleMappingsProvider>
The properties
file can contain both roles and principals as keys, and a list of zero or more roles separated by comma
as values. When invoked, the implementation iterates through the set of roles that were extracted from the assertion and checks,
for each role, if a mapping exists. If the role maps to an empty role, it is discarded. If it maps to a set of one or more
different roles, then these roles are set in the result set. If no mapping is found for the role then it is included as is
in the result set.
Once the roles have been processed, the implementation checks if the principal extracted from the assertion contains an entry
properties
file. If a mapping for the principal exists, any roles listed as value are added to the result set. This
allows the assignment of extra roles to a principal.
As an example, let’s assume the provider has been configured with the following properties file:
roleA=roleX,roleY
roleB=
kc_user=roleZ
If the principal kc_user
is extracted from the assertion with roles roleA
, roleB
and roleC
, the final set of roles
assigned to the principal will be roleC
, roleX
, roleY
and roleZ
because roleA
is being mapped into both roleX
and roleY
, roleB
was mapped into an empty role - thus being discarded, roleC
is used as is and finally an additional role
was added to the kc_user
principal (roleZ
).
Note: to use spaces in role names for mappings, use unicode replacements for space. For example, incoming 'role A' would appear as:
role\u0020A=roleX,roleY
Adding your own role mappings provider
To add a custom role mappings provider one simply needs to implement the org.keycloak.adapters.saml.RoleMappingsProvider
SPI.
For more details see the SAML Role Mappings SPI
section in Server Developer Guide.
IDP Element
Everything in the IDP element describes the settings for the identity provider (authentication server) the SP is communicating with.
<IDP entityID="idp"
signaturesRequired="true"
signatureAlgorithm="RSA_SHA1"
signatureCanonicalizationMethod="http://www.w3.org/2001/10/xml-exc-c14n#">
...
</IDP>
Here are the attribute config options you can specify within the IDP
element declaration.
- entityID
-
This is the issuer ID of the IDP. This setting is REQUIRED.
- signaturesRequired
-
If set to
true
, the client adapter will sign every document it sends to the IDP. Also, the client will expect that the IDP will be signing any documents sent to it. This switch sets the default for all request and response types, but you will see later that you have some fine grain control over this. This setting is OPTIONAL and will default tofalse
. - signatureAlgorithm
-
This is the signature algorithm that the IDP expects signed documents to use. Allowed values are:
RSA_SHA1
,RSA_SHA256
,RSA_SHA512
, andDSA_SHA1
. This setting is OPTIONAL and defaults toRSA_SHA256
. Note thatSHA1
based algorithms are deprecated and can be removed in the future. We recommend the use of some more secure algorithm instead of*_SHA1
. Also, with*_SHA1
algorithms, verifying signatures do not work if the SAML server (usually Keycloak) runs on Java 17 or higher. - signatureCanonicalizationMethod
-
This is the signature canonicalization method that the IDP expects signed documents to use. This setting is OPTIONAL. The default value is
http://www.w3.org/2001/10/xml-exc-c14n#
and should be good for most IDPs. - metadataUrl
-
The URL used to retrieve the IDP metadata, currently this is only used to pick up signing and encryption keys periodically which allow cycling of these keys on the IDP without manual changes on the SP side.
IDP AllowedClockSkew sub element
The AllowedClockSkew
optional sub element defines the allowed clock skew between IDP and SP.
The default value is 0.
<AllowedClockSkew unit="MILLISECONDS">3500</AllowedClockSkew>
- unit
-
It is possible to define the time unit attached to the value for this element. Allowed values are MICROSECONDS, MILLISECONDS, MINUTES, NANOSECONDS and SECONDS. This is OPTIONAL. The default value is
SECONDS
.
IDP SingleSignOnService sub element
The SingleSignOnService
sub element defines the login SAML endpoint of the IDP.
The client adapter will send requests
to the IDP formatted via the settings within this element when it wants to log in.
<SingleSignOnService signRequest="true"
validateResponseSignature="true"
requestBinding="post"
bindingUrl="url"/>
Here are the config attributes you can define on this element:
- signRequest
-
Should the client sign authn requests? This setting is OPTIONAL. Defaults to whatever the IDP
signaturesRequired
element value is. - validateResponseSignature
-
Should the client expect the IDP to sign the assertion response document sent back from an authn request? This setting OPTIONAL. Defaults to whatever the IDP
signaturesRequired
element value is. - requestBinding
-
This is the SAML binding type used for communicating with the IDP. This setting is OPTIONAL. The default value is
POST
, but you can set it toREDIRECT
as well. - responseBinding
-
SAML allows the client to request what binding type it wants authn responses to use. The values of this can be
POST
orREDIRECT
. This setting is OPTIONAL. The default is that the client will not request a specific binding type for responses. - assertionConsumerServiceUrl
-
URL of the assertion consumer service (ACS) where the IDP login service should send responses to. This setting is OPTIONAL. By default it is unset, relying on the configuration in the IdP. When set, it must end in
/saml
, for examplehttp://sp.domain.com/my/endpoint/for/saml
. The value of this property is sent inAssertionConsumerServiceURL
attribute of SAMLAuthnRequest
message. This property is typically accompanied by theresponseBinding
attribute. - bindingUrl
-
This is the URL for the IDP login service that the client will send requests to. This setting is REQUIRED.
IDP SingleLogoutService sub element
The SingleLogoutService
sub element defines the logout SAML endpoint of the IDP. The client adapter will send requests
to the IDP formatted via the settings within this element when it wants to log out.
<SingleLogoutService validateRequestSignature="true"
validateResponseSignature="true"
signRequest="true"
signResponse="true"
requestBinding="redirect"
responseBinding="post"
postBindingUrl="posturl"
redirectBindingUrl="redirecturl">
- signRequest
-
Should the client sign logout requests it makes to the IDP? This setting is OPTIONAL. Defaults to whatever the IDP
signaturesRequired
element value is. - signResponse
-
Should the client sign logout responses it sends to the IDP requests? This setting is OPTIONAL. Defaults to whatever the IDP
signaturesRequired
element value is. - validateRequestSignature
-
Should the client expect signed logout request documents from the IDP? This setting is OPTIONAL. Defaults to whatever the IDP
signaturesRequired
element value is. - validateResponseSignature
-
Should the client expect signed logout response documents from the IDP? This setting is OPTIONAL. Defaults to whatever the IDP
signaturesRequired
element value is. - requestBinding
-
This is the SAML binding type used for communicating SAML requests to the IDP. This setting is OPTIONAL. The default value is
POST
, but you can set it to REDIRECT as well. - responseBinding
-
This is the SAML binding type used for communicating SAML responses to the IDP. The values of this can be
POST
orREDIRECT
. This setting is OPTIONAL. The default value isPOST
, but you can set it toREDIRECT
as well. - postBindingUrl
-
This is the URL for the IDP’s logout service when using the POST binding. This setting is REQUIRED if using the
POST
binding. - redirectBindingUrl
-
This is the URL for the IDP’s logout service when using the REDIRECT binding. This setting is REQUIRED if using the REDIRECT binding.
IDP Keys sub element
The Keys sub element of IDP is only used to define the certificate or public key to use to verify documents signed by the IDP. It is defined in the same way as the SP’s Keys element. But again, you only have to define one certificate or public key reference. Note that, if both IDP and SP are realized by Keycloak server and adapter, respectively, there is no need to specify the keys for signature validation, see below.
It is possible to configure SP to obtain public keys for IDP signature validation from published certificates automatically, provided both SP and IDP are implemented by Keycloak. This is done by removing all declarations of signature validation keys in Keys sub element. If the Keys sub element would then remain empty, it can be omitted completely. The keys are then automatically obtained by SP from SAML descriptor, location of which is derived from SAML endpoint URL specified in the IDP SingleSignOnService sub element. Settings of the HTTP client that is used for SAML descriptor retrieval usually needs no additional configuration, however it can be configured in the IDP HttpClient sub element.
It is also possible to specify multiple keys for signature verification. This is done by declaring multiple Key elements
within Keys sub element that have signing
attribute set to true
.
This is useful for example in situation when the IDP signing keys are rotated: There is
usually a transition period when new SAML protocol messages and assertions are signed
with the new key but those signed by previous key should still be accepted.
It is not possible to configure Keycloak to both obtain the keys for signature verification automatically and define additional static signature verification keys.
<IDP entityID="idp">
...
<Keys>
<Key signing="true">
<KeyStore resource="/WEB-INF/keystore.jks" password="store123">
<Certificate alias="demo"/>
</KeyStore>
</Key>
</Keys>
</IDP>
IDP HttpClient sub element
The HttpClient
optional sub element defines the properties of HTTP client used
for automatic obtaining of certificates containing public keys for IDP signature
verification via SAML descriptor of the IDP when
enabled.
<HttpClient connectionPoolSize="10"
disableTrustManager="false"
allowAnyHostname="false"
clientKeystore="classpath:keystore.jks"
clientKeystorePassword="pwd"
truststore="classpath:truststore.jks"
truststorePassword="pwd"
proxyUrl="http://proxy/"
socketTimeout="5000"
connectionTimeout="6000"
connectionTtl="500" />
- connectionPoolSize
-
This config option defines how many connections to the Keycloak server should be pooled. This is OPTIONAL. The default value is
10
. - disableTrustManager
-
If the Keycloak server requires HTTPS and this config option is set to
true
you do not have to specify a truststore. This setting should only be used during development and never in production as it will disable verification of SSL certificates. This is OPTIONAL. The default value isfalse
. - allowAnyHostname
-
If the Keycloak server requires HTTPS and this config option is set to
true
the Keycloak server’s certificate is validated via the truststore, but host name validation is not done. This setting should only be used during development and never in production as it will partly disable verification of SSL certificates. This setting may be useful in test environments. This is OPTIONAL. The default value isfalse
. - truststore
-
The value is the file path to a truststore file. If you prefix the path with
classpath:
, then the truststore will be obtained from the deployment’s classpath instead. Used for outgoing HTTPS communications to the Keycloak server. Client making HTTPS requests need a way to verify the host of the server they are talking to. This is what the truststore does. The keystore contains one or more trusted host certificates or certificate authorities. You can create this truststore by extracting the public certificate of the Keycloak server’s SSL keystore. This is REQUIRED unlessdisableTrustManager
istrue
. - truststorePassword
-
Password for the truststore. This is REQUIRED if
truststore
is set and the truststore requires a password. - clientKeystore
-
This is the file path to a keystore file. This keystore contains client certificate for two-way SSL when the adapter makes HTTPS requests to the Keycloak server. This is OPTIONAL.
- clientKeystorePassword
-
Password for the client keystore and for the client’s key. This is REQUIRED if
clientKeystore
is set. - proxyUrl
-
URL to HTTP proxy to use for HTTP connections. This is OPTIONAL.
- socketTimeout
-
Timeout for socket waiting for data after establishing the connection in milliseconds. Maximum time of inactivity between two data packets. A timeout value of zero is interpreted as an infinite timeout. A negative value is interpreted as undefined (system default if applicable). The default value is
-1
. This is OPTIONAL. - connectionTimeout
-
Timeout for establishing the connection with the remote host in milliseconds. A timeout value of zero is interpreted as an infinite timeout. A negative value is interpreted as undefined (system default if applicable). The default value is
-1
. This is OPTIONAL. - connectionTtl
-
Connection time-to-live for client in milliseconds. A value less than or equal to zero is interpreted as an infinite value. The default value is
-1
. This is OPTIONAL.
3.1.2. JBoss EAP/WildFly adapter
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.
3.1.3. Installing adapters from a Galleon feature pack
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.
Setting SameSite value for JSESSIONID cookie
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 SAML adapter, we recommend
setting the SameSite
value to None
for the JSESSIONID
cookie created by your container. Not doing so may result in
resetting the container’s session with each request to Keycloak.
To avoid setting the SameSite attribute to None , consider switching to the REDIRECT binding
if it is acceptable, or to OIDC protocol where this workaround is not necessary.
|
To set the SameSite
value to None
for the JSESSIONID
cookie in Wildfly/EAP, add a file undertow-handlers.conf
with the following content to the WEB-INF
directory of your application.
samesite-cookie(mode=None, cookie-pattern=JSESSIONID)
The support for this configuration is available in Wildfly from version 19.1.0.
Securing a WAR
This section describes how to secure a WAR directly by adding config and editing files within your WAR package.
The first thing you must do is create a keycloak-saml.xml
adapter config file within the WEB-INF
directory of your WAR.
The format of this config file is described in the General Adapter Config section.
Next you must set the auth-method
to KEYCLOAK-SAML
in web.xml
.
You also have to use standard servlet security to specify role-base constraints on your URLs.
Here’s an example web.xml file:
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd"
version="6.0">
<module-name>customer-portal</module-name>
<security-constraint>
<web-resource-collection>
<web-resource-name>Admins</web-resource-name>
<url-pattern>/admin/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>admin</role-name>
</auth-constraint>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
<security-constraint>
<web-resource-collection>
<web-resource-name>Customers</web-resource-name>
<url-pattern>/customers/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>user</role-name>
</auth-constraint>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
<login-config>
<auth-method>KEYCLOAK-SAML</auth-method>
<realm-name>this is ignored currently</realm-name>
</login-config>
<security-role>
<role-name>admin</role-name>
</security-role>
<security-role>
<role-name>user</role-name>
</security-role>
</web-app>
All standard servlet settings except the auth-method
setting.
Securing WARs using the Keycloak SAML Subsystem
You do not have to open a WAR to secure it with Keycloak.
Alternatively, you can externally secure it via the Keycloak SAML Adapter Subsystem.
While you don’t have to specify KEYCLOAK-SAML as an auth-method
, you still have to define the security-constraints
in web.xml
.
You do not, however, have to create a WEB-INF/keycloak-saml.xml
file.
This metadata is instead defined within the XML in your server’s domain.xml
or standalone.xml
subsystem configuration section.
<extensions>
<extension module="org.keycloak.keycloak-saml-adapter-subsystem"/>
</extensions>
<profile>
<subsystem xmlns="urn:jboss:domain:keycloak-saml:1.1">
<secure-deployment name="WAR MODULE NAME.war">
<SP entityID="APPLICATION URL">
...
</SP>
</secure-deployment>
</subsystem>
</profile>
The secure-deployment
name
attribute identifies the WAR you want to secure.
Its value is the module-name
defined in web.xml
with .war
appended.
The rest of the configuration uses the same XML syntax as keycloak-saml.xml
configuration defined in General Adapter Config.
An example configuration:
<subsystem xmlns="urn:jboss:domain:keycloak-saml:1.1">
<secure-deployment name="saml-post-encryption.war">
<SP entityID="http://localhost:8080/sales-post-enc/"
sslPolicy="EXTERNAL"
nameIDPolicyFormat="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
logoutPage="/logout.jsp"
forceAuthentication="false">
<Keys>
<Key signing="true" encryption="true">
<KeyStore resource="/WEB-INF/keystore.jks" password="store123">
<PrivateKey alias="http://localhost:8080/sales-post-enc/" password="test123"/>
<Certificate alias="http://localhost:8080/sales-post-enc/"/>
</KeyStore>
</Key>
</Keys>
<PrincipalNameMapping policy="FROM_NAME_ID"/>
<RoleIdentifiers>
<Attribute name="Role"/>
</RoleIdentifiers>
<IDP entityID="idp">
<SingleSignOnService signRequest="true"
validateResponseSignature="true"
requestBinding="POST"
bindingUrl="http://localhost:8080/realms/saml-demo/protocol/saml"/>
<SingleLogoutService
validateRequestSignature="true"
validateResponseSignature="true"
signRequest="true"
signResponse="true"
requestBinding="POST"
responseBinding="POST"
postBindingUrl="http://localhost:8080/realms/saml-demo/protocol/saml"
redirectBindingUrl="http://localhost:8080/realms/saml-demo/protocol/saml"/>
<Keys>
<Key signing="true" >
<KeyStore resource="/WEB-INF/keystore.jks" password="store123">
<Certificate alias="saml-demo"/>
</KeyStore>
</Key>
</Keys>
</IDP>
</SP>
</secure-deployment>
</subsystem>
3.1.4. Tomcat SAML adapters
The Keycloak Tomcat SAML adapter is deprecated. We recommend that you use another client adapter if possible. |
To be able to secure WAR apps deployed on Tomcat 8 or 9 you must install the Keycloak Tomcat SAML adapter into your Tomcat installation. You then have to provide some extra configuration in each WAR you deploy to Tomcat.
Installing the adapter
Adapters are no longer included with the appliance or war distribution. Each adapter is a separate download on the Keycloak Downloads site. They are also available as a maven artifact.
-
Download the adapter for the Tomcat version on your system from the Keycloak Downloads site:
-
Install on the Tomcat version on your system:
-
Install on Tomcat 8 or 9:
$ cd $TOMCAT_HOME/lib $ unzip keycloak-saml-tomcat-adapter-dist.zip
-
Including the adapter’s jars within your WEB-INF/lib directory will not work. The Keycloak SAML adapter is implemented as a Valve and valve code must reside in Tomcat’s main lib/ directory. |
Securing a WAR
Use this procedure to secure a WAR directly by adding config and editing files within your WAR package.
-
Create a
META-INF/context.xml
file in your WAR package. This is a Tomcat specific config file and you must define a Keycloak specific Valve.<Context path="/your-context-path"> <Valve className="org.keycloak.adapters.saml.tomcat.SamlAuthenticatorValve"/> </Context>
-
Create a
keycloak-saml.xml
adapter config file within theWEB-INF
directory of your WAR. The format of this config file is described in the General Adapter Config section. -
Specify both a
login-config
and use standard servlet security to specify role-base constraints on your URLs. Here’s an example:<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" version="3.0"> <module-name>customer-portal</module-name> <security-constraint> <web-resource-collection> <web-resource-name>Customers</web-resource-name> <url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>user</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>BASIC</auth-method> <realm-name>this is ignored currently</realm-name> </login-config> <security-role> <role-name>admin</role-name> </security-role> <security-role> <role-name>user</role-name> </security-role> </web-app>
If the keycloak-saml.xml
does not explicitly set assertionConsumerServiceUrl
, the SAML adapter will implicitly listen for SAML assertions at the location /my-context-path/saml
. This has to match Master SAML Processing URL
in the IDP realm/client settings, for example http://sp.domain.com/my-context-path/saml
. If not, Tomcat will probably redirect infinitely to the IDP login service, as it does not receive the SAML assertion after the user logged in.
Setting SameSite value for JSESSIONID cookie
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 SAML adapter, we recommend
setting the SameSite
value to None
for the JSESSIONID
cookie created by your container. Not doing so may result in
resetting the container’s session with each request to Keycloak.
To avoid setting the SameSite attribute to None , consider switching to the REDIRECT binding
if it is acceptable, or to OIDC protocol where this workaround is not necessary.
|
To set the SameSite
value to None
for JSESSIONID
cookie in Tomcat add following configuration to the`context.xml`
of your application. Note, this will set the SameSite
value to None
for all cookies created by Tomcat container.
<CookieProcessor sameSiteCookies="None" />
It is not possible to set the SameSite attribute only to a subset of cookies, therefore all cookies created
for your application will have this attribute set to None .
|
The support for this feature is available in Tomcat from versions 9.0.29 and 8.5.49.
3.1.5. Jetty SAML adapters
The Keycloak Jetty SAML adapter is deprecated. We recommend that you use another client adapter if possible. |
To be able to secure WAR apps deployed on Jetty you must install the Keycloak Jetty 9.4 SAML adapter into your Jetty installation. You then provide some extra configuration in each WAR you deploy to Jetty.
Use the following installation and configuration procedures.
Jetty 9 Installing the adapter
Keycloak has a separate SAML adapter for Jetty 9.4. Adapters are no longer included with the appliance or war distribution. Each adapter is a separate download on the Keycloak download site. They are also available as a maven artifact.
-
Download the Keycloak Jetty 9.4 adapter ZIP archive from the Keycloak Downloads site.
-
Unzip the Jetty 9.4 distro into Jetty 9.4’s root directory.
Including adapter’s jars within your WEB-INF/lib directory will not work. $ cd $JETTY_HOME $ unzip keycloak-saml-jetty94-adapter-dist.zip
-
Enable the keycloak module for your jetty.base.
$ cd your-base $ java -jar $JETTY_HOME/start.jar --add-to-startd=keycloak
Jetty 9 WAR Configuration
Use this procedure to secure a WAR directly.
-
Create a
WEB-INF/jetty-web.xml
file in your WAR package. This is a Jetty specific config file and you must define a Keycloak specific authenticator within it.<?xml version="1.0"?> <!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Get name="securityHandler"> <Set name="authenticator"> <New class="org.keycloak.adapters.saml.jetty.KeycloakSamlAuthenticator"> </New> </Set> </Get> </Configure>
-
Create a
keycloak-saml.xml
adapter config file within theWEB-INF
directory of your WAR. The format of this config file is described in the General Adapter Config section. -
Specify both a
login-config
and use standard servlet security to specify role-base constraints on your URLs. Here’s an example:<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" version="3.0"> <module-name>customer-portal</module-name> <security-constraint> <web-resource-collection> <web-resource-name>Customers</web-resource-name> <url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>user</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> </security-constraint> <login-config> <auth-method>BASIC</auth-method> <realm-name>this is ignored currently</realm-name> </login-config> <security-role> <role-name>admin</role-name> </security-role> <security-role> <role-name>user</role-name> </security-role> </web-app>
3.1.6. Java Servlet filter adapter
If you want to use SAML with a Java servlet application that doesn’t have an adapter for that servlet platform, you can
opt to use the servlet filter adapter that Keycloak has.
This adapter works a little differently than the other adapters.
You still have to specify a /WEB-INF/keycloak-saml.xml
file as defined in
the General Adapter Config section, but
you do not define security constraints in web.xml.
Instead you define a filter mapping using the Keycloak servlet filter adapter to secure the url patterns you want to secure.
Backchannel logout works a bit differently than the standard adapters. Instead of invalidating the http session it instead marks the session ID as logged out. There’s just no way of arbitrarily invalidating an HTTP session based on a session ID. |
Backchannel logout does not currently work when you have a clustered application that uses the SAML filter. |
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">
<module-name>customer-portal</module-name>
<filter>
<filter-name>Keycloak Filter</filter-name>
<filter-class>org.keycloak.adapters.saml.servlet.SamlFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>Keycloak Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
</web-app>
The Keycloak filter has the same configuration parameters available as the other adapters except you must define them as filter init params instead of context params.
You can define multiple filter mappings if you have various different secure and unsecure url patterns.
You must have a filter mapping that covers /saml .
This mapping covers all server callbacks.
|
When registering SPs with an IdP, you must register http[s]://hostname/{context-root}/saml
as your Assert Consumer Service URL and Single Logout Service URL.
To use this filter, include this maven artifact in your WAR poms:
<dependency>
<groupId>org.keycloak</groupId>
<artifactId>keycloak-saml-servlet-filter-adapter</artifactId>
<version>23.0.2</version>
</dependency>
In order to use Multi Tenancy the keycloak.config.resolver
parameter should be passed as a filter parameter.
<filter>
<filter-name>Keycloak Filter</filter-name>
<filter-class>org.keycloak.adapters.saml.servlet.SamlFilter</filter-class>
<init-param>
<param-name>keycloak.config.resolver</param-name>
<param-value>example.SamlMultiTenantResolver</param-value>
</init-param>
</filter>
3.1.7. Registering with an Identity Provider
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
.
3.1.8. Logout
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.
Logout in clustered environment
Internally, the SAML adapter stores a mapping between the SAML session index, principal name (when known), and HTTP session ID.
This mapping can be maintained in JBoss application server family (WildFly 10/11, EAP 6/7) across cluster for distributable
applications. As a precondition, the HTTP sessions need to be distributed across cluster (i.e. application is marked with
<distributable/>
tag in application’s web.xml
).
To enable the functionality, add the following section to your /WEB_INF/web.xml
file:
For EAP 7, WildFly 10/11:
<context-param>
<param-name>keycloak.sessionIdMapperUpdater.classes</param-name>
<param-value>org.keycloak.adapters.saml.wildfly.infinispan.InfinispanSessionCacheIdMapperUpdater</param-value>
</context-param>
For EAP 6:
<context-param>
<param-name>keycloak.sessionIdMapperUpdater.classes</param-name>
<param-value>org.keycloak.adapters.saml.jbossweb.infinispan.InfinispanSessionCacheIdMapperUpdater</param-value>
</context-param>
If the session cache of the deployment is named deployment-cache
, the cache used for SAML mapping will be named
as deployment-cache.ssoCache
. The name of the cache can be overridden by a context parameter
keycloak.sessionIdMapperUpdater.infinispan.cacheName
. The cache container containing the cache will be the same as
the one containing the deployment session cache, but can be overridden by a context parameter
keycloak.sessionIdMapperUpdater.infinispan.containerName
.
By default, the configuration of the SAML mapping cache will be derived from session cache. The configuration can be manually overridden in cache configuration section of the server just the same as other caches.
Currently, to provide reliable service, it is recommended to use replicated cache for the SAML session cache. Using distributed cache may lead to results where the SAML logout request would land to a node with no access to SAML session index to HTTP session mapping which would lead to unsuccessful logout.
Logout in cross-site scenario
The cross-site scenario only applies to WildFly 10 and higher, and EAP 7 and higher.
Special handling is needed for handling sessions that span multiple data centers. Imagine the following scenario:
-
Login requests are handled within cluster in data center 1.
-
Admin issues logout request for a particular SAML session, the request lands in data center 2.
The data center 2 has to log out all sessions that are present in data center 1 (and all other data centers that share HTTP sessions).
To cover this case, the SAML session cache described above needs to be replicated not only within individual clusters but across all the data centers for example via standalone Infinispan/JDG server:
-
A cache has to be added to the standalone Infinispan/JDG server.
-
The cache from previous item has to be added as a remote store for the respective SAML session cache.
Once remote store is found to be present on SAML session cache during deployment, it is watched for changes and the local SAML session cache is updated accordingly.
3.1.9. Obtaining assertion attributes
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.
package org.keycloak.adapters.saml;
public class SamlPrincipal implements Serializable, Principal {
/**
* Get full saml assertion
*
* @return
*/
public AssertionType getAssertion() {
...
}
/**
* Get SAML subject sent in assertion
*
* @return
*/
public String getSamlSubject() {
...
}
/**
* Subject nameID format
*
* @return
*/
public String getNameIDFormat() {
...
}
@Override
public String getName() {
...
}
/**
* Convenience function that gets Attribute value by attribute name
*
* @param name
* @return
*/
public List<String> getAttributes(String name) {
...
}
/**
* Convenience function that gets Attribute value by attribute friendly name
*
* @param friendlyName
* @return
*/
public List<String> getFriendlyAttributes(String friendlyName) {
...
}
/**
* Convenience function that gets first value of an attribute by attribute name
*
* @param name
* @return
*/
public String getAttribute(String name) {
...
}
/**
* Convenience function that gets first value of an attribute by attribute name
*
*
* @param friendlyName
* @return
*/
public String getFriendlyAttribute(String friendlyName) {
...
}
/**
* Get set of all assertion attribute names
*
* @return
*/
public Set<String> getAttributeNames() {
...
}
/**
* Get set of all assertion friendly attribute names
*
* @return
*/
public Set<String> getFriendlyNames() {
...
}
}
3.1.10. Error Handling
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.
<error-page>
<error-code>403</error-code>
<location>/ErrorHandler</location>
</error-page>
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.
public class SamlAuthenticationError implements AuthenticationError {
public static enum Reason {
EXTRACTION_FAILURE,
INVALID_SIGNATURE,
ERROR_STATUS
}
public Reason getReason() {
return reason;
}
public StatusResponseType getStatus() {
return status;
}
}
3.1.11. Troubleshooting
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.
3.1.12. Multi Tenancy
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:
package example;
import java.io.InputStream;
import org.keycloak.adapters.saml.SamlConfigResolver;
import org.keycloak.adapters.saml.SamlDeployment;
import org.keycloak.adapters.saml.config.parsers.DeploymentBuilder;
import org.keycloak.adapters.saml.config.parsers.ResourceLoader;
import org.keycloak.adapters.spi.HttpFacade;
import org.keycloak.saml.common.exceptions.ParsingException;
public class SamlMultiTenantResolver implements SamlConfigResolver {
@Override
public SamlDeployment resolve(HttpFacade.Request request) {
String host = request.getHeader("Host");
String realm = null;
if (host.contains("tenant1")) {
realm = "tenant1";
} else if (host.contains("tenant2")) {
realm = "tenant2";
} else {
throw new IllegalStateException("Not able to guess the keycloak-saml.xml to load");
}
InputStream is = getClass().getResourceAsStream("/" + realm + "-keycloak-saml.xml");
if (is == null) {
throw new IllegalStateException("Not able to find the file /" + realm + "-keycloak-saml.xml");
}
ResourceLoader loader = new ResourceLoader() {
@Override
public InputStream getResourceAsStream(String path) {
return getClass().getResourceAsStream(path);
}
};
try {
return new DeploymentBuilder().build(is, loader);
} catch (ParsingException e) {
throw new IllegalStateException("Cannot load SAML deployment", e);
}
}
}
You must also configure which SamlConfigResolver
implementation to use with the keycloak.config.resolver
context-param in your web.xml
:
<web-app>
...
<context-param>
<param-name>keycloak.config.resolver</param-name>
<param-value>example.SamlMultiTenantResolver</param-value>
</context-param>
</web-app>
3.1.13. Migration from older versions
Migrating to 1.9.0
SAML SP Client Adapter changes
Keycloak SAML SP Client Adapter now requires a specific endpoint, /saml
to be registered with your IdP.
The SamlFilter must also be bound to /saml in addition to any other binding it has.
This had to be done because SAML POST binding would eat the request input stream and this would be really bad for clients that relied on it.
3.2. mod_auth_mellon Apache HTTPD Module
Keycloak does not provide any official support to mod_auth_mellon. The instructions below are best-effort and may not be up-to-date. We recommend that you stick to official mod_auth_mellon documentation for more details. |
The mod_auth_mellon module is an Apache HTTPD plugin for SAML. If your language/environment supports using Apache HTTPD as a proxy, then you can use mod_auth_mellon to secure your web application with SAML. For more details on this module see the mod_auth_mellon GitHub repo.
To configure mod_auth_mellon you need:
-
An Identity Provider (IdP) entity descriptor XML file, which describes the connection to Keycloak or another SAML IdP
-
An SP entity descriptor XML file, which describes the SAML connections and configuration for the application you are securing.
-
A private key PEM file, which is a text file in the PEM format that defines the private key the application uses to sign documents.
-
A certificate PEM file, which is a text file that defines the certificate for your application.
-
mod_auth_mellon-specific Apache HTTPD module configuration.
If you have already defined and registered the client application within a realm on the Keycloak application server, Keycloak can generate all the files you need except the Apache HTTPD module configuration.
Perform the following procedure to generate the Apache HTTPD module configuration.
-
Go to the Installation page of your SAML client.
-
Select the Mod Auth Mellon files option.
mod_auth_mellon config download -
Click Download to download a ZIP file that contains the XML descriptor and PEM files you need.
3.2.1. Configuring mod_auth_mellon with Keycloak
There are two hosts involved:
-
The host on which Keycloak is running, which will be referred to as $idp_host because Keycloak is a SAML identity provider (IdP).
-
The host on which the web application is running, which will be referred to as $sp_host. In SAML an application using an IdP is called a service provider (SP).
All of the following steps need to performed on $sp_host with root privileges.
Installing the packages
To install the necessary packages, you will need:
-
Apache Web Server (httpd)
-
Mellon SAML SP add-on module for Apache
-
Tools to create X509 certificates
To install the necessary packages, run this command:
yum install httpd mod_auth_mellon mod_ssl openssl
Creating a configuration directory for Apache SAML
It is advisable to keep configuration files related to Apache’s use of SAML in one location.
Create a new directory named saml2 located under the Apache configuration root /etc/httpd:
mkdir /etc/httpd/saml2
Configuring the Mellon Service Provider
Configuration files for Apache add-on modules are located in the /etc/httpd/conf.d directory and have a file name extension of .conf. You need to create the /etc/httpd/conf.d/mellon.conf file and place Mellon’s configuration directives in it.
Mellon’s configuration directives can roughly be broken down into two classes of information:
-
Which URLs to protect with SAML authentication
-
What SAML parameters will be used when a protected URL is referenced.
Apache configuration directives typically follow a hierarchical tree structure in the URL space, which are known as locations. You need to specify one or more URL locations for Mellon to protect. You have flexibility in how you add the configuration parameters that apply to each location. You can either add all the necessary parameters to the location block or you can add Mellon parameters to a common location high up in the URL location hierarchy that specific protected locations inherit (or some combination of the two). Since it is common for an SP to operate in the same way no matter which location triggers SAML actions, the example configuration used here places common Mellon configuration directives in the root of the hierarchy and then specific locations to be protected by Mellon can be defined with minimal directives. This strategy avoids duplicating the same parameters for each protected location.
This example has just one protected location: https://$sp_host/private.
To configure the Mellon service provider, perform the following procedure.
-
Create the file /etc/httpd/conf.d/mellon.conf with this content:
<Location / >
MellonEnable info
MellonEndpointPath /mellon/
MellonSPMetadataFile /etc/httpd/saml2/mellon_metadata.xml
MellonSPPrivateKeyFile /etc/httpd/saml2/mellon.key
MellonSPCertFile /etc/httpd/saml2/mellon.crt
MellonIdPMetadataFile /etc/httpd/saml2/idp_metadata.xml
</Location>
<Location /private >
AuthType Mellon
MellonEnable auth
Require valid-user
</Location>
Some of the files referenced in the code above are created in later steps. |
3.2.2. Setting the SameSite value for the cookie used by mod_auth_mellon
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.
MellonSecureCookie On
MellonCookieSameSite none
The support for this configuration is available in the mod_auth_mellon module from version 0.16.0.
Creating the Service Provider metadata
In SAML IdPs and SPs exchange SAML metadata, which is in XML format. The schema for the metadata is a standard, thus assuring participating SAML entities can consume each other’s metadata. You need:
-
Metadata for the IdP that the SP utilizes
-
Metadata describing the SP provided to the IdP
One of the components of SAML metadata is X509 certificates. These certificates are used for two purposes:
-
Sign SAML messages so the receiving end can prove the message originated from the expected party.
-
Encrypt the message during transport (seldom used because SAML messages typically occur on TLS-protected transports)
You can use your own certificates if you already have a Certificate Authority (CA) or you can generate a self-signed certificate. For simplicity in this example a self-signed certificate is used.
Because Mellon’s SP metadata must reflect the capabilities of the installed version of mod_auth_mellon, must be valid SP metadata XML, and must contain an X509 certificate (whose creation can be obtuse unless you are familiar with X509 certificate generation) the most expedient way to produce the SP metadata is to use a tool included in the mod_auth_mellon package (mellon_create_metadata.sh). The generated metadata can always be edited later because it is a text file. The tool also creates your X509 key and certificate.
SAML IdPs and SPs identify themselves using a unique name known as an EntityID. To use the Mellon metadata creation tool you need:
-
The EntityID, which is typically the URL of the SP, and often the URL of the SP where the SP metadata can be retrieved
-
The URL where SAML messages for the SP will be consumed, which Mellon calls the MellonEndPointPath.
To create the SP metadata, perform the following procedure.
-
Create a few helper shell variables:
fqdn=`hostname` mellon_endpoint_url="https://${fqdn}/mellon" mellon_entity_id="${mellon_endpoint_url}/metadata" file_prefix="$(echo "$mellon_entity_id" | sed 's/[^A-Za-z.]/_/g' | sed 's/__*/_/g')"
-
Invoke the Mellon metadata creation tool by running this command:
/usr/libexec/mod_auth_mellon/mellon_create_metadata.sh $mellon_entity_id $mellon_endpoint_url
-
Move the generated files to their destination (referenced in the /etc/httpd/conf.d/mellon.conf file created above):
mv ${file_prefix}.cert /etc/httpd/saml2/mellon.crt mv ${file_prefix}.key /etc/httpd/saml2/mellon.key mv ${file_prefix}.xml /etc/httpd/saml2/mellon_metadata.xml
Adding the Mellon Service Provider to the Keycloak Identity Provider
Assumption: The Keycloak IdP has already been installed on the $idp_host.
Keycloak supports multiple tenancy where all users, clients, and so on are grouped in what is called a realm. Each realm is independent of other realms. You can use an existing realm in your Keycloak, but this example shows how to create a new realm called test_realm and use that realm.
All these operations are performed using the Keycloak Admin Console. You must have the admin username and password for $idp_host to perform the following procedure.
-
Open the Admin Console and log on by entering the admin username and password.
After logging into the Admin Console, there will be an existing realm. When Keycloak is first set up a root realm, master, is created by default. Any previously created realms are listed in the upper left corner of the Admin Console in a drop-down list.
-
From the realm drop-down list select Add realm.
-
In the Name field type
test_realm
and click Create.
Adding the Mellon Service Provider as a client of the realm
In Keycloak SAML SPs are known as clients. To add the SP we must be in the Clients section of the realm.
-
Click the Clients menu item on the left and click Create in the upper right corner to create a new client.
Adding the Mellon SP client
To add the Mellon SP client, perform the following procedure.
-
Set the client protocol to SAML.
-
From the Client Protocol drop down list, select saml.
-
Provide the Mellon SP metadata file created above (/etc/httpd/saml2/mellon_metadata.xml).
Depending on where your browser is running you might have to copy the SP metadata from $sp_host to the machine on which your browser is running so the browser can find the file.
-
Click Save.
Editing the Mellon SP client
Use this procedure to set important client configuration parameters.
-
Ensure "Force POST Binding" is On.
-
Add paosResponse to the Valid Redirect URIs list:
-
Copy the postResponse URL in "Valid Redirect URIs" and paste it into the empty add text fields just below the "+".
-
Change "postResponse" to "paosResponse". (The paosResponse URL is needed for SAML ECP.)
-
Click Save at the bottom.
Many SAML SPs determine authorization based on a user’s membership in a group. The Keycloak IdP can manage user group information but it does not supply the user’s groups unless the IdP is configured to supply it as a SAML attribute.
Perform the following procedure to configure the IdP to supply the user’s groups as a SAML attribute.
-
Click the Mappers tab of the client.
-
In the upper right corner of the Mappers page, click Create.
-
From the Mapper Type drop-down list select Group list.
-
Set Name to "group list".
-
Set the SAML attribute name to "groups".
-
Click Save.
The remaining steps are performed on $sp_host.
Retrieving the Identity Provider metadata
Now that you have created the realm on the IdP you need to retrieve the IdP metadata associated with it so the Mellon SP recognizes it. In the /etc/httpd/conf.d/mellon.conf file created previously, the MellonIdPMetadataFile is specified as /etc/httpd/saml2/idp_metadata.xml but until now that file has not existed on $sp_host.
Use this procedure to retrieve that file from the IdP.
-
Use this command, substituting with the correct value for $idp_host:
curl -k -o /etc/httpd/saml2/idp_metadata.xml \ https://$idp_host/realms/test_realm/protocol/saml/descriptor
Mellon is now fully configured.
-
To run a syntax check for Apache configuration files, use this command:
apachectl configtest
Configtest is equivalent to the -t argument to apachectl. If the configuration test shows any errors, correct them before proceeding. -
Restart the Apache server:
systemctl restart httpd.service
You have now set up both Keycloak as a SAML IdP in the test_realm and mod_auth_mellon as SAML SP protecting the URL $sp_host/protected (and everything beneath it) by authenticating against the $idp_host
IdP.
4. Configuring a Docker registry to use Keycloak
Docker authentication is disabled by default. To enable see the Enabling and disabling features guide. |
This section describes how you can configure a Docker registry to use Keycloak as its authentication server.
For more information on how to set up and configure a Docker registry, see the Docker Registry Configuration Guide.
4.1. Docker registry configuration file installation
For users with more advanced Docker registry configurations, it is generally recommended to provide your own registry configuration file. The Keycloak Docker provider supports this mechanism via the Registry Config File Format Option. Choosing this option will generate output similar to the following:
auth:
token:
realm: http://localhost:8080/realms/master/protocol/docker-v2/auth
service: docker-test
issuer: http://localhost:8080/realms/master
This output can then be copied into any existing registry config file. See the registry config file specification for more information on how the file should be set up, or start with a basic example.
Don’t forget to configure the rootcertbundle field with the location of the Keycloak realm’s public key. The auth configuration will not work without this argument.
|
4.2. Docker registry environment variable override installation
Often times it is appropriate to use a simple environment variable override for develop or POC Docker registries. While this approach is usually not recommended for production use, it can be helpful when one requires quick-and-dirty way to stand up a registry. Simply use the Variable Override Format Option from the client details, and an output should appear like the one below:
REGISTRY_AUTH_TOKEN_REALM: http://localhost:8080/realms/master/protocol/docker-v2/auth
REGISTRY_AUTH_TOKEN_SERVICE: docker-test
REGISTRY_AUTH_TOKEN_ISSUER: http://localhost:8080/realms/master
Don’t forget to configure the REGISTRY_AUTH_TOKEN_ROOTCERTBUNDLE override with the location of the Keycloak realm’s public key. The auth configuration will not work without this argument.
|
4.3. Docker Compose YAML File
This installation method is meant to be an easy way to get a docker registry authenticating against a Keycloak server. It is intended for development purposes only and should never be used in a production or production-like environment. |
The zip file installation mechanism provides a quickstart for developers who want to understand how the Keycloak server can interact with the Docker registry. In order to configure:
-
From the desired realm, create a client configuration. At this point you will not have a Docker registry - the quickstart will take care of that part.
-
Choose the "Docker Compose YAML" option from the from Action menu and select the Download adapter config option to download the ZIP file.
-
Unzip the archive to the desired location, and open the directory.
-
Start the Docker registry with
docker-compose up
it is recommended that you configure the Docker registry client in a realm other than 'master', since the HTTP Basic auth flow will not present forms. |
Once the above configuration has taken place, and the keycloak server and Docker registry are running, docker authentication should be successful:
[user ~]# docker login localhost:5000 -u $username Password: ******* Login Succeeded
5. Using the client registration service
In order for an application or service to utilize Keycloak it has to register a client in Keycloak. An admin can do this through the admin console (or admin REST endpoints), but clients can also register themselves through the Keycloak client registration service.
The Client Registration Service provides built-in support for Keycloak Client Representations, OpenID Connect Client Meta Data and SAML Entity Descriptors.
The Client Registration Service endpoint is /realms/<realm>/clients-registrations/<provider>
.
The built-in supported providers
are:
-
default - Keycloak Client Representation (JSON)
-
install - Keycloak Adapter Configuration (JSON)
-
openid-connect - OpenID Connect Client Metadata Description (JSON)
-
saml2-entity-descriptor - SAML Entity Descriptor (XML)
The following sections will describe how to use the different providers.
5.1. Authentication
To invoke the Client Registration Services you usually need a token. The token can be a bearer token, an initial access token or a registration access token. There is an alternative to register new client without any token as well, but then you need to configure Client Registration Policies (see below).
5.1.1. Bearer token
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):
-
create-client or manage-client - To create clients
-
view-client or manage-client - To view clients
-
manage-client - To update or delete client
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).
5.1.2. Initial Access Token
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:
Authorization: bearer eyJhbGciOiJSUz...
5.1.3. Registration Access Token
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
.
5.2. Keycloak Representations
The default
client registration provider can be used to create, retrieve, update and delete a client.
It uses Keycloak Client Representation format which provides support for configuring clients exactly as they can be configured through the admin
console, including for example configuring protocol mappers.
To create a client create a Client Representation (JSON) then perform an HTTP POST request to /realms/<realm>/clients-registrations/default
.
It will return a Client Representation that also includes the registration access token. You should save the registration access token somewhere if you want to retrieve the config, update or delete the client later.
To retrieve the Client Representation perform an HTTP GET request to /realms/<realm>/clients-registrations/default/<client id>
.
It will also return a new registration access token.
To update the Client Representation perform an HTTP PUT request with the updated Client Representation to:
/realms/<realm>/clients-registrations/default/<client id>
.
It will also return a new registration access token.
To delete the Client Representation perform an HTTP DELETE request to:
/realms/<realm>/clients-registrations/default/<client id>
5.3. Keycloak adapter configuration
The installation
client registration provider can be used to retrieve the adapter configuration for a client.
In addition to token authentication you can also authenticate with client credentials using HTTP basic authentication.
To do this include the following header in the request:
Authorization: basic BASE64(client-id + ':' + client-secret)
To retrieve the Adapter Configuration then perform an HTTP GET request to /realms/<realm>/clients-registrations/install/<client id>
.
No authentication is required for public clients. This means that for the JavaScript adapter you can load the client configuration directly from Keycloak using the above URL.
5.4. OpenID Connect Dynamic Client Registration
Keycloak implements OpenID Connect Dynamic Client Registration, which extends OAuth 2.0 Dynamic Client Registration Protocol and OAuth 2.0 Dynamic Client Registration Management Protocol.
The endpoint to use these specifications to register clients in Keycloak is /realms/<realm>/clients-registrations/openid-connect[/<client id>]
.
This endpoint can also be found in the OpenID Connect Discovery endpoint for the realm, /realms/<realm>/.well-known/openid-configuration
.
5.5. SAML Entity Descriptors
The SAML Entity Descriptor endpoint only supports using SAML v2 Entity Descriptors to create clients. It doesn’t support retrieving, updating or deleting clients. For those operations the Keycloak representation endpoints should be used. When creating a client a Keycloak Client Representation is returned with details about the created client, including a registration access token.
To create a client perform an HTTP POST request with the SAML Entity Descriptor to /realms/<realm>/clients-registrations/saml2-entity-descriptor
.
5.6. Example using CURL
The following example creates a client with the clientId myclient
using CURL. You need to replace eyJhbGciOiJSUz…
with a proper initial access token or
bearer token.
curl -X POST \
-d '{ "clientId": "myclient" }' \
-H "Content-Type:application/json" \
-H "Authorization: bearer eyJhbGciOiJSUz..." \
http://localhost:8080/realms/master/clients-registrations/default
5.7. Example using Java Client Registration API
The Client Registration Java API makes it easy to use the Client Registration Service using Java.
To use include the dependency org.keycloak:keycloak-client-registration-api:>VERSION<
from Maven.
For full instructions on using the Client Registration refer to the JavaDocs.
Below is an example of creating a client. You need to replace eyJhbGciOiJSUz…
with a proper initial access token or bearer token.
String token = "eyJhbGciOiJSUz...";
ClientRepresentation client = new ClientRepresentation();
client.setClientId(CLIENT_ID);
ClientRegistration reg = ClientRegistration.create()
.url("http://localhost:8080", "myrealm")
.build();
reg.auth(Auth.token(token));
client = reg.create(client);
String registrationAccessToken = client.getRegistrationAccessToken();
5.8. Client Registration Policies
The current plans are for the Client Registration Policies to be removed in favor of the Client Policies described in the Server Administration Guide. Client Policies are more flexible and support more use cases. |
Keycloak currently supports two ways how new clients can be registered through Client Registration Service.
-
Authenticated requests - Request to register new client must contain either
Initial Access Token
orBearer Token
as mentioned above. -
Anonymous requests - Request to register new client doesn’t need to contain any token at all
Anonymous client registration requests are very interesting and powerful feature, however you usually don’t want that anyone is able to register new
client without any limitations. Hence we have Client Registration Policy SPI
, which provide a way to limit who can register new clients and under which conditions.
In Keycloak admin console, you can click to Client Registration
tab and then Client Registration Policies
sub-tab. Here you will see what policies
are configured by default for anonymous requests and what policies are configured for authenticated requests.
The anonymous requests (requests without any token) are allowed just for creating (registration) of new clients. So when you register
new client through anonymous request, the response will contain Registration Access Token, which must be used for Read, Update or Delete request of particular client.
However using this Registration Access Token from anonymous registration will be then subject to Anonymous Policy too! This means that for example request for update
client also needs to come from Trusted Host if you have Trusted Hosts policy. Also for example it won’t be allowed to disable Consent Required when updating client and
when Consent Required policy is present etc.
|
Currently we have these policy implementations:
-
Trusted Hosts Policy - You can configure list of trusted hosts and trusted domains. Request to Client Registration Service can be sent just from those hosts or domains. Request sent from some untrusted IP will be rejected. URLs of newly registered client must also use just those trusted hosts or domains. For example it won’t be allowed to set
Redirect URI
of client pointing to some untrusted host. By default, there is not any whitelisted host, so anonymous client registration is de-facto disabled. -
Consent Required Policy - Newly registered clients will have
Consent Allowed
switch enabled. So after successful authentication, user will always see consent screen when he needs to approve permissions (client scopes). It means that client won’t have access to any personal info or permission of user unless user approves it. -
Protocol Mappers Policy - Allows to configure list of whitelisted protocol mapper implementations. New client can’t be registered or updated if it contains some non-whitelisted protocol mapper. Note that this policy is used for authenticated requests as well, so even for authenticated request there are some limitations which protocol mappers can be used.
-
Client Scope Policy - Allow to whitelist
Client Scopes
, which can be used with newly registered or updated clients. There are no whitelisted scopes by default; only the client scopes, which are defined asRealm Default Client Scopes
are whitelisted by default. -
Full Scope Policy - Newly registered clients will have
Full Scope Allowed
switch disabled. This means they won’t have any scoped realm roles or client roles of other clients. -
Max Clients Policy - Rejects registration if current number of clients in the realm is same or bigger than specified limit. It’s 200 by default for anonymous registrations.
-
Client Disabled Policy - Newly registered client will be disabled. This means that admin needs to manually approve and enable all newly registered clients. This policy is not used by default even for anonymous registration.
6. Automating Client Registration with the CLI
The Client Registration CLI is a command-line interface (CLI) tool for application developers to configure new clients in a self-service manner when integrating with Keycloak. It is specifically designed to interact with Keycloak Client Registration REST endpoints.
It is necessary to create or obtain a client configuration for any application to be able to use Keycloak. You usually configure a new client for each new application hosted on a unique host name. When an application interacts with Keycloak, the application identifies itself with a client ID so Keycloak can provide a login page, single sign-on (SSO) session management, and other services.
You can configure application clients from a command line with the Client Registration CLI, and you can use it in shell scripts.
To allow a particular user to use Client Registration CLI
the Keycloak administrator typically uses the Admin Console to configure a new user with proper roles or to configure a new client and client secret to grant access to the Client Registration REST API.
6.1. Configuring a new regular user for use with Client Registration CLI
-
Log in to the Admin Console (for example, http://localhost:8080/admin) as
admin
. -
Select a realm to administer.
-
If you want to use an existing user, select that user to edit; otherwise, create a new user.
-
Select Role Mappings > Client Roles > realm-management. If you are in the master realm, select NAME-realm, where
NAME
is the name of the target realm. You can grant access to any other realm to users in the master realm. -
Select Available Roles > manage-client to grant a full set of client management permissions. Another option is to choose view-clients for read-only or create-client to create new clients.
These permissions grant the user the capability to perform operations without the use of Initial Access Token or Registration Access Token.
It is possible to not assign any realm-management
roles to a user. In that case, a user can still log in with the Client Registration CLI but cannot use it without an Initial Access Token. Trying to perform any operations without a token results in a 403 Forbidden error.
The Administrator can issue Initial Access Tokens from the Admin Console through the Realm Settings > Client Registration > Initial Access Token menu.
6.2. Configuring a client for use with the Client Registration CLI
By default, the server recognizes the Client Registration CLI as the admin-cli
client, which is configured automatically for every new realm. No additional client configuration is necessary when logging in with a user name.
-
Create a client (for example,
reg-cli
) if you want to use a separate client configuration for the Client Registration CLI. -
Toggle the Standard Flow Enabled setting it to Off.
-
Strengthen the security by configuring the client
Access Type
asConfidential
and selecting Credentials > ClientId and Secret.You can configure either
Client Id and Secret
orSigned JWT
under the Credentials tab . -
Enable service accounts if you want to use a service account associated with the client by selecting a client to edit in the Clients section of the
Admin Console
.-
Under Settings, change the Access Type to Confidential, toggle the Service Accounts Enabled setting to On, and click Save.
-
Click Service Account Roles and select desired roles to configure the access for the service account. For the details on what roles to select, see Configuring a new regular user for use with Client Registration CLI.
-
-
Toggle the Direct Access Grants Enabled setting it to On if you want to use a regular user account instead of a service account.
-
If the client is configured as
Confidential
, provide the configured secret when runningkcreg config credentials
by using the--secret
option. -
Specify which
clientId
to use (for example,--client reg-cli
) when runningkcreg config credentials
. -
With the service account enabled, you can omit specifying the user when running
kcreg config credentials
and only provide the client secret or keystore information.
6.3. Installing the Client Registration CLI
The Client Registration CLI is packaged inside the Keycloak Server distribution. You can find execution scripts inside the bin
directory. The Linux script is called kcreg.sh
, and the Windows script is called kcreg.bat
.
Add the Keycloak server directory to your PATH
when setting up the client for use from any location on the file system.
For example, on:
-
Linux:
$ export PATH=$PATH:$KEYCLOAK_HOME/bin $ kcreg.sh
-
Windows:
c:\> set PATH=%PATH%;%KEYCLOAK_HOME%\bin c:\> kcreg
KEYCLOAK_HOME
refers to a directory where the Keycloak Server distribution was unpacked.
6.4. Using the Client Registration CLI
-
Start an authenticated session by logging in with your credentials.
-
Run commands on the
Client Registration REST
endpoint.For example, on:
-
Linux:
$ kcreg.sh config credentials --server http://localhost:8080 --realm demo --user user --client reg-cli $ kcreg.sh create -s clientId=my_client -s 'redirectUris=["http://localhost:8980/myapp/*"]' $ kcreg.sh get my_client
-
Windows:
c:\> kcreg config credentials --server http://localhost:8080 --realm demo --user user --client reg-cli c:\> kcreg create -s clientId=my_client -s "redirectUris=[\"http://localhost:8980/myapp/*\"]" c:\> kcreg get my_client
In a production environment, Keycloak has to be accessed with
https:
to avoid exposing tokens to network sniffers.
-
-
If a server’s certificate is not issued by one of the trusted certificate authorities (CAs) that are included in Java’s default certificate truststore, prepare a
truststore.jks
file and instruct the Client Registration CLI to use it.For example, on:
-
Linux:
$ kcreg.sh config truststore --trustpass $PASSWORD ~/.keycloak/truststore.jks
-
Windows:
c:\> kcreg config truststore --trustpass %PASSWORD% %HOMEPATH%\.keycloak\truststore.jks
-
6.4.1. Logging in
-
Specify a server endpoint URL and a realm when you log in with the Client Registration CLI.
-
Specify a user name or a client id, which results in a special service account being used. When using a user name, you must use a password for the specified user. When using a client ID, you use a client secret or a
Signed JWT
instead of a password.
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:
-
Linux:
$ kcreg.sh help
-
Windows:
c:\> kcreg help
See kcreg config credentials --help
for more information about starting an authenticated session.
6.4.2. Working with alternative configurations
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.
Do not make the configuration file visible to other users on the system. The configuration file contains access tokens and secrets that should be kept private. |
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.
6.4.3. Initial Access and Registration Access Tokens
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:
-
Linux:
$ kcreg.sh config initial-token $TOKEN $ kcreg.sh create -s clientId=myclient
or
$ kcreg.sh create -s clientId=myclient -t $TOKEN
-
Windows:
c:\> kcreg config initial-token %TOKEN% c:\> kcreg create -s clientId=myclient
or
c:\> kcreg create -s clientId=myclient -t %TOKEN%
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.
6.4.4. Creating a client configuration
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.
-
Linux:
$ kcreg.sh create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s 'redirectUris=["/myclient/*"]' -o
-
Windows:
C:\> kcreg create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s "redirectUris=[\"/myclient/*\"]" -o
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.
6.4.5. Retrieving a client configuration
You can retrieve an existing client by using the kcreg get
command.
For example, on:
-
Linux:
$ kcreg.sh get myclient
-
Windows:
C:\> kcreg get myclient
You can also retrieve the client configuration as an adapter configuration file, which you can package with your web application.
For example, on:
-
Linux:
$ kcreg.sh get myclient -e install > keycloak.json
-
Windows:
C:\> kcreg get myclient -e install > keycloak.json
Run the kcreg get --help
command for more information about the kcreg get
command.
6.4.6. Modifying a client configuration
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:
-
Linux:
$ kcreg.sh get myclient > myclient.json $ vi myclient.json $ kcreg.sh update myclient -f myclient.json
-
Windows:
C:\> kcreg get myclient > myclient.json C:\> notepad myclient.json C:\> kcreg update myclient -f myclient.json
The second method fetches the current client, sets or deletes fields on it, and posts it back in one step.
For example, on:
-
Linux:
$ kcreg.sh update myclient -s enabled=false -d redirectUris
-
Windows:
C:\> kcreg update myclient -s enabled=false -d redirectUris
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:
-
Linux:
$ kcreg.sh update myclient --merge -d redirectUris -f mychanges.json
-
Windows:
C:\> kcreg update myclient --merge -d redirectUris -f mychanges.json
Run the kcreg update --help
command for more information about the kcreg update
command.
6.4.7. Deleting a client configuration
Use the following example to delete a client.
-
Linux:
$ kcreg.sh delete myclient
-
Windows:
C:\> kcreg delete myclient
Run the kcreg delete --help
command for more information about the kcreg delete
command.
6.4.8. Refreshing invalid Registration Access Tokens
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.
7. Using token exchange
Token Exchange is Technology Preview and is not fully supported. This feature is disabled by default. To enable start the server with |
To use more than the Internal Token to Internal Token Exchange flow, also enable the |
7.1. How token exchange works
In Keycloak, token exchange is the process of using a set of credentials or token to obtain an entirely different token. A client may want to invoke on a less trusted application so it may want to downgrade the current token it has. A client may want to exchange a Keycloak token for a token stored for a linked social provider account. You may want to trust external tokens minted by other Keycloak realms or foreign IDPs. A client may have a need to impersonate a user. Here’s a short summary of the current capabilities of Keycloak around token exchange.
-
A client can exchange an existing Keycloak token created for a specific client for a new token targeted to a different client
-
A client can exchange an existing Keycloak token for an external token, i.e. a linked Facebook account
-
A client can exchange an external token for a Keycloak token.
-
A client can impersonate a user
Token exchange in Keycloak is a very loose implementation of the OAuth Token Exchange specification at the IETF. We have extended it a little, ignored some of it, and loosely interpreted other parts of the specification. It is a simple grant type invocation on a realm’s OpenID Connect token endpoint.
/realms/{realm}/protocol/openid-connect/token
It accepts form parameters (application/x-www-form-urlencoded
) as input and the output depends on the type of token you requested an exchange for.
Token exchange is a client endpoint so requests must provide authentication information for the calling client.
Public clients specify their client identifier as a form parameter. Confidential clients can also use form parameters
to pass their client id and secret, Basic Auth, or however your admin has configured the client authentication flow in your
realm.
7.1.1. Form parameters
- client_id
-
REQUIRED MAYBE. This parameter is required for clients using form parameters for authentication. If you are using Basic Auth, a client JWT token, or client cert authentication, then do not specify this parameter.
- client_secret
-
REQUIRED MAYBE. This parameter is required for clients using form parameters for authentication and using a client secret as a credential. Do not specify this parameter if client invocations in your realm are authenticated by a different means.
- grant_type
-
REQUIRED. The value of the parameter must be
urn:ietf:params:oauth:grant-type:token-exchange
. - subject_token
-
OPTIONAL. A security token that represents the identity of the party on behalf of whom the request is being made. It is required if you are exchanging an existing token for a new one.
- subject_issuer
-
OPTIONAL. Identifies the issuer of the
subject_token
. It can be left blank if the token comes from the current realm or if the issuer can be determined from thesubject_token_type
. Otherwise it is required to be specified. Valid values are the alias of anIdentity Provider
configured for your realm. Or an issuer claim identifier configured by a specificIdentity Provider
. - subject_token_type
-
OPTIONAL. This parameter is the type of the token passed with the
subject_token
parameter. This defaults tourn:ietf:params:oauth:token-type:access_token
if thesubject_token
comes from the realm and is an access token. If it is an external token, this parameter may or may not have to be specified depending on the requirements of thesubject_issuer
. - requested_token_type
-
OPTIONAL. This parameter represents the type of token the client wants to exchange for. Currently only oauth and OpenID Connect token types are supported. The default value for this depends on whether it is
urn:ietf:params:oauth:token-type:refresh_token
in which case you will be returned both an access token and refresh token within the response. Other appropriate values areurn:ietf:params:oauth:token-type:access_token
andurn:ietf:params:oauth:token-type:id_token
- audience
-
OPTIONAL. This parameter specifies the target client you want the new token minted for.
- requested_issuer
-
OPTIONAL. This parameter specifies that the client wants a token minted by an external provider. It must be the alias of an
Identity Provider
configured within the realm. - requested_subject
-
OPTIONAL. This specifies a username or user id if your client wants to impersonate a different user.
- scope
-
NOT IMPLEMENTED. This parameter represents the target set of OAuth and OpenID Connect scopes the client is requesting. It is not implemented at this time but will be once Keycloak has better support for scopes in general.
We currently only support OpenID Connect and OAuth exchanges. Support for SAML based clients and identity providers may be added in the future depending on user demand. |
7.1.2. Responses from a token exchange request
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.
{
"access_token" : ".....",
"refresh_token" : ".....",
"expires_in" : "...."
}
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:
{
"error" : "...."
"error_description" : "...."
}
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.
Token exchange setup requires knowledge of fine grain admin permissions (See the Server Administration Guide for more information). You will need to grant clients permission to exchange. This is discussed more later in this chapter. |
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.
7.2. Internal token to internal token exchange
With an internal token to token exchange you have an existing token minted to a specific client and you want to exchange this token for a new one minted for a different target client. Why would you want to do this? This generally happens when a client has a token minted for itself, and needs to make additional requests to other applications that require different claims and permissions within the access token. Other reasons this type of exchange might be required is if you need to perform a "permission downgrade" where your app needs to invoke on a less trusted app and you don’t want to propagate your current access token.
7.2.1. Granting permission for the exchange
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.
-
Toggle Permissions Enabled to On.
Target Client PermissionThat page displays a token-exchange link.
-
Click that link to start defining the permission.
This setup page displays.
Target Client Exchange Permission Setup -
Click Client details in the breadcrumbs at the top of the screen.
-
Define a policy for this permission.
-
Click Authorization in the breadcrumbs at the top of the screen.
-
Define a policy for this permission.
-
Click the Policies tab.
-
Create a Client Policy by clicking Create policy button.
Client Policy Creation -
Enter in the starting client that is the authenticated client that is requesting a token exchange.
-
After you create this policy, go back to the target client’s token-exchange permission and add the client policy you just defined.
Apply Client Policy
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.
7.2.2. Making the request
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.
curl -X POST \
-d "client_id=starting-client" \
-d "client_secret=the client secret" \
--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
-d "subject_token=...." \
--data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:refresh_token" \
-d "audience=target-client" \
http://localhost:8080/realms/myrealm/protocol/openid-connect/token
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.
{
"access_token" : "....",
"refresh_token" : "....",
"expires_in" : 3600
}
7.3. Internal token to external token exchange
You can exchange a realm token for an external token minted by an external identity provider. This external identity provider
must be configured within the Identity Provider
section of the Admin Console. Currently only OAuth/OpenID Connect based external
identity providers are supported, this includes all social providers. Keycloak does not perform a backchannel exchange to the external provider. So if the account
is not linked, you will not be able to get the external token. To be able to obtain an external token one of
these conditions must be met:
-
The user must have logged in with the external identity provider at least once
-
The user must have linked with the external identity provider through the User Account Service
-
The user account was linked through the external identity provider using Client Initiated Account Linking API.
Finally, the external identity provider must have been configured to store tokens, or, one of the above actions must have been performed with the same user session as the internal token you are exchanging.
If the account is not linked, the exchange response will contain a link you can use to establish it. This is discussed more in the Making the Request section.
7.3.1. Granting permission for 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.
-
Toggle Permissions Enabled to On.
Identity Provider PermissionThe page displays token-exchange link.
-
Click the link to start defining the permission.
This setup page appears.
Identity Provider Exchange Permission Setup -
Click Client details in the breadcrumbs at the top of the screen.
-
Click Policies tab to create a client policy.
Client Policy Creation -
Enter the starting client that is the authenticated client that is requesting a token exchange.
-
Return to the identity provider’s token-exchange permission and add the client policy you just defined.
Apply Client Policy
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.
7.3.2. Making the request
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.
curl -X POST \
-d "client_id=starting-client" \
-d "client_secret=the client secret" \
--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
-d "subject_token=...." \
--data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
-d "requested_issuer=google" \
http://localhost:8080/realms/myrealm/protocol/openid-connect/token
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.
{
"access_token" : "....",
"expires_in" : 3600
"account-link-url" : "https://...."
}
If the external identity provider is not linked for whatever reason, you will get an HTTP 400 response code with this JSON document:
{
"error" : "....",
"error_description" : "..."
"account-link-url" : "https://...."
}
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.
7.4. External token to internal token exchange
You can trust and exchange external tokens minted by external identity providers for internal tokens. This can be used to bridge between realms or just to trust tokens from your social provider. It works similarly to an identity provider browser login in that a new user is imported into your realm if it doesn’t exist.
The current limitation on external token exchanges is that if the external token maps to an existing user an exchange will not be allowed unless the existing user already has an account link to the external identity provider. |
When the exchange is complete, a user session will be created within the realm, and you will receive an access
and or refresh token depending on the requested_token_type
parameter value. You should note that this new
user session will remain active until it times out or until you call the logout endpoint of the realm passing this
new access token.
These types of changes required a configured identity provider in the Admin Console.
SAML identity providers are not supported at this time. Twitter tokens cannot be exchanged either. |
7.4.1. Granting permission for the exchange
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.
7.4.2. Making the request
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 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.
curl -X POST \
-d "client_id=starting-client" \
-d "client_secret=the client secret" \
--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
-d "subject_token=...." \
-d "subject_issuer=myOidcProvider" \
--data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
-d "audience=target-client" \
http://localhost:8080/realms/myrealm/protocol/openid-connect/token
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.
{
"access_token" : "....",
"refresh_token" : "....",
"expires_in" : 3600
}
7.5. Impersonation
For internal and external token exchanges, the client can request on behalf of a user to impersonate a different user. For example, you may have an admin application that needs to impersonate a user so that a support engineer can debug a problem.
7.5.1. Granting permission for the exchange
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.
7.5.2. Making the request
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.
curl -X POST \
-d "client_id=starting-client" \
-d "client_secret=the client secret" \
--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
-d "subject_token=...." \
--data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
-d "audience=target-client" \
-d "requested_subject=wburke" \
http://localhost:8080/realms/myrealm/protocol/openid-connect/token
7.6. Direct Naked Impersonation
You can make an internal token exchange request without providing a subject_token
. This is called a direct
naked impersonation because it places a lot of trust in a client as that client can impersonate any user in the realm.
You might need this to bridge for applications where it is impossible to obtain a subject token to exchange. For example,
you may be integrating a legacy application that performs login directly with LDAP. In that case, the legacy app
is able to authenticate users itself, but not able to obtain a token.
It is very risky to enable direct naked impersonation for a client. If the client’s credentials are ever stolen, that client can impersonate any user in the system. |
7.6.1. Granting permission for the exchange
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.
-
Click Users in the menu.
-
Click the Permissions tab.
User Permissions -
Toggle Permissions Enabled to On.
Identity Provider PermissionThe page displays an impersonate link.
-
Click that link to start defining the permission.
This setup page displays.
Users Impersonation Permission Setup -
Click Client details in the breadcrumbs at the top of the screen.
-
Define a policy for this permission.
-
Go to the Policies tab and create a client policy.
Client Policy Creation -
Enter the starting client that is the authenticated client that is requesting a token exchange.
-
Return to the users' impersonation permission and add the client policy you just defined.
Apply Client Policy
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.
Public clients are not allowed to do direct naked impersonations. |
7.6.2. Making the request
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.
curl -X POST \
-d "client_id=starting-client" \
-d "client_secret=the client secret" \
--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
-d "requested_subject=wburke" \
http://localhost:8080/realms/myrealm/protocol/openid-connect/token
7.7. Expand permission model with service accounts
When granting clients permission to exchange, you don’t necessarily manually enable those permissions for each and every client.
If the client has a service account associated with it, you can use a role to group permissions together and assign exchange permissions
by assigning a role to the client’s service account. For example, you might define a naked-exchange
role and any service account that has that
role can do a naked exchange.
7.8. Exchange vulnerabilities
When you start allowing token exchanges, there are various things you have to both be aware of and careful of.
The first is public clients. Public clients do not have or require a client credential in order to perform an exchange. Anybody that has a valid token will be able to impersonate the public client and perform the exchanges that public client is allowed to perform. If there are any untrustworthy clients that are managed by your realm, public clients may open up vulnerabilities in your permission models. This is why direct naked exchanges do not allow public clients and will abort with an error if the calling client is public.
It is possible to exchange social tokens provided by Facebook, Google, etc. for a realm token. Be careful and vigilante on what the exchange token is allowed to do as it’s not hard to create fake accounts on these social websites. Use default roles, groups, and identity provider mappers to control what attributes and roles are assigned to the external social user.
Direct naked exchanges are quite dangerous. You are putting a lot of trust in the calling client that it will never leak out its client credentials. If those credentials are leaked, then the thief can impersonate anybody in your system. This is in direct contrast to confidential clients that have existing tokens. You have two factors of authentication, the access token and the client credentials, and you’re only dealing with one user. So use direct naked exchanges sparingly.