libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases 1 Packages Activity Actions

Update documentation after adapters removal

Browse source 
closes #28792

Signed-off-by: mposolda <mposolda@gmail.com>
This commit is contained in:
mposolda 2024-05-20 13:05:32 +02:00 committed by Alexander Schwartz
parent 7a0eec5e19
commit bbd4b60163
20 changed files with 26 additions and 719 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
docs/documentation/release_notes/topics/25_0_0.adoc
View file

@ -2,6 +2,19 @@
The Account Console v2 theme has been removed from {project_name}. This theme was deprecated in {project_name} 24 and replaced by the Account Console v3 theme. If you are still using this theme, you should migrate to the Account Console v3 theme. The Account Console v2 theme has been removed from {project_name}. This theme was deprecated in {project_name} 24 and replaced by the Account Console v3 theme. If you are still using this theme, you should migrate to the Account Console v3 theme.
= Most of Java adapters removed
As stated in the release notes of previous {project_name} version, the most of Java adapters are now removed from the {project_name} codebase and downloads pages.
For OAuth 2.0/OIDC, this includes removal of the Tomcat adapter, WildFly/EAP adapter, Servlet Filter adapter, `KeycloakInstalled` desktop adapter, the `jaxrs-oauth-client` adapter, JAAS login modules, Spring adapter and SpringBoot adapters.
You can check https://www.keycloak.org/2023/03/adapter-deprecation-update.html[our older post] for the list of some alternatives.
For SAML, this includes removal of the Tomcat adapter and Servlet filter adapter. SAML adapters are still supported with WildFly and JBoss EAP.
The generic Authorization Client library is still supported, and we still plan to support it. It aims to be used in combination with any other OAuth 2.0 or OpenID Connect libraries. You can
check the https://github.com/keycloak/keycloak-quickstarts[quickstarts] for some examples where this authorization client library is used together with the 3rd party Java adapters like
Elytron OIDC or SpringBoot. You can check the quickstarts also for the example of SAML adapter used with WildFly.
= Upgrade to PatternFly 5 = Upgrade to PatternFly 5
In {project_name} 24, the Welcome page is updated to use https://www.patternfly.org/[PatternFly 5], the latest version of the design system that underpins the user interface of {project_name}. In this release, the Admin Console and Account Console are also updated to use PatternFly 5. If you want to extend and customize the Admin Console and Account Console, review https://www.patternfly.org/get-started/upgrade/[the changes in PatternFly 5] and update your customizations accordingly. In {project_name} 24, the Welcome page is updated to use https://www.patternfly.org/[PatternFly 5], the latest version of the design system that underpins the user interface of {project_name}. In this release, the Admin Console and Account Console are also updated to use PatternFly 5. If you want to extend and customize the Admin Console and Account Console, review https://www.patternfly.org/get-started/upgrade/[the changes in PatternFly 5] and update your customizations accordingly.
@ -10,8 +23,8 @@ In {project_name} 24, the Welcome page is updated to use https://www.patternfly.
Argon2 is now the default password hashing algorithm used by {project_name} in a non-FIPS environment. Argon2 is now the default password hashing algorithm used by {project_name} in a non-FIPS environment.
Argon2 was the winner of the [2015 password hashing competition](https://en.wikipedia.org/wiki/Password_Hashing_Competition) Argon2 was the winner of the https://en.wikipedia.org/wiki/Password_Hashing_Competition[2015 password hashing competition]
and is the recommended hashing algorithm by [OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#argon2id). and is the recommended hashing algorithm by https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#argon2id[OWASP].
In {project_name} 24 the default hashing iterations for PBKDF2 were increased from 27.5K to 210K, resulting in a more than In {project_name} 24 the default hashing iterations for PBKDF2 were increased from 27.5K to 210K, resulting in a more than
10 times increase in the amount of CPU time required to generate a password hash. With Argon2 it is possible to achieve 10 times increase in the amount of CPU time required to generate a password hash. With Argon2 it is possible to achieve

20
docs/documentation/securing_apps/topics/oidc/java/adapter-context.adoc
View file

@ -1,20 +0,0 @@
==== 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 {project_name}.
In servlet environments it is available in secured invocations as an attribute in HttpServletRequest:
[source,java]
----
httpServletRequest
.getAttribute(KeycloakSecurityContext.class.getName());
----
Or, it is available in insecured requests in the HttpSession:
[source,java]
----
httpServletRequest.getSession()
.getAttribute(KeycloakSecurityContext.class.getName());
----

5
docs/documentation/securing_apps/topics/oidc/java/adapter-deprecation-notice.adoc
View file

@ -1,5 +0,0 @@
[WARNING]
====
This adapter is deprecated and will be removed in a future release of {project_name}. No further enhancements or new features
will be added to this adapter.
====

35
docs/documentation/securing_apps/topics/oidc/java/adapter_error_handling.adoc
View file

@ -1,35 +0,0 @@
[[_adapter_error_handling]]
==== Error handling
{project_name} has some error handling facilities for servlet based client adapters.
When an error is encountered in authentication, {project_name} will call `HttpServletResponse.sendError()`.
You can set up an error-page within your `web.xml` file to handle the error however you want.
{project_name} can throw 400, 401, 403, and 500 errors.
[source,xml]
----
<error-page>
<error-code>403</error-code>
<location>/ErrorHandler</location>
</error-page>
----
{project_name} 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:
[source,java]
----
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());
----

117
docs/documentation/securing_apps/topics/oidc/java/application-clustering.adoc
View file

@ -1,117 +0,0 @@
[[_applicationclustering]]
==== Application clustering
ifeval::[{project_community}==true]
This chapter is related to supporting clustered applications deployed to JBoss EAP, WildFly and JBoss AS.
endif::[]
ifeval::[{project_product}==true]
This chapter is related to supporting clustered applications deployed to JBoss EAP.
endif::[]
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 {project_name}
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 {project_name}, so it's not as simple as enabling sticky sessions on your load balancer.
===== Stateless token store
By default, the web application secured by {project_name} 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:
[source,json]
----
"token-store": "cookie"
----
NOTE: 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 {project_name} to applications using cookie store. Hence it's recommended to use a short value for the access token timeout (for example 1 minute).
NOTE: 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 {project_name} 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 {project_name}.
For example if the URL to your application is `$$https://acme.org/myapp$$` and the URL to {project_name} is `\https://acme.org{kc_base_path}`, 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 {project_name} Admin Console.
It's used by the {project_name} 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 {project_name}
. The {project_name} server invalidates the user session
. The {project_name} 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_app_nodes]]
===== Registration of application nodes
The previous section describes how {project_name} 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 {project_name} 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 {project_name} server
. The request may be re-sent to {project_name} in configured periodic intervals
. If the {project_name} 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 {project_name} 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:
[source,json]
----
"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 {project_name} 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_each_req]]
===== 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 {project_name} server.
To enable the feature edit the `WEB-INF/keycloak.json` file for your application and add:
[source,json]
----
"always-refresh-token": true
----
NOTE: 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.

