keycloak-scim/securing_apps/topics/oidc/java/java-adapter-config.adoc

[[_java_adapter_config]]
==== Java Adapter Config

Each Java adapter supported by {project_name} can be configured by a simple JSON file.
This is what one might look like:

[source,json]
----
{
  "realm" : "demo",
  "resource" : "customer-portal",
  "realm-public-key" : "MIGfMA0GCSqGSIb3D...31LwIDAQAB",
  "auth-server-url" : "https://localhost:8443/auth",
  "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/{project_name}`.
Replacement of environment variables is also supported via the `env` prefix, e.g. `${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::
  Name of the realm.
  This is _REQUIRED._

resource::
  The client-id of the application. Each application has a client-id that is used to identify the application.
  This is _REQUIRED._

realm-public-key::
  PEM format of the realm public key. You can obtain this from the administration console.
  This is _OPTIONAL_ and it's not recommended to set it. If not set, the adapter will download this from {project_name} and
  it will always re-download it when needed (eg. {project_name} rotate it's keys). However if realm-public-key is set, then adapter
  will never download new keys from {project_name}, so when {project_name} rotate it's keys, adapter will break.

auth-server-url::
  The base URL of the {project_name} server. All other {project_name} pages and REST service endpoints 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 {project_name} server is over HTTPS.
  In production this should be set to `all`.
  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'.

confidential-port::
  The confidential port used by the {project_name} server for secure connections over SSL/TLS.
  This is _OPTIONAL_.
  The default value is _8443_.

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 {project_name}.
  This is _OPTIONAL_.
  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.

cors-exposed-headers::
  If CORS is enabled, this sets the value of the `Access-Control-Expose-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 should be set to _true_ for services. If enabled the adapter will not attempt to authenticate users, but only verify bearer tokens.
  This is _OPTIONAL_.
  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 (e.g. 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 like `X-Requested-With`, `SOAPAction` or `Accept`.
  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 password and jwt is supported. This is _REQUIRED_ only for clients with 'Confidential' access type.

connection-pool-size::
  This config option defines how many connections to the {project_name} server should be pooled.
  This is _OPTIONAL_.
  The default value is `20`.

socket-timeout-millis::
  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_.

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`.
  This is _OPTIONAL_.

connection-ttl-millis::
  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_.

disable-trust-manager::
  If the {project_name} 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 is `false`.

allow-any-hostname::
  If the {project_name} server requires HTTPS and this config option is set to `true` the {project_name} 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 seting may be useful in test environments This is _OPTIONAL_.
  The default value is `false`.

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 {project_name} 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 {project_name} server's SSL keystore.
  This is _REQUIRED_ unless `ssl-required` is `none` or `disable-trust-manager` is `true`.

truststore-password::
  Password for the truststore.
  This is _REQUIRED_ if `truststore` is set and the truststore requires a password.

client-keystore::
  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 {project_name} server.
  This is _OPTIONAL_.

client-keystore-password::
  Password for the client keystore.
  This is _REQUIRED_ if `client-keystore` is set.

client-key-password::
  Password for the client's key.
  This is _REQUIRED_ if `client-keystore` is set.

always-refresh-token::
  If _true_, the adapter will refresh token in every request.
  Warning - when enabled this will result in a request to {project_name} for every request to your application.

register-node-at-startup::
  If _true_, then adapter will send registration request to {project_name}.
  It's _false_ by default and useful only when application is clustered.
  See <<_applicationclustering,Application Clustering>> for details

register-node-period::
  Period for re-registration adapter to {project_name}.
  Useful when application is clustered.
  See <<_applicationclustering,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 <<_applicationclustering,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 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.  Change this to true if you want to turn this off This is _OPTIONAL_.
  The default value is _false_.

token-minimum-time-to-live::
  Amount of time, in seconds, to preemptively refresh an active access token with the {project_name} 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.
  This is _OPTIONAL_.  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 {project_name} 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 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 bad `kid` forcing adapter
  to send lots of requests to {project_name}.

public-key-cache-ttl::
  Amount of time, in seconds, specifying maximum interval between two requests to {project_name} 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 unknown `kid` . If it recognize token with known `kid`, 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 the `kid` of token is already known.

ignore-oauth-query-parameter::
  Defaults to `false`, if set to `true` will turn off processing of the `access_token`
  query parameter for bearer token processing.  Users will not be able to authenticate
  if they only pass in an `access_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 to `false` by default, however for improved security, it is recommended to enable this.
  See link:{adminguide_link}#_audience[Audience Support] for more details about audience support.