1. Java adapters
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.
1.1. Java adapter 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}
.
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 (eg. Keycloak rotates its keys). However if realm-public-key is set, then adapter
will never download new keys from Keycloak, so when Keycloak rotate it’s 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 toall
.- 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 theAccess-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 theAccess-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 theAccess-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 theAccess-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 HTTP401
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.
Iftrue
, 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 is20
.- 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
.- onnection-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 totrue
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 totrue
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 withclasspath:
, 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 trustore 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 iftruststore
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 tosub
.
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 is0
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 recognize token with unknownkid
. 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 recognize token with unknownkid
. If it recognize 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
1.2. JBoss EAP/WildFly adapter
To be able to secure WAR apps deployed on JBoss EAP, WildFly or JBoss AS, you must install and configure the
Keycloak adapter subsystem. You then have two options to secure your WARs.
You can provide an adapter config file in your WAR and change the auth-method to KEYCLOAK within web.xml.
Alternatively, you do not have to modify your WAR at all and you can secure it via the Keycloak adapter subsystem configuration in the configuration file, such as
standalone.xml
.
Both methods are described in this section.
Adapters are available as a separate archive depending on what server version you are using.
1.6. Spring Security adapter
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.
as a Spring bean (in Spring Boot environments using Spring Security adapter)
1.7. Java servlet filter 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.
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.
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.
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:
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.
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:
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:
or use interactive console, if your runtime allows for that:
If you need more control, for example, providing custom KeycloakConfigResolver
to implement multi tenancy, you can register the filter programmatically:
Please refer to Apache Felix HTTP Service for more info on programmatic registration.
1.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
.
1.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.
1.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 authentication with signed jwt
This is based on the RFC7523 specification. It works this way:
For set up on the adapter side you need to have something like this in your keycloak.json
file:
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.
1.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:
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.
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 logout 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:
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:
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 your not using the automatic unregistration feature.
1.1. Java adapter 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}.
2.7. JavaScript Adapter Reference
Methods
init(options)
Called to initialize the adapter.
Options is an Object, where:
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 valuelogin
. 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 – Used to forward the scope parameter to the Keycloak login endpoint. Use a space-delimited list of scopes. Those typically
reference Client scopes defined on particular client. Note that the scopeopenid
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
.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.action – If value is
register
then user is redirected to registration page, if the value isUPDATE_PASSWORD
then the user will 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 logout 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:
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 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:
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.