78
docs/documentation/securing_apps/topics/oidc/java/client-authentication.adoc
View file

@ -1,78 +0,0 @@
[[_client_authentication_adapter]]
==== 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 {project_name} 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 {project_name} server.
You can generate the secret for a particular client in the {project_name} Admin Console, and then paste this secret into the `keycloak.json` file on the application side:
[source,json]
----
"credentials": {
"secret": "19666a4f-32dd-4049-b082-684c74115f28"
}
----
===== Client authentication with Signed JWT
This is based on the https://datatracker.ietf.org/doc/html/rfc7523[RFC7523] specification. It works this way:
* The client must have the private key and certificate. For {project_name} 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 https://datatracker.ietf.org/doc/html/rfc7517[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 {project_name} (see below).
* During authentication, the client generates a JWT token and signs it with its private key and sends it to {project_name} in
the particular backchannel request (for example, code-to-token request) in the `client_assertion` parameter.
* {project_name} must have the public key or certificate of the client so that it can verify the signature on JWT. In {project_name} 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 tab `Credentials` in the Admin Console.
Then you can choose to either in the tab `Keys`:
** Configure the JWKS URL where {project_name} 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 {project_name} then always downloads new keys when needed without needing to change the configuration. More accurately, {project_name} 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 {project_name} Admin Console if you don't have your own available.
For more details on how to set up the {project_name} Admin Console, see the {adminguide_link}[{adminguide_name}].
For set up on the adapter side you need to have something like this in your `keycloak.json` file:
[source,json]
----
"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.
===== 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 {project_name} 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:
[source,json]
----
"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 https://datatracker.ietf.org/doc/html/rfc7518#section-3.2[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 link:{developerguide_link}[{developerguide_name}].

