General Adapter Config
Each adapter supported by Keycloak can be configured by a simple JSON text file. This is what one might
look like:
Some of these configuration switches may be adapter specific and some are common across all adapters.
For Java adapters you can use ${...} enclosure as System property replacement.
For example ${jboss.server.config.dir}. Also, you can obtain a template
for this config file from the admin console. Go to the realm and select the application you want a template for.
Go to the Installation tab and this will provide you with a template that includes
the public key of the realm.
Here is a description of each item:
realm
Name of the realm representing the users of your distributed applications and services.
This is
REQUIRED.resource
Username of the application. Each application has a username that is used when the
application connects with the Keycloak server to turn an access code into an access token
(part of the OAuth 2.0 protocol). This is
REQUIRED.realm-public-key
PEM format of public key. You can obtain this from the administration console.
This is
REQUIRED.auth-server-url
The base URL of the Keycloak Server. All other Keycloak pages and REST services are derived
from this. It is usually of the form https://host:port/auth
This is
REQUIRED.ssl-required
Ensures that all communication to and from the Keycloak server from the adapter is over HTTPS.
This is OPTIONAL. The default value is
external
meaning that HTTPS is required by default for external requests. Valid values are 'all', 'external'
and 'none'.
use-resource-role-mappings
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.
This is OPTIONAL. The default value is false.
public-client
If set to true, the adapter will not send credentials for the client to Keycloak.
The default value is false.
enable-cors
This enables CORS support. It will handle CORS preflight requests. It will also look into
the access token to determine valid origins.
This is OPTIONAL. The default value is false.
cors-max-age
If CORS is enabled, this sets the value of the
Access-Control-Max-Age
header.
This is OPTIONAL. If not set, this header is not returned in CORS
responses.
cors-allowed-methods
If CORS is enabled, this sets the value of the
Access-Control-Allow-Methods
header. This should be a comma-separated string.
This is OPTIONAL. If not set, this header is not returned in CORS
responses.
cors-allowed-headers
If CORS is enabled, this sets the value of the
Access-Control-Allow-Headers
header. This should be a comma-separated string.
This is OPTIONAL. If not set, this header is not returned in CORS
responses.
bearer-only
This tells the adapter to only do bearer token authentication. That is, it will not do
OAuth 2.0 redirects, but only accept bearer tokens through the
Authorization
header.
This is OPTIONAL. The default value is false.
enable-basic-auth
This tells the adapter to also support basic authentication. If this option is enabled,
then secret must also be provided.
This is OPTIONAL. The default value is false.
expose-token
If true, an authenticated browser client (via a Javascript HTTP invocation)
can obtain the signed access token via the URL root/k_query_bearer_token.
This is OPTIONAL. The default value is false.
credentials
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 only
password
is supported.
This is REQUIRED.
connection-pool-size
Adapters will make separate HTTP invocations to the Keycloak Server to turn an access code
into an access token. This config option defines how many connections to the Keycloak Server
should be pooled.
This is OPTIONAL. The default value is 20.
disable-trust-manager
If the Keycloak Server requires HTTPS and this config option is set to true
you do not have to specify a truststore. While convenient, this setting is not recommended
as you will not be verifying the host name of the Keycloak Server.
This is OPTIONAL. The default value is false.
allow-any-hostname
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 is not a recommended. This seting may be useful in test environments
This is OPTIONAL. The default value is false.
truststore
This setting is for Java adapters. The value is the file path to a Java keystore 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 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.
This is
OPTIONAL
if
ssl-required
is
none
or
disable-trust-manager
is true.
truststore-password
Password for the truststore keystore.
This is
REQUIRED
if
truststore
is set.
client-keystoreNot supported yet, but we will support in future versions.
This setting is for Java adapters. This is the file path to a Java keystore file.
This keystore contains client certificate for two-way SSL when the adapter makes
HTTPS requests to the Keycloak server.
This is OPTIONAL.
client-keystore-passwordNot supported yet, but we will support in future versions.
Password for the client keystore.
This is
REQUIRED
if
client-keystore
is set.
client-key-passwordNot supported yet, but we will support in future versions.
Password for the client's key.
This is
REQUIRED
if
client-keystore
is set.
auth-server-url-for-backend-requests
Alternative location of auth-server-url used just for backend requests. It must be absolute URI. Useful
especially in cluster (see Relative URI Optimization) or if you would like to use https for browser requests
but stick with http for backend requests etc.
always-refresh-token
If true, Keycloak will refresh token in every request. More info in Refresh token in each request .
register-node-at-startup
If true, then adapter will send registration request to Keycloak. It's false
by default and useful just in cluster (See Registration of application nodes to Keycloak)
register-node-period
Period for re-registration adapter to Keycloak. Useful in cluster. See Registration of application nodes to Keycloak 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 Stateless token store for details.
principal-attribute
OpenID Connection ID Token attribute to populate the UserPrincipal name with. If token attribute is null, defaults to sub.
Possible values are sub, preferred_username, email, name, nickname, given_name, family_name.
turn-off-change-session-id-on-login
The session id is changed by default on a successful login on some platforms to plug a security attack vector (Tomcat 8, Jetty9, Undertow/Wildfly). Change this to true if you want to turn this off
This is OPTIONAL. The default value is false.