286
docs/documentation/securing_apps/topics/oidc/java/java-adapter-config.adoc
View file

@ -1,286 +0,0 @@
[[_java_adapter_config]]
==== Configuration
Each Java adapter supported by {project_name} can be configured by a simple JSON file.
This is what one might look like:
[source,json,subs="attributes+"]
----
{
"realm" : "demo",
"resource" : "customer-portal",
"realm-public-key" : "MIGfMA0GCSqGSIb3D...31LwIDAQAB",
"auth-server-url" : "https://localhost:8443{kc_base_path}",
"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, 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 {project_name} and
it will always re-download it when needed (e.g. {project_name} rotates its keys). However if realm-public-key is set, then adapter
will never download new keys from {project_name}, so when {project_name} rotate its keys, adapter will break.
auth-server-url::
_REQUIRED._ 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{kc_base_path}`.
ssl-required::
_OPTIONAL_. Ensures that all communication to and from the {project_name} 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 {project_name} 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 {project_name}.
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 {project_name} 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.
{project_name} 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::
_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 URL `root/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 {project_name} 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 {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.
The default value is `false`.
allow-any-hostname::
_OPTIONAL_.
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 setting 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 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 {project_name} server's SSL keystore.
_REQUIRED_ unless `ssl-required` is `none` or `disable-trust-manager` is `true`.
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 {project_name} 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 {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::
_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 {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.
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 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 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 recognizes token with unknown `kid` . If it recognizes 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-support[Audience Support] for more details about audience

21
docs/documentation/securing_apps/topics/oidc/java/java-adapters.adoc
View file

@ -2,27 +2,8 @@
[WARNING] [WARNING]
==== ====
{project_name} 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. {project_name} Java Adapters were removed from {project_name} codebase and they are not supported anymore.
For more details about how to integrate {project_name} with Java applications, consider looking at the For more details about how to integrate {project_name} with Java applications, consider looking at the
{quickstartRepo_link}[Keycloak Quickstart GitHub Repository]. {quickstartRepo_link}[Keycloak Quickstart GitHub Repository].
==== ====
{project_name} 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_adapter_config,Java Adapters Config>> chapter.
ifeval::[{project_community}==true]
include::java-adapter-config.adoc[]
endif::[]
include::jboss-adapter.adoc[]
ifeval::[{project_community}==true]
include::adapter-context.adoc[]
include::adapter_error_handling.adoc[]
include::logout.adoc[]
include::params_forwarding.adoc[]
include::client-authentication.adoc[]
include::multi-tenancy.adoc[]
include::application-clustering.adoc[]
endif::[]

15
docs/documentation/securing_apps/topics/oidc/java/jboss-adapter.adoc
View file

@ -1,15 +0,0 @@
[[_jboss_adapter]]
==== JBoss EAP/WildFly adapter
{project_name} 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 {project_name} WildFly adapters, so you can expect a smooth migration of your applications
if you used this adapter with the older {project_name} 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 {project_name} adapters, but those
are not maintained and officially supported.
For more details on how to integrate {project_name} with JakartaEE applications running on latest Wildfly/EAP, take a look at the Jakarta EE quickstarts within the {quickstartRepo_link}[Keycloak Quickstart GitHub Repository].

20
docs/documentation/securing_apps/topics/oidc/java/logout.adoc
View file

@ -1,20 +0,0 @@
==== Logout
[[_java_adapter_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{kc_realms_path}/{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
https://openid.net/specs/openid-connect-rpinitiated-1_0.html[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 {project_name} 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 {project_name} 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 {project_name} server is performed if needed.

54
docs/documentation/securing_apps/topics/oidc/java/multi-tenancy.adoc
View file

@ -1,54 +0,0 @@
[[_multi_tenancy]]
==== Multi Tenancy
Multi Tenancy, in our context, means that a single target application (WAR) can be secured with multiple {project_name} realms. The realms can be located
on the same {project_name} 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.
{project_name} 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:
[source,java]
----
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`:
[source,xml]
----
<web-app>
...
<context-param>
<param-name>keycloak.config.resolver</param-name>
<param-value>example.PathBasedKeycloakConfigResolver</param-value>
</context-param>
</web-app>
----

46
docs/documentation/securing_apps/topics/oidc/java/params_forwarding.adoc
View file

@ -1,46 +0,0 @@
[[_params_forwarding]]
==== Parameters forwarding
The {project_name} initial authorization endpoint request has support for various parameters. Most of the parameters are described in
https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint[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 {project_name} authorization endpoint.
For example, if you request an offline token, then you can open the secured application URI with the `scope` parameter like:
[source]
----
http://myappserver/mysecuredapp?scope=offline_access
----
and the parameter `scope=offline_access` will be automatically forwarded to the {project_name} authorization endpoint.
The supported parameters are:
* scope - Use a space-delimited list of scopes. A space-delimited list typically references link:{adminguide_link}#_client_scopes[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 options `address phone`, then the request to {project_name} will contain the scope parameter `scope=openid address phone`.
* prompt - {project_name} supports these settings:
** `login` - SSO will be ignored and the {project_name} login page will always be shown, even if the user is already authenticated
** `consent` - Applicable only for the clients with `Consent 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 {project_name} to skip showing login page and automatically redirect to specified identity provider instead.
More info in the link:{adminguide_link}#_client_suggested_idp[Identity Provider documentation].
Most of the parameters are described in the https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint[OIDC specification].
The only exception is parameter `kc_idp_hint`, which is specific to {project_name} and contains the name of the identity provider to automatically use.
For more information see the `Identity Brokering` section in the link:{adminguide_link}[{adminguide_name}].
WARNING: If you open the URL using the attached parameters, the adapter will not redirect you to {project_name} if you are already authenticated
in the application. For example, opening $$http://myappserver/mysecuredapp?prompt=login$$ will not automatically redirect you to
the {project_name} login page if you are already authenticated to the application `mysecuredapp` . This behavior may be changed in the future.

8
docs/documentation/securing_apps/topics/oidc/javascript-adapter.adoc
View file

@ -386,11 +386,9 @@ Options is an optional Object, where:
* redirectUri - Specifies the uri to redirect to after login. * redirectUri - Specifies the uri to redirect to after login.
* prompt - This parameter allows to slightly customize the login flow on the {project_name} server side. * prompt - This parameter allows to slightly customize the login flow on the {project_name} server side.
For example, enforce displaying the login screen in case of value `login`. For example, enforce displaying the login screen in case of value `login`. Or enforce displaying of consent screen for the value `consent` in case that client has `Consent Required`.
ifeval::[{project_community}==true] Finally it is possible use the value `none` to make sure that login screen is not displayed to the user, which is useful just to check SSO for the case when user was already
See the link:{adapterguide_link}#_params_forwarding[Parameters Forwarding Section] authenticated before (This is related to the `onLoad` check with value `check-sso` described above).
for the details and all the possible values of the `prompt` parameter.
endif::[]
* 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. * 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. * 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. * scope - Override the scope configured in `init` with a different value for this specific login.

3
docs/documentation/securing_apps/topics/oidc/mod-auth-openidc.adoc
View file

@ -1,6 +1,9 @@
[[_mod_auth_openidc]] [[_mod_auth_openidc]]
=== mod_auth_openidc Apache HTTPD Module === mod_auth_openidc Apache HTTPD Module
WARNING: {project_name} does not provide any official support to mod_auth_openidc. The instructions below are best-effort and may not be up-to-date.
We recommend that you stick to official mod_auth_openidc documentation for more details.
The https://github.com/OpenIDC/mod_auth_openidc[mod_auth_openidc] is an Apache HTTP plugin for OpenID Connect. If your language/environment supports using Apache HTTPD The https://github.com/OpenIDC/mod_auth_openidc[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 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. is beyond the scope of this document. Please see the _mod_auth_openidc_ GitHub repo for more details on configuration.

1
docs/documentation/securing_apps/topics/overview/getting-started.adoc
View file

@ -13,7 +13,6 @@ ifeval::[{project_community}==true]
===== Java ===== Java
* {quickstartRepo_link}/tree/latest/jakarta/servlet-authz-client[Wildfly Elytron OIDC] * {quickstartRepo_link}/tree/latest/jakarta/servlet-authz-client[Wildfly Elytron OIDC]
* {quickstartRepo_link}/tree/latest/spring/rest-authz-resource-server[Spring Boot] * {quickstartRepo_link}/tree/latest/spring/rest-authz-resource-server[Spring Boot]
* <<_jboss_adapter, {project_name} Wildfly Adapter>> (Deprecated)
endif::[] endif::[]
===== JavaScript (client-side) ===== JavaScript (client-side)

2
docs/documentation/server_admin/topics/authentication/kerberos.adoc
View file

@ -62,7 +62,7 @@ Install a Kerberos client on your machine.
.Procedure .Procedure
. Install a Kerberos client. If your machine runs Fedora, Ubuntu, or RHEL, install the link:https://www.freeipa.org/page/Downloads[freeipa-client] package, containing a Kerberos client and other utilities. . Install a Kerberos client. If your machine runs Fedora, Ubuntu, or RHEL, install the link:https://www.freeipa.org/page/Downloads[freeipa-client] package, containing a Kerberos client and other utilities.
. Configure the Kerberos client (on Linux, the configuration settings are in the link:https://web.mit.edu/kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html[/etc/krb5.conf] file ). . Configure the Kerberos client (on Linux, the configuration settings are in the link:https://web.mit.edu/kerberos/krb5-1.21/doc/admin/conf_files/krb5_conf.html[/etc/krb5.conf] file ).
+ +
Add your Kerberos realm to the configuration and configure the HTTP domains your server runs on. Add your Kerberos realm to the configuration and configure the HTTP domains your server runs on.
+ +

10
docs/documentation/server_admin/topics/clients/oidc/con-advanced-settings.adoc
View file

@ -92,11 +92,6 @@ In the following cases, {project_name} will verify the client sending the access
See https://datatracker.ietf.org/doc/html/draft-ietf-oauth-mtls-08#section-3[Mutual TLS Client Certificate Bound Access Tokens] in the OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens for more details. See https://datatracker.ietf.org/doc/html/draft-ietf-oauth-mtls-08#section-3[Mutual TLS Client Certificate Bound Access Tokens] in the OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens for more details.
[NOTE]
====
Currently, {project_name} client adapters do not support holder-of-key token verification. {project_name} adapters treat access and refresh tokens as bearer tokens.
====
[[_dpop-bound-tokens]] [[_dpop-bound-tokens]]
*OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)* *OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)*
@ -125,11 +120,6 @@ In the following cases, {project_name} will verify the client sending the access
See https://datatracker.ietf.org/doc/html/rfc9449[OAuth 2.0 Demonstrating Proof of Possession (DPoP)] for more details. See https://datatracker.ietf.org/doc/html/rfc9449[OAuth 2.0 Demonstrating Proof of Possession (DPoP)] for more details.
[NOTE]
====
Currently, {project_name} client adapters do not support DPoP holder-of-key token verification. {project_name} adapters treat access and refresh tokens as bearer tokens.
====
:tech_feature_name: DPoP :tech_feature_name: DPoP
:tech_feature_id: dpop :tech_feature_id: dpop
include::../../templates/techpreview.adoc[] include::../../templates/techpreview.adoc[]

3
docs/documentation/server_admin/topics/clients/oidc/con-audience.adoc
View file

@ -49,7 +49,7 @@ Use this value to invoke the *<trusted service>*.
When setting up audience checking: When setting up audience checking:
* Ensure that services are configured to check audience on the access token sent to them by adding the flag *_verify-token-audience_* in the adapter configuration. See link:{adapterguide_link_latest}#_java_adapter_config[Adapter configuration] for details. * Ensure that services are configured to check audience on the access token sent to them. This may be done in a way specific to your client OIDC adapter, which you are using to secure your OIDC client application.
* Ensure that access tokens issued by {project_name} contain all necessary audiences. Audiences can be added using the client roles as described in the <<_audience_resolve, next section>> or hardcoded. See <<_audience_hardcoded, Hardcoded audience>>. * Ensure that access tokens issued by {project_name} contain all necessary audiences. Audiences can be added using the client roles as described in the <<_audience_resolve, next section>> or hardcoded. See <<_audience_hardcoded, Hardcoded audience>>.
@ -113,7 +113,6 @@ See <<_client_scopes_linking, Client Scopes Linking section>> for more details.
+ +
See: See:
+ +
** link:{adapterguide_link}#_params_forwarding[parameters forwarding section] if your application uses the servlet adapter.
** link:{adapterguide_link}#_javascript_adapter[javascript adapter section] if your application uses the javascript adapter. ** link:{adapterguide_link}#_javascript_adapter[javascript adapter section] if your application uses the javascript adapter.
NOTE: Both the _Audience_ and _Audience Resolve_ protocol mappers add the audiences to the access token only, by default. The ID Token typically contains only a single audience, the client ID for which the token was issued, a requirement of the OpenID Connect specification. However, the access token does not necessarily have the client ID, which was the token issued for, unless the audience mappers added it. NOTE: Both the _Audience_ and _Audience Resolve_ protocol mappers add the audiences to the access token only, by default. The ID Token typically contains only a single audience, the client ID for which the token was issued, a requirement of the OpenID Connect specification. However, the access token does not necessarily have the client ID, which was the token issued for, unless the audience mappers added it.

2
docs/documentation/server_admin/topics/clients/proc-evaluating-client-scopes.adoc
View file

@ -15,7 +15,7 @@ image:images/client-scopes-evaluate.png[]
[NOTE] [NOTE]
==== ====
To send a custom value for a *scope* parameter from your application, see the link:{adapterguide_link_latest}#_params_forwarding[parameters forwarding section], for servlet adapters or the link:{adapterguide_link_latest}#_javascript_adapter[javascript adapter section], for javascript adapters. To send a custom value for a *scope* parameter from your application, see the link:{adapterguide_link_latest}#_javascript_adapter[javascript adapter section], for javascript adapters.
==== ====
All examples are generated for the particular user and issued for the particular client, with the specified value of the *scope* parameter. The examples include all of the claims and role mappings used. All examples are generated for the particular user and issued for the particular client, with the specified value of the *scope* parameter. The examples include all of the claims and role mappings used.

2
docs/documentation/server_admin/topics/identity-broker/logout.adoc
View file

@ -1,4 +1,4 @@
=== Identity broker logout === Identity broker logout
When logging out, {project_name} sends a request to the external identity provider that is used to log in initially and logs the user out of this identity provider. You can skip this behavior and avoid logging out of the external identity provider. See link:{adapterguide_logout_link}[adapter logout documentation] for more information. When logging out, {project_name} sends a request to the external identity provider that is used to log in initially and logs the user out of this identity provider.