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

Addressing final review comments from Pedro (#1176)

Browse source
This commit is contained in:
andymunro 2021-12-22 05:28:04 -05:00 committed by GitHub
parent db81d66e24
commit d604e60c58
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
70 changed files with 770 additions and 628 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
securing_apps/topics.adoc
View file

@ -2,7 +2,8 @@ include::topics/overview/overview.adoc[]
include::topics/overview/what-are-client-adapters.adoc[]
include::topics/overview/supported-platforms.adoc[]
include::topics/overview/supported-protocols.adoc[]
include::topics/overview/terminology.adoc[]
include::topics/overview/basic-steps.adoc[]
include::topics/oidc/oidc-overview.adoc[]
include::topics/oidc/java/java-adapters.adoc[]

6
securing_apps/topics/client-registration.adoc
View file

@ -1,5 +1,5 @@
[[_client_registration]]
== Client Registration
== Using the client registration service
In order for an application or service to utilize {project_name} it has to register a client in {project_name}.
An admin can do this through the admin console (or admin REST endpoints), but clients can also register themselves through the {project_name} client
@ -22,7 +22,7 @@ The following sections will describe how to use the different providers.
To invoke the Client Registration Services you usually need a token. The token can be a bearer token, an initial access token or a registration access token.
There is an alternative to register new client without any token as well, but then you need to configure Client Registration Policies (see below).
==== Bearer Token
==== Bearer token
The bearer token can be issued on behalf of a user or a Service Account. The following permissions are required to invoke the endpoints (see link:{adminguide_link}[{adminguide_name}] for more details):
@ -90,7 +90,7 @@ It will also return a new registration access token.
To delete the Client Representation perform an HTTP DELETE request to:
`/auth/realms/<realm>/clients-registrations/default/<client id>`
=== {project_name} Adapter Configuration
=== {project_name} adapter configuration
The `installation` client registration provider can be used to retrieve the adapter configuration for a client.
In addition to token authentication you can also authenticate with client credentials using HTTP basic authentication.

12
securing_apps/topics/client-registration/client-registration-cli.adoc
View file

@ -1,5 +1,5 @@
[[_client_registration_cli]]
== Client Registration CLI
== Automating Client Registration with the CLI
The Client Registration CLI is a command-line interface (CLI) tool for application developers to configure new clients in a self-service manner when integrating with {project_name}. It is specifically designed to interact with {project_name} Client Registration REST endpoints.
@ -13,6 +13,8 @@ To allow a particular user to use `Client Registration CLI` the {project_name} a
[[_configuring_a_user_for_client_registration_cli]]
=== Configuring a new regular user for use with Client Registration CLI
.Procedure
. Log in to the Admin Console (for example, http://localhost:8080/auth/admin) as [command]`admin`.
. Select a realm to administer.
. If you want to use an existing user, select that user to edit; otherwise, create a new user.
@ -34,7 +36,9 @@ The Administrator can issue Initial Access Tokens from the Admin Console through
By default, the server recognizes the Client Registration CLI as the [filename]`admin-cli` client, which is configured automatically for every new realm. No additional client configuration is necessary when logging in with a user name.
. Create a new client (for example, [filename]`reg-cli`) if you want to use a separate client configuration for the Client Registration CLI.
.Procedure
. Create a client (for example, [filename]`reg-cli`) if you want to use a separate client configuration for the Client Registration CLI.
. Toggle the *Standard Flow Enabled* setting it to *Off*.
. Strengthen the security by configuring the client [filename]`Access Type` as [filename]`Confidential` and selecting *Credentials > ClientId and Secret*.
+
@ -79,6 +83,8 @@ c:\> kcreg
[[_using_client_registration_cli]]
=== Using the Client Registration CLI
.Procedure
. Start an authenticated session by logging in with your credentials.
. Run commands on the [filename]`Client Registration REST` endpoint.
+
@ -126,6 +132,8 @@ c:\> kcreg config truststore --trustpass %PASSWORD% %HOMEPATH%\.keycloak\trustst
[[_logging_in]]
==== Logging in
.Procedure
. Specify a server endpoint URL and a realm when you log in with the Client Registration CLI.
. Specify a user name or a client id, which results in a special service account being used. When using a user name, you must use a password for the specified user. When using a client ID, you use a client secret or a [filename]`Signed JWT` instead of a password.

10
securing_apps/topics/docker/docker-overview.adoc
View file

@ -1,5 +1,5 @@
== Docker Registry Configuration
== Configuring a Docker registry to use {project_name}
NOTE: Docker authentication is disabled by default. To enable see link:{installguide_profile_link}[{installguide_profile_name}].
@ -9,7 +9,7 @@ For more information on how to set up and configure a Docker registry, see the l
=== Docker Registry Configuration File Installation
=== Docker registry configuration file installation
For users with more advanced Docker registry configurations, it is generally recommended to provide your own registry configuration file. The {project_name} Docker provider supports this mechanism via the _Registry Config File_ Format Option. Choosing this option will generate output similar to the following:
@ -24,7 +24,7 @@ This output can then be copied into any existing registry config file. See the
WARNING: Don't forget to configure the `rootcertbundle` field with the location of the {project_name} realm's public key. The auth configuration will not work without this argument.
=== Docker Registry Environment Variable Override Installation
=== Docker registry environment variable override installation
Often times it is appropriate to use a simple environment variable override for develop or POC Docker registries. While this approach is usually not recommended for production use, it can be helpful when one requires quick-and-dirty way to stand up a registry. Simply use the _Variable Override_ Format Option from the client installation tab, and an output should appear like the one below:
@ -41,7 +41,9 @@ WARNING: This installation method is meant to be an easy way to get a docker reg
The zip file installation mechanism provides a quickstart for developers who want to understand how the {project_name} server can interact with the Docker registry. In order to configure:
1. From the desired realm, create a client configuration. At this point you won't have a Docker registry - the quickstart will take care of that part.
.Procedure
1. From the desired realm, create a client configuration. At this point you won't have a Docker registry - the quickstart will take care of that part.
2. Choose the "Docker Compose YAML" option from the installation tab and download the .zip file
3. Unzip the archive to the desired location, and open the directory.
4. Start the Docker registry with `docker-compose up`

2
securing_apps/topics/oidc/java/adapter_error_handling.adoc
View file

@ -1,6 +1,6 @@
[[_adapter_error_handling]]
==== 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()`.

16
securing_apps/topics/oidc/java/application-clustering.adoc
View file

@ -1,5 +1,5 @@
[[_applicationclustering]]
==== Application Clustering
==== Application clustering
ifeval::[{project_community}==true]
This chapter is related to supporting clustered applications deployed to JBoss EAP, WildFly and JBoss AS.
@ -30,7 +30,7 @@ To use the cookie store for saving the security context, edit your applications
[source,json]
----
"token-store": "cookie"
----
----
NOTE: The default value for `token-store` is `session`, which stores the security context in the HTTP session.
@ -54,7 +54,7 @@ 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} Administration Console.
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:
@ -75,7 +75,7 @@ However, in some cases admin may want to propagate admin tasks to all registered
For example to push a new not before policy to the application or to logout 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:
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
@ -95,8 +95,8 @@ To enable the feature edit the `WEB-INF/keycloak.json` file for your application
This means the adapter will send the registration request on startup and re-register every 10 minutes.
In the {project_name} Administration 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 Adminstration Console, which is useful if you don't want to rely
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 your not using the automatic unregistration feature.
[[_refresh_token_each_req]]
@ -110,8 +110,8 @@ To enable the feature edit the `WEB-INF/keycloak.json` file for your application
[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.
minutes of the logout.

20
securing_apps/topics/oidc/java/client-authentication.adoc
View file

@ -1,12 +1,12 @@
[[_client_authentication_adapter]]
==== Client Authentication
==== 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} administration console, and then paste this secret into the `keycloak.json` file on the application side:
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]
@ -16,7 +16,7 @@ You can generate the secret for a particular client in the {project_name} admini
}
----
===== Client Authentication with Signed JWT
===== Client authentication with Signed JWT
This is based on the https://datatracker.ietf.org/doc/html/rfc7523[RFC7523] specification. It works this way:
@ -27,12 +27,12 @@ This is based on the https://datatracker.ietf.org/doc/html/rfc7523[RFC7523] spec
* 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 administration console.
* {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} admininstration console if you don't have your own available.
For more details on how to set up the {project_name} administration console see {adminguide_link}[{adminguide_name}].
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:
@ -56,11 +56,11 @@ you can point to any file on the file system where the client application is run
ifeval::[{project_community}==true]
For inspiration, you can take a look at the examples distribution into the main demo example into the `product-portal` application.
===== Client Authentication with Signed JWT using Client Secret
===== 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 administration console, and then paste this secret into the `keycloak.json` file on the application side:
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]
----
@ -76,9 +76,7 @@ The "algorithm" field specifies the algorithm for Signed JWT using Client Secret
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
===== 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}].
endif::[]

8
securing_apps/topics/oidc/java/fuse-adapter.adoc
View file

@ -1,11 +1,11 @@
[[_fuse_adapter]]
==== JBoss Fuse 6 Adapter
==== JBoss Fuse 6 adapter
{project_name} supports securing your web applications running inside https://developers.redhat.com/products/fuse/overview[JBoss Fuse 6].
ifeval::[{project_community}==true]
JBoss Fuse 6 leverages <<_jetty9_adapter,Jetty 9 adapter>> as {fuseVersion} is bundled with http://www.eclipse.org/jetty/[Jetty 9.2 server]
JBoss Fuse 6 uses <<_jetty9_adapter,Jetty 9 adapter>> as {fuseVersion} is bundled with http://www.eclipse.org/jetty/[Jetty 9.2 server]
under the covers and Jetty is used for running various kinds of web applications.
endif::[]
@ -21,11 +21,11 @@ Security for the following items is supported for Fuse:
* SSH and JMX admin access
* https://hawt.io/[Hawtio administration console]
===== Securing Your Web Applications Inside Fuse 6
===== Securing your web applications inside Fuse 6
You must first install the {project_name} Karaf feature. Next you will need to perform the steps according to the type of application you want to secure.
All referenced web applications require injecting the {project_name} Jetty authenticator into the underlying Jetty server. The steps to achieve this depend on the application type. The details are described below.
ifeval::[{project_community}==true]
The best place to start is look at Fuse demo bundled as part of {project_name} examples in directory `fuse` . Most of the steps should be understandable from testing and understanding the demo.
The best place to start is look at Fuse demo bundled as part of {project_name} examples in directory `fuse`. Most of the steps should be understandable from testing and understanding the demo.
endif::[]

2
securing_apps/topics/oidc/java/fuse/camel.adoc
View file

@ -1,6 +1,6 @@
[[_fuse_adapter_camel]]
===== Securing an Apache Camel Application
===== Securing an Apache Camel application
You can secure Apache Camel endpoints implemented with the https://camel.apache.org/components/next/jetty-component.html[camel-jetty] component by adding the securityHandler with `KeycloakJettyAuthenticator` and the proper security constraints injected. You can add the `OSGI-INF/blueprint/blueprint.xml` file to your Camel application with a similar configuration as below. The roles, security constraint mappings, and {project_name} adapter configuration might differ slightly depending on your environment and needs.

4
securing_apps/topics/oidc/java/fuse/classic-war.adoc
View file

@ -1,8 +1,8 @@
[[_fuse_adapter_classic_war]]
===== Securing a Classic WAR Application
===== Securing a Classic WAR application
The needed steps to secure your WAR application are:
.Procedure
. In the `/WEB-INF/web.xml` file, declare the necessary:
* security constraints in the <security-constraint> element

2
securing_apps/topics/oidc/java/fuse/cxf-builtin.adoc
View file

@ -1,6 +1,6 @@
[[_fuse_adapter_cxf_builtin]]
===== Securing an Apache CXF Endpoint on the Default Jetty Engine
===== Securing an Apache CXF endpoint on the default Jetty Engine
Some services automatically come with deployed servlets on startup. One such service is the CXF servlet running in the $$http://localhost:8181/cxf$$ context. Securing such endpoints can be complicated. One approach, which {project_name} is currently using, is ServletReregistrationService, which undeploys a built-in servlet at startup, enabling you to redeploy it on a context secured by {project_name}.

6
securing_apps/topics/oidc/java/fuse/cxf-separate.adoc
View file

@ -1,8 +1,10 @@
[[_fuse_adapter_cxf_separate]]
===== Securing an Apache CXF Endpoint on a Separate Jetty Engine
===== Securing an Apache CXF endpoint on a separate Jetty engine
To run your CXF endpoints secured by {project_name} on separate Jetty engines, complete the following steps:
.Procedure
To run your CXF endpoints secured by {project_name} on separate Jetty engines, perform the following procedure.
. Add `META-INF/spring/beans.xml` to your application, and in it, declare `httpj:engine-factory` with Jetty SecurityHandler with injected `KeycloakJettyAuthenticator`. The configuration for a CFX JAX-WS application might resemble this one:
+

10
securing_apps/topics/oidc/java/fuse/fuse-admin.adoc
View file

@ -8,7 +8,9 @@
with {project_name}, protecting non-web administration services such as SSH with {project_name} credentials is a best pracrice. You can do this using the JAAS login module, which allows remote connection to {project_name} and verifies credentials based on
<<_resource_owner_password_credentials_flow,Resource Owner Password Credentials>>.
To enable SSH authentication, complete the following steps:
To enable SSH authentication, perform the following procedure.
.Procedure
. In {project_name} create a client (for example, `ssh-jmx-admin-client`), which will be used for SSH authentication.
This client needs to have `Direct Access Grants Enabled` selected to `On`.
@ -36,7 +38,7 @@ sshRealm=keycloak
----
This file specifies the client application configuration, which is used by JAAS DirectAccessGrantsLoginModule from the `keycloak` JAAS realm for SSH authentication.
. Start Fuse and install the `keycloak` JAAS realm. The easiest way is to install the `keycloak-jaas` feature, which has the JAAS realm predefined. You can override the feature's predefined realm by using your own `keycloak` JAAS realm with higher ranking. For details see the https://access.redhat.com/documentation/en-us/red_hat_jboss_fuse/6.3/html-single/security_guide/#ESBSecureContainer[JBoss Fuse documentation].
. Start Fuse and install the `keycloak` JAAS realm. The easiest way is to install the `keycloak-jaas` feature, which has the JAAS realm predefined. You can override the feature's predefined realm by using your own `keycloak` JAAS realm with higher ranking. For details see the https://access.redhat.com/documentation/en-us/red_hat_jboss_fuse/6.3/html-single/security_guide/#ESBSecureContainer[JBoss Fuse documentation].
+
Use these commands in the Fuse terminal:
+
@ -58,11 +60,11 @@ NOTE: On some later operating systems, you might also need to use the SSH comman
Note that the user needs to have realm role `admin` to perform all operations or another role to perform a subset of operations (for example, the *viewer* role that restricts the user to run only read-only Karaf commands). The available roles are configured in `$FUSE_HOME/etc/org.apache.karaf.shell.cfg` or `$FUSE_HOME/etc/system.properties`.
====== Using JMX Authentication
====== Using JMX authentication
JMX authentication might be necessary if you want to use jconsole or another external tool to remotely connect to JMX through RMI. Otherwise it might be better to use hawt.io/jolokia, since the jolokia agent is installed in hawt.io by default. For more details see <<_hawtio,Hawtio Admin Console>>.
To use JMX authentication, complete the following steps:
.Procedure
. In the `$FUSE_HOME/etc/org.apache.karaf.management.cfg` file, change the jmxRealm property to:
+

15
securing_apps/topics/oidc/java/fuse/hawtio.adoc
View file

@ -2,7 +2,9 @@
[[_hawtio]]
===== Securing the Hawtio Administration Console
To secure the Hawtio Administration Console with {project_name}, complete the following steps:
To secure the Hawtio Administration Console with {project_name}, perform the following procedure.
.Procedure
. Add these properties to the `$FUSE_HOME/etc/system.properties` file:
+
@ -14,10 +16,10 @@ hawtio.keycloakClientConfig=file://${karaf.base}/etc/keycloak-hawtio-client.json
hawtio.rolePrincipalClasses=org.keycloak.adapters.jaas.RolePrincipal,org.apache.karaf.jaas.boot.principal.RolePrincipal
----
. Create a client in the {project_name} administration console in your realm. For example, in the {project_name} `demo` realm, create a client `hawtio-client`, specify `public` as the Access Type, and specify a redirect URI pointing to Hawtio: \http://localhost:8181/hawtio/*. You must also have a corresponding Web Origin configured (in this case, \http://localhost:8181).
. Create a client in the {project_name} Admin Console in your realm. For example, in the {project_name} `demo` realm, create a client `hawtio-client`, specify `public` as the Access Type, and specify a redirect URI pointing to Hawtio: \http://localhost:8181/hawtio/*. You must also have a corresponding Web Origin configured (in this case, \http://localhost:8181).
. Create the `keycloak-hawtio-client.json` file in the `$FUSE_HOME/etc` directory using content similar to that shown in the example below. Change the `realm`, `resource`, and `auth-server-url` properties according to your {project_name} environment. The `resource` property must point to the client created in the previous step. This file is used by the client (Hawtio JavaScript application) side.
+
[source,json]
----
{
@ -58,13 +60,16 @@ Note that the user needs to have the proper realm role to successfully authentic
====== Securing Hawtio on {fuseHawtioEAPVersion}
To run Hawtio on the {fuseHawtioEAPVersion} server, complete the following steps:
.Prerequisites
Set up {project_name} as described in <<_hawtio,Securing the Hawtio Administration Console>>. It is assumed that:
. Set up {project_name} as described in the previous section, Securing the Hawtio Administration Console. It is assumed that:
* you have a {project_name} realm `demo` and client `hawtio-client`
* your {project_name} is running on `localhost:8080`
* the {fuseHawtioEAPVersion} server with deployed Hawtio will be running on `localhost:8181`. The directory with this server is referred in next steps as `$EAP_HOME`.
.Procedure
. Copy the `{fuseHawtioWARVersion}` archive to the `$EAP_HOME/standalone/configuration` directory. For more details about deploying Hawtio see the https://access.redhat.com/documentation/en-us/red_hat_jboss_fuse/6.3/html-single/deploying_into_a_web_server/[Fuse Hawtio documentation].
. Copy the `keycloak-hawtio.json` and `keycloak-hawtio-client.json` files with the above content to the `$EAP_HOME/standalone/configuration` directory.

41
securing_apps/topics/oidc/java/fuse/install-feature.adoc
View file

@ -1,22 +1,25 @@
[[_fuse_install_feature]]
===== Installing the Keycloak Feature
===== Installing the Keycloak feature
You must first install the `keycloak` feature in the JBoss Fuse environment. The keycloak feature includes the Fuse adapter and all third-party dependencies. You can install it either from the Maven repository or from an archive.
====== Installing from the Maven Repository
====== Installing from the Maven repository
As a prerequisite, you must be online and have access to the Maven repository.
.Prerequisites
* You must be online and have access to the Maven repository.
ifeval::[{project_community}==true]
For community it's sufficient to be online as all the artifacts and 3rd party dependencies should be available in the maven central repository.
* For community it is sufficient to be online as all the artifacts and 3rd party dependencies should be available in the maven central repository.
endif::[]
ifeval::[{project_product}==true]
For {project_name} you first need to configure a proper Maven repository, so you can install the artifacts. For more information see the
* For {project_name}, configure a proper Maven repository, so you can install the artifacts. For more information see the
https://access.redhat.com/maven-repository[JBoss Enterprise Maven repository] page.
+
Assuming the Maven repository is {maven_repository}, add the following to the `$FUSE_HOME/etc/org.ops4j.pax.url.mvn.cfg` file and add the repository to the list of supported repositories. For example:
+
[source,subs="attributes"]
----
org.ops4j.pax.url.mvn.repositories= \
@ -26,9 +29,12 @@ Assuming the Maven repository is {maven_repository}, add the following to the `$
----
endif::[]
To install the keycloak feature using the Maven repository, complete the following steps:
. Start {fuseVersion}; then in the Karaf terminal type:
.Procedure
. Start {fuseVersion}
. In the Karaf terminal type:
+
[source,subs="attributes"]
----
@ -42,10 +48,9 @@ features:install keycloak
----
features:install keycloak-jetty9-adapter
----
+
. Ensure that the features were installed:
+
[source]
----
features:list | grep keycloak
@ -53,11 +58,18 @@ features:list | grep keycloak
====== Installing from the ZIP bundle
This is useful if you are offline or do not want to use Maven to obtain the JAR files and other artifacts.
This installation option is useful if you are offline or do not want to use Maven to obtain the JAR files and other artifacts.
To install the Fuse adapter from the ZIP archive, complete the following steps:
.Procedure
ifeval::[{project_product}==true]
. Download the {project_name} Fuse adapter ZIP archive from the link:https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?downloadType=distributions&product=core.service.rhsso[Sotware Downloads] site.
endif::[]
ifeval::[{project_community}==true]
. Download the {project_name} Fuse adapter ZIP archive from the link:https://www.keycloak.org/downloads[Downloads] site.
endif::[]
. Download the {project_name} Fuse adapter ZIP archive.
. Unzip it into the root directory of JBoss Fuse. The dependencies are then installed under the `system` directory. You can overwrite all existing jar files.
+
Use this for {fuseVersion}:
@ -81,4 +93,3 @@ features:install keycloak
----
. Install the corresponding Jetty adapter. Since the artifacts are available directly in the JBoss Fuse `system` directory, you do not need to use the Maven repository.

6
securing_apps/topics/oidc/java/fuse/servlet-whiteboard.adoc
View file

@ -1,12 +1,12 @@
[[_fuse_adapter_servlet_whiteboard]]
===== Securing a Servlet Deployed as an OSGI Service
===== Securing a servlet deployed as an OSGI Service
You can use this method if you have a servlet class inside your OSGI bundled project that is not deployed as a classic WAR application. Fuse uses Pax Web Whiteboard Extender to deploy such servlets as web applications.
To secure your servlet with {project_name}, complete the following steps:
.Procedure
. {project_name} provides PaxWebIntegrationService, which allows injecting jetty-web.xml and configuring security constraints for your application. You need to declare such services in the `OSGI-INF/blueprint/blueprint.xml` file inside your application. Note that your servlet needs to depend on it.
. {project_name} provides `org.keycloak.adapters.osgi.undertow.PaxWebIntegrationService`, which allows injecting jetty-web.xml and configuring security constraints for your application. You need to declare such services in the `OSGI-INF/blueprint/blueprint.xml` file inside your application. Note that your servlet needs to depend on it.
An example configuration:
+
[source,xml]

2
securing_apps/topics/oidc/java/fuse7-adapter.adoc
View file

@ -26,7 +26,7 @@ Security for the following items is supported for Fuse:
* SSH and JMX admin access
* https://hawt.io/[Hawtio administration console]
===== Securing Your Web Applications Inside Fuse 7
===== Securing your web applications inside Fuse 7
You must first install the {project_name} Karaf feature. Next you will need to perform the steps according to the type of application you want to secure.
All referenced web applications require injecting the {project_name} Undertow authentication mechanism into the underlying web server. The steps to achieve this depend on the application type. The details are described below.

2
securing_apps/topics/oidc/java/fuse7/camel.adoc
View file

@ -1,6 +1,6 @@
[[_fuse7_adapter_camel]]
===== Securing an Apache Camel Application
===== Securing an Apache Camel application
You can secure Apache Camel endpoints implemented with the https://camel.apache.org/components/next/undertow-component.html[camel-undertow] component by injecting the proper security constraints via blueprint and updating the used component to `undertow-keycloak`. You have to add the `OSGI-INF/blueprint/blueprint.xml` file to your Camel application with a similar configuration as below. The roles, security constraint mappings, and adapter configuration might differ slightly depending on your environment and needs.

6
securing_apps/topics/oidc/java/fuse7/classic-war.adoc
View file

@ -1,8 +1,8 @@
[[_fuse7_adapter_classic_war]]
===== Securing a Classic WAR Application
===== Securing a Classic WAR application
The needed steps to secure your WAR application are:
.Procedure
. In the `/WEB-INF/web.xml` file, declare the necessary:
* security constraints in the <security-constraint> element
@ -69,7 +69,7 @@ For example:
. Contrary to the Fuse 6 adapter, there are no special OSGi imports needed in MANIFEST.MF.
[[_fuse7_config_external_adapter]]
====== Configuration Resolvers
====== Configuration resolvers
The `keycloak.json` adapter configuration file can be stored inside a bundle,
which is default behaviour, or in a directory on a filesystem. To specify the

2
securing_apps/topics/oidc/java/fuse7/cxf-builtin.adoc
View file

@ -1,6 +1,6 @@
[[_fuse7_adapter_cxf_builtin]]
===== Securing an Apache CXF Endpoint on the Default Undertow Engine
===== Securing an Apache CXF endpoint on the default Undertow Engine
Some services automatically come with deployed servlets on startup. One such service is the CXF servlet running in the $$http://localhost:8181/cxf$$ context. Fuse's Pax Web supports altering existing contexts via configuration admin. This can be used to secure endpoints by {project_name}.

6
securing_apps/topics/oidc/java/fuse7/cxf-separate.adoc
View file

@ -1,8 +1,10 @@
[[_fuse7_adapter_cxf_separate]]
===== Securing an Apache CXF Endpoint on a Separate Undertow Engine
===== Securing an Apache CXF endpoint on a separate Undertow Engine
To run your CXF endpoints secured by {project_name} on a separate Undertow engine, complete the following steps:
To run your CXF endpoints secured by {project_name} on a separate Undertow engine, perform the following procedure.
.Procedure
. Add `OSGI-INF/blueprint/blueprint.xml` to your application, and in it, add the proper configuration resolver bean similarly to <<_fuse7_adapter_camel,Camel configuration>>.
In the `httpu:engine-factory` declare `org.keycloak.adapters.osgi.undertow.CxfKeycloakAuthHandler` handler using that camel configuration. The configuration for a CFX JAX-WS application might resemble this one:

10
securing_apps/topics/oidc/java/fuse7/fuse-admin.adoc
View file

@ -8,7 +8,9 @@
with {project_name}, protecting non-web administration services such as SSH with {project_name} credentials is a best pracrice. You can do this using the JAAS login module, which allows remote connection to {project_name} and verifies credentials based on
<<_resource_owner_password_credentials_flow,Resource Owner Password Credentials>>.
To enable SSH authentication, complete the following steps:
To enable SSH authentication, perform the following procedure.
.Procedure
. In {project_name} create a client (for example, `ssh-jmx-admin-client`), which will be used for SSH authentication.
This client needs to have `Direct Access Grants Enabled` selected to `On`.
@ -58,11 +60,13 @@ NOTE: On some later operating systems, you might also need to use the SSH comman
Note that the user needs to have realm role `admin` to perform all operations or another role to perform a subset of operations (for example, the *viewer* role that restricts the user to run only read-only Karaf commands). The available roles are configured in `$FUSE_HOME/etc/org.apache.karaf.shell.cfg` or `$FUSE_HOME/etc/system.properties`.
====== Using JMX Authentication
====== Using JMX authentication
JMX authentication might be necessary if you want to use jconsole or another external tool to remotely connect to JMX through RMI. Otherwise it might be better to use hawt.io/jolokia, since the jolokia agent is installed in hawt.io by default. For more details see <<_fuse7_hawtio,Hawtio Admin Console>>.
To use JMX authentication, complete the following steps:
To use JMX authentication, perform the following procedure.
.Procedure
. In the `$FUSE_HOME/etc/org.apache.karaf.management.cfg` file, change the jmxRealm property to:
+

6
securing_apps/topics/oidc/java/fuse7/hawtio.adoc
View file

@ -2,9 +2,11 @@
[[_fuse7_hawtio]]
===== Securing the Hawtio Administration Console
To secure the Hawtio Administration Console with {project_name}, complete the following steps:
To secure the Hawtio Administration Console with {project_name}, perform the following procedure.
. Create a client in the {project_name} administration console in your realm. For example, in the {project_name} `demo` realm, create a client `hawtio-client`, specify `public` as the Access Type, and specify a redirect URI pointing to Hawtio: \http://localhost:8181/hawtio/*. Configure corresponding Web Origin (in this case, \http://localhost:8181). Setup client scope mapping to include _view-profile_ client role of _account_ client in _Scope_ tab in `hawtio-client` client detail.
.Procedure
. Create a client in the {project_name} Admin Console in your realm. For example, in the {project_name} `demo` realm, create a client `hawtio-client`, specify `public` as the Access Type, and specify a redirect URI pointing to Hawtio: \http://localhost:8181/hawtio/*. Configure corresponding Web Origin (in this case, \http://localhost:8181). Setup client scope mapping to include _view-profile_ client role of _account_ client in _Scope_ tab in `hawtio-client` client detail.
. Create the `keycloak-hawtio-client.json` file in the `$FUSE_HOME/etc` directory using content similar to that shown in the example below. Change the `realm`, `resource`, and `auth-server-url` properties according to your {project_name} environment. The `resource` property must point to the client created in the previous step. This file is used by the client (Hawtio JavaScript application) side.
+

36
securing_apps/topics/oidc/java/fuse7/install-feature.adoc
View file

@ -1,35 +1,38 @@
[[_fuse7_install_feature]]
===== Installing the Keycloak Feature
===== Installing the Keycloak feature
You must first install the `keycloak-pax-http-undertow` and `keycloak-jaas` features in the JBoss Fuse environment. The `keycloak-pax-http-undertow` feature includes the Fuse adapter and all third-party dependencies. The `keycloak-jaas` contains JAAS module used in realm for SSH and JMX authentication. You can install it either from the Maven repository or from an archive.
====== Installing from the Maven Repository
====== Installing from the Maven repository
As a prerequisite, you must be online and have access to the Maven repository.
.Prerequisites
* You must be online and have access to the Maven repository.
ifeval::[{project_community}==true]
For community it's sufficient to be online as all the artifacts and 3rd party dependencies should be available in the maven central repository.
* For community it is sufficient to be online as all the artifacts and 3rd party dependencies should be available in the maven central repository.
endif::[]
ifeval::[{project_product}==true]
For {project_name} you first need to configure a proper Maven repository, so you can install the artifacts. For more information see the
* For {project_name}, configure a proper Maven repository, so you can install the artifacts. For more information see the
https://access.redhat.com/maven-repository[JBoss Enterprise Maven repository] page.
Assuming the Maven repository is {maven_repository}, add the following to the `$FUSE_HOME/etc/org.ops4j.pax.url.mvn.cfg` file and add the repository to the list of supported repositories. For example:
* Assuming the Maven repository is {maven_repository}, add the following to the `$FUSE_HOME/etc/org.ops4j.pax.url.mvn.cfg` file and add the repository to the list of supported repositories. For example:
+
[source,subs="attributes"]
----
config:edit org.ops4j.pax.url.mvn
config:property-append org.ops4j.pax.url.mvn.repositories ,{maven_repository}@id=redhat.product.repo
config:update
feature:repo-refresh
feature:repo-refresh
----
endif::[]
To install the keycloak feature using the Maven repository, complete the following steps:
.Procedure
. Start {fuse7Version}; then in the Karaf terminal type:
. Start {fuse7Version}
. In the Karaf terminal, type:
+
[source,subs="attributes"]
----
@ -45,7 +48,7 @@ feature:install pax-http-undertow
----
. Ensure that the features were installed:
+
[source]
----
feature:list | grep keycloak
@ -55,9 +58,15 @@ feature:list | grep keycloak
This is useful if you are offline or do not want to use Maven to obtain the JAR files and other artifacts.
To install the Fuse adapter from the ZIP archive, complete the following steps:
.Procedure
. Download the {project_name} Fuse adapter ZIP archive.
ifeval::[{project_product}==true]
. Download the {project_name} Fuse adapter ZIP archive from the link:https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?downloadType=distributions&product=core.service.rhsso[Sotware Downloads] site.
endif::[]
ifeval::[{project_community}==true]
. Download the {project_name} Fuse adapter ZIP archive from the link:https://www.keycloak.org/downloads[Downloads] site.
endif::[]
. Unzip it into the root directory of JBoss Fuse. The dependencies are then installed under the `system` directory. You can overwrite all existing jar files.
+
Use this for {fuse7Version}:
@ -81,4 +90,3 @@ feature:install keycloak-pax-http-undertow keycloak-jaas
----
. Install the corresponding Undertow adapter. Since the artifacts are available directly in the JBoss Fuse `system` directory, you do not need to use the Maven repository.

8
securing_apps/topics/oidc/java/fuse7/servlet-whiteboard.adoc
View file

@ -1,10 +1,10 @@
[[_fuse7_adapter_servlet_whiteboard]]
===== Securing a Servlet Deployed as an OSGI Service
===== Securing a servlet deployed as an OSGI Service
You can use this method if you have a servlet class inside your OSGI bundled project that is not deployed as a classic WAR application. Fuse uses Pax Web Whiteboard Extender to deploy such servlets as web applications.
To secure your servlet with {project_name}, complete the following steps:
.Procedure
. {project_name} provides `org.keycloak.adapters.osgi.undertow.PaxWebIntegrationService`, which allows configuring authentication method and security constraints for your application. You need to declare such services in the `OSGI-INF/blueprint/blueprint.xml` file inside your application. Note that your servlet needs to depend on it.
An example configuration:
@ -48,8 +48,8 @@ An example configuration:
</service>
</blueprint>
----
* You might need to have the `WEB-INF` directory inside your project (even if your project is not a web application) and create the `/WEB-INF/keycloak.json` file as described in the <<_fuse7_adapter_classic_war,Classic WAR application>> section.
+
You might need to have the `WEB-INF` directory inside your project (even if your project is not a web application) and create the `/WEB-INF/keycloak.json` file as described in the <<_fuse7_adapter_classic_war,Classic WAR application>> section.
Note you don't need the `web.xml` file as the security-constraints are declared in the blueprint configuration file.
. Contrary to the Fuse 6 adapter, there are no special OSGi imports needed in MANIFEST.MF.

6
securing_apps/topics/oidc/java/installed-adapter.adoc
View file

@ -2,7 +2,7 @@
==== CLI / Desktop Applications
{project_name} supports securing desktop
(e.g. Swing, JavaFX) or CLI applications via the
(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`
@ -34,7 +34,7 @@ id_token) which can then be used to call backend services.
The `KeycloakInstalled` adapter provides support for renewal of stale tokens.
[[_installed_adapter_installation]]
===== Adapter Installation
===== Installing the adapter
[source,xml,subs="attributes+"]
----
@ -49,7 +49,7 @@ The `KeycloakInstalled` adapter provides support for renewal of stale tokens.
----
===== Client Configuration
===== Client configuration
The application needs to be configured as a `public` OpenID Connect client with
`Standard Flow Enabled` and pass:[http://localhost] as an allowed `Valid Redirect URI`.

12
securing_apps/topics/oidc/java/java-adapter-config.adoc
View file

@ -1,6 +1,6 @@
[[_java_adapter_config]]
==== Java Adapter Config
==== Java adapter configuration
Each Java adapter supported by {project_name} can be configured by a simple JSON file.
This is what one might look like:
@ -47,7 +47,7 @@ This is what one might look like:
----
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}`.
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`.
@ -63,7 +63,7 @@ resource::
This is _REQUIRED._
realm-public-key::
PEM format of the realm public key. You can obtain this from the administration console.
PEM format of the realm public key. You can obtain this from the Admin 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} 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 it's keys, adapter will break.
@ -128,10 +128,10 @@ bearer-only::
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,
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.
Keycloak auto-detects SOAP or REST clients based on typical headers like `X-Requested-With`, `SOAPAction` or `Accept`.
{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::

2
securing_apps/topics/oidc/java/java-adapters.adoc
View file

@ -1,4 +1,4 @@
=== Java Adapters
=== Java adapters
{project_name} comes with a range of different adapters for Java application. Selecting the correct adapter depends on the target platform.

74
securing_apps/topics/oidc/java/jboss-adapter-rpms.adoc
View file

@ -1,58 +1,61 @@
[[_jboss_adapter_rpm]]
==== Installing JBoss EAP Adapter from an RPM
Install the EAP 7 Adapters from an RPM:
[id="jboss7_adapter_rpm"]
==== Installing JBoss EAP 7 adapters from an RPM
NOTE: With Red Hat Enterprise Linux 7, the term channel was replaced with the term repository. In these instructions only the term repository is used.
You must subscribe to the {appserver_name} {appserver_version} repository before you can install the {appserver_name} 7 adapters from an RPM.
.Prerequisites
. Ensure that your Red Hat Enterprise Linux system is registered to your account using Red Hat Subscription Manager. For more information see the link:https://access.redhat.com/documentation/en-us/red_hat_subscription_management/1/html-single/quick_registration_for_rhel/index[Red Hat Subscription Management documentation].
You must subscribe to the {appserver_name} {appserver_version} repository before you can install the {appserver_name} 7 adapters from an RPM.
. If you are already subscribed to another JBoss EAP repository, you must unsubscribe from that repository first.
* Ensure that your Red Hat Enterprise Linux system is registered to your account using Red Hat Subscription Manager. For more information see the link:https://access.redhat.com/documentation/en-us/red_hat_subscription_management/1/html-single/quick_registration_for_rhel/index[Red Hat Subscription Management documentation].
* If you are already subscribed to another JBoss EAP repository, you must unsubscribe from that repository first.
+
For Red Hat Enterprise Linux 6, 7: Using Red Hat Subscription Manager, subscribe to the {appserver_name} {appserver_version} repository using the following command. Replace <RHEL_VERSION> with either 6 or 7 depending on your Red Hat Enterprise Linux version.
+
[source,bash,subs="attributes+"]
----
$ sudo subscription-manager repos --enable=jb-eap-7-for-rhel-<RHEL_VERSION>-server-rpms
----
+
For Red Hat Enterprise Linux 8: Using Red Hat Subscription Manager, subscribe to the {appserver_name} {appserver_version} repository using the following command:
+
[source,bash,subs="attributes+"]
----
$ sudo subscription-manager repos --enable=jb-eap-{appserver_version}-for-rhel-8-x86_64-rpms --enable=rhel-8-for-x86_64-baseos-rpms --enable=rhel-8-for-x86_64-appstream-rpms
----
Install the {appserver_name} 7 adapters for OIDC using the following command at Red Hat Enterprise Linux 6, 7:
.Procedure
. Install the {appserver_name} 7 adapters for OIDC based on your version of Red Hat Enterprise Linux.
* Install on Red Hat Enterprise Linux 6, 7:
+
[source,bash,subs="attributes+"]
----
$ sudo yum install eap7-keycloak-adapter-sso7_4
$ sudo yum install eap7-keycloak-adapter-sso7_5
----
or use following one for Red Hat Enterprise Linux 8:
* Install on Red Hat Enterprise Linux 8:
+
[source,bash,subs="attributes+"]
----
$ sudo dnf install eap7-keycloak-adapter-sso7_4
$ sudo dnf install eap7-keycloak-adapter-sso7_5
----
+
NOTE: The default EAP_HOME path for the RPM installation is /opt/rh/eap7/root/usr/share/wildfly.
Run the appropriate module installation script.
For the OIDC module, enter the following command:
. Run the installation script for the OIDC module.
+
[source,bash,subs="attributes+"]
----
$ $EAP_HOME/bin/jboss-cli.sh -c --file=$EAP_HOME/bin/adapter-install.cli
----
Your installation is complete.
Install the EAP 6 Adapters from an RPM:
[id="jboss6_adapter_rpm"]
==== Installing JBoss EAP 6 adapters from an RPM
NOTE: With Red Hat Enterprise Linux 7, the term channel was replaced with the term repository. In these instructions only the term repository is used.
@ -60,28 +63,31 @@ You must subscribe to the JBoss EAP 6 repository before you can install the EAP
.Prerequisites
. Ensure that your Red Hat Enterprise Linux system is registered to your account using Red Hat Subscription Manager. For more information see the link:https://access.redhat.com/documentation/en-us/red_hat_subscription_management/1/html-single/quick_registration_for_rhel/index[Red Hat Subscription Management documentation].
. If you are already subscribed to another JBoss EAP repository, you must unsubscribe from that repository first.
* Ensure that your Red Hat Enterprise Linux system is registered to your account using Red Hat Subscription Manager. For more information see the link:https://access.redhat.com/documentation/en-us/red_hat_subscription_management/1/html-single/quick_registration_for_rhel/index[Red Hat Subscription Management documentation].
* If you are already subscribed to another JBoss EAP repository, you must unsubscribe from that repository first.
+
Using Red Hat Subscription Manager, subscribe to the JBoss EAP 6 repository using the following command. Replace <RHEL_VERSION> with either 6 or 7 depending on your Red Hat Enterprise Linux version.
+
[source,bash,subs="attributes+"]
----
$ sudo subscription-manager repos --enable=jb-eap-6-for-rhel-<RHEL_VERSION>-server-rpms
----
Install the EAP 6 adapters for OIDC using the following command:
.Procedure
. Install the EAP 6 adapters for OIDC using the following command:
+
[source,bash,subs="attributes+"]
----
$ sudo yum install keycloak-adapter-sso7_4-eap6
$ sudo yum install keycloak-adapter-sso7_5eap6
----
+
NOTE: The default EAP_HOME path for the RPM installation is /opt/rh/eap6/root/usr/share/wildfly.
Run the appropriate module installation script.
For the OIDC module, enter the following command:
. Run the installation script for the OIDC module.
+
[source,bash,subs="attributes+"]
----
$ $EAP_HOME/bin/jboss-cli.sh -c --file=$EAP_HOME/bin/adapter-install.cli
----

158
securing_apps/topics/oidc/java/jboss-adapter.adoc
View file

@ -1,12 +1,20 @@
[[_jboss_adapter]]
ifeval::[{project_community}==true]
==== JBoss EAP/WildFly Adapter
==== JBoss EAP/WildFly adapter
endif::[]
ifeval::[{project_product}==true]
==== JBoss EAP Adapter
==== JBoss EAP adapter
endif::[]
You can install this adapter from a ZIP file or from an RPM.
* xref:jboss_adapter_installation[Installing JBOSS EAP adapters from a ZIP file]
* xref:jboss7_adapter_rpm[Installing JBoss EAP 7 Adapters from an RPM]
* xref:jboss6_adapter_rpm[Installing JBoss EAP 6 Adapters from an RPM]
[id="jboss_adapter_installation"]
==== Installing JBOSS EAP adapters from a ZIP file
ifeval::[{project_community}==true]
To be able to secure WAR apps deployed on JBoss EAP, WildFly or JBoss AS, you must install and configure the
{project_name} adapter subsystem. You then have two options to secure your WARs.
@ -16,144 +24,137 @@ To be able to secure WAR apps deployed on JBoss EAP, you must install and config
{project_name} adapter subsystem. You then have two options to secure your WARs.
endif::[]
You can provide an adapter config file in your WAR and change the auth-method to KEYCLOAK within web.xml.
* 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 {project_name} adapter subsystem configuration in the configuration file, such as `standalone.xml`.
Alternatively, you don't have to modify your WAR at all and you can secure it via the {project_name} adapter subsystem configuration in the configuration file, such as `standalone.xml`.
Both methods are described in this section.
[[_jboss_adapter_installation]]
===== Installing the adapter
Adapters are available as a separate archive depending on what server version you are using.
ifeval::[{project_community}==true]
NOTE: We only test and maintain adapter with the most recent version of WildFly available upon the release. Once new version of
NOTE: We test and maintain adapters only with the most recent version of WildFly available upon the release. Once a new version of
WildFly is released, the current adapters become deprecated and support for them will be removed after next WildFly release.
The other alternative is to switch your applications from WildFly to the JBoss EAP, as the JBoss EAP adapter is supported for much longer period.
Install on WildFly 9 or newer:
.Procedure
. Install the adapter that applies to your application server from the link:https://www.keycloak.org/downloads[Downloads] site.
* Install on WildFly 9 or newer:
+
[source, subs="attributes"]
----
$ cd $WILDFLY_HOME
$ unzip keycloak-wildfly-adapter-dist-{project_version}.zip
----
Install on JBoss EAP 7:
* Install on JBoss EAP 7:
+
[source, subs="attributes"]
----
$ cd $EAP_HOME
$ unzip keycloak-eap7-adapter-dist-{project_version}.zip
----
Install on JBoss EAP 6:
* Install on JBoss EAP 6:
+
[source, subs="attributes"]
----
$ cd $EAP_HOME
$ unzip keycloak-eap6-adapter-dist-{project_version}.zip
----
Install on JBoss AS 7.1:
* Install on JBoss AS 7.1:
+
[source, subs="attributes"]
----
$ cd $JBOSS_HOME
$ unzip keycloak-as7-adapter-dist-{project_version}.zip
----
endif::[]
ifeval::[{project_product}==true]
Install on JBoss EAP 7:
.Procedure
You can install the EAP 7 adapters either by unzipping a ZIP file, or by using an RPM.
Install the EAP 7 Adapters from a ZIP File:
. Install the adapter that applies to your application server from the link:https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?downloadType=distributions&product=core.service.rhsso[Sotware Downloads] site.
* Install on JBoss EAP 7:
+
[source, subs="attributes"]
----
$ cd $EAP_HOME
$ unzip rh-sso-{project_version}-eap7-adapter.zip
----
Install on JBoss EAP 6:
You can install the EAP 6 adapters either by unzipping a ZIP file, or by using an RPM.
Install the EAP 6 Adapters from a ZIP File:
* Install on JBoss EAP 6:
+
[source, subs="attributes"]
----
$ cd $EAP_HOME
$ unzip rh-sso-{project_version}-eap6-adapter.zip
----
endif::[]
+
This ZIP archive contains JBoss Modules specific to the {project_name} adapter. It also contains JBoss CLI scripts to configure the adapter subsystem.
To configure the adapter subsystem if the server is not running execute:
NOTE: Alternatively, you can specify the `server.config` property while installing adapters from the command line to install adapters using a different config, for example: `-Dserver.config=standalone-ha.xml`.
. To configure the adapter subsystem, execute the appropriate command.
ifeval::[{project_community}==true]
.WildFly 11 or newer
* Install on WildFly 11 or newer if the server *is not* running
+
[source]
----
$ ./bin/jboss-cli.sh --file=bin/adapter-elytron-install-offline.cli
----
.WildFly 10 or older
+
* Install on WildFly 11 or newer if the server *is* running
+
[source]
----
$ ./bin/jboss-cli.sh -c --file=bin/adapter-elytron-install.cli
----
+
NOTE: It is possible to use the legacy non-Elytron adapter on WildFly 11 or newer as well, meaning you can use `adapter-install-offline.cli`
even on those versions. However, we recommend to use the newer Elytron adapter.
+
* Install on WildFly 10 or older if the server *is not* running
+
[source]
----
$ ./bin/jboss-cli.sh --file=bin/adapter-install-offline.cli
----
NOTE: It is possible to use the legacy non-Elytron adapter on WildFly 11 or newer as well, meaning you can use `adapter-install-offline.cli`
even on those versions. However, we recommend to use the newer Elytron adapter.
endif::[]
ifeval::[{project_product}==true]
.JBoss EAP 7.1 or newer
[source]
----
$ ./bin/jboss-cli.sh --file=bin/adapter-elytron-install-offline.cli
----
NOTE: The offline script is not available for JBoss EAP 6.4
endif::[]
Alternatively, if the server is running execute:
ifeval::[{project_community}==true]
.WildFly 11 or newer
[source]
----
$ ./bin/jboss-cli.sh -c --file=bin/adapter-elytron-install.cli
----
.WildFly 10 or older
+
* Install on WildFly 10 or older if the server *is* running
+
[source]
----
$ ./bin/jboss-cli.sh -c --file=bin/adapter-install.cli
----
endif::[]
NOTE: Alternatively, you can specify the `server.config` property while installing adapters from the command line to install adapters using a different config, for example: `-Dserver.config=standalone-ha.xml`.
endif::[]
ifeval::[{project_product}==true]
.JBoss EAP 7.1 or newer
* Install on JBoss EAP 7.1 or newer if the server *is not* running.
+
[source]
----
$ ./bin/jboss-cli.sh --file=bin/adapter-elytron-install-offline.cli
----
+
NOTE: The offline script is not available for JBoss EAP 6.4
* Install on JBoss EAP 7.1 or newer if the server *is* running.
+
[source]
----
$ ./bin/jboss-cli.sh -c --file=bin/adapter-elytron-install.cli
----
+
NOTE: It is possible to use the legacy non-Elytron adapter on JBoss EAP 7.1 or newer as well, meaning you can use `adapter-install-offline.cli`
.JBoss EAP 6.4
* Install on JBoss EAP 6.4
+
[source]
----
$ ./bin/jboss-cli.sh -c --file=bin/adapter-install.cli
@ -166,19 +167,21 @@ endif::[]
{appserver_name} has built-in support for single sign-on for web applications deployed to the same {appserver_name}
instance. This should not be enabled when using {project_name}.
===== Required Per WAR Configuration
===== Securing a WAR
This section describes how to secure a WAR directly by adding configuration and editing files within your WAR package.
The first thing you must do is create a `keycloak.json` adapter configuration file within the `WEB-INF` directory of your WAR.
.Procedure
. Create a `keycloak.json` adapter configuration file within the `WEB-INF` directory of your WAR.
+
The format of this configuration file is described in the <<_java_adapter_config,Java adapter configuration>> section.
. Set the `auth-method` to `KEYCLOAK` in `web.xml`.
Next you must set the `auth-method` to `KEYCLOAK` in `web.xml`.
You also have to use standard servlet security to specify role-base constraints on your URLs.
. Use standard servlet security to specify role-base constraints on your URLs.
+
Here's an example:
+
[source,xml]
----
@ -228,12 +231,12 @@ Here's an example:
</web-app>
----
===== Securing WARs via Adapter Subsystem
===== Securing WARs via adapter subsystem
You do not have to modify your WAR to secure it with {project_name}. Instead you can externally secure it via the {project_name} Adapter Subsystem.
While you don't have to specify KEYCLOAK as an `auth-method`, you still have to define the `security-constraints` in `web.xml`.
You do not, however, have to create a `WEB-INF/keycloak.json` file.
This metadata is instead defined within server configuration (i.e. `standalone.xml`) in the {project_name} subsystem definition.
The metadata is instead defined within server configuration (`standalone.xml`) in the {project_name} subsystem definition.
[source,xml]
----
@ -259,7 +262,7 @@ Its value is the `module-name` defined in `web.xml` with `.war` appended. The re
The exception is the `credential` element.
To make it easier for you, you can go to the {project_name} Administration Console and go to the Client/Installation tab of the application this WAR is aligned with.
To make it easier for you, you can go to the {project_name} Admin Console and go to the Client/Installation tab of the application this WAR is aligned with.
It provides an example XML file you can cut and paste.
If you have multiple deployments secured by the same realm you can share the realm configuration in a separate element. For example:
@ -289,7 +292,6 @@ If you have multiple deployments secured by the same realm you can share the rea
</subsystem>
----
===== Security domain
===== Security Domain
The security context is propagated to the EJB tier automatically.
The security context is propagated to the EJB tier automatically.

65
securing_apps/topics/oidc/java/jetty9-adapter.adoc
View file

@ -1,48 +1,49 @@
[[_jetty9_adapter]]
==== Jetty 9.x Adapters
==== Jetty 9.x adapters
Keycloak has a separate adapter for Jetty 9.2.x, Jetty 9.3.x and Jetty 9.4.x that you will have to install into your Jetty installation.
You then have to provide some extra configuration in each WAR you deploy to Jetty.
Let's go over these steps.
[[_jetty9_adapter_installation]]
===== Adapter Installation
===== Installing the adapter
Adapters are no longer included with the appliance or war distribution. Each adapter is a separate download on the Keycloak download site.
They are also available as a maven artifact.
Adapters are no longer included with the appliance or war distribution. Each adapter is a separate download on the Keycloak downloads site. They are also available as a maven artifact.
You must unzip the Jetty 9.x distro into Jetty 9.x's link:https://www.eclipse.org/jetty/documentation/jetty-9/index.html[base directory].
Including adapter's jars within your WEB-INF/lib directory will not work!
In the example below, the Jetty base is named `your-base`:
.Procedure
. Download the {project_name} Jetty 9.x adapter ZIP archive from the link:https://www.keycloak.org/downloads[Keycloak Downloads] site.
. Unzip the Jetty 9.x distro into Jetty 9.x's link:https://www.eclipse.org/jetty/documentation/jetty-9/index.html[base directory]. In the example below, the Jetty base is named `your-base`:
+
[source]
----
$ cd your-base
$ unzip keycloak-jetty93-adapter-dist-2.5.0.Final.zip
----
Next, you will have to enable the `keycloak` module for your Jetty base:
. Enable the `keycloak` module for your Jetty base:
+
[source]
----
$ java -jar $JETTY_HOME/start.jar --add-to-startd=keycloak
----
+
====
[NOTE]
Including the adapter's jars within your WEB-INF/lib directory will not work.
====
[[_jetty9_per_war]]
===== Required Per WAR Configuration
===== Jetty 9 Securing a WAR
This section describes how to secure a WAR directly by adding config and editing files within your WAR package.
Use this procedure to secure a WAR directly by adding config and editing files within your WAR package.
The first thing you must do is create a `WEB-INF/jetty-web.xml` file in your WAR package.
This is a Jetty specific config file and you must define a Keycloak specific authenticator within it.
.Procedure
. Create a `WEB-INF/jetty-web.xml` file in your WAR package. This is a Jetty specific config fil. You define a Keycloak specific authenticator within it.
+
[source]
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
@ -55,21 +56,17 @@ This is a Jetty specific config file and you must define a Keycloak specific aut
</Configure>
----
Next you must create a `keycloak.json` adapter config file within the `WEB-INF` directory of your WAR.
. Create a `keycloak.json` adapter config file within the `WEB-INF` directory of your WAR.
+
The format of this config file is described in the <<_java_adapter_config,Java adapter configuration>> section.
+
WARNING: The Jetty 9.x adapter will not be able to find the `keycloak.json` file.
You will have to define all adapter settings within the `jetty-web.xml` file as described below.
Instead of using keycloak.json, you can define everything within the `jetty-web.xml`.
You'll just have to figure out how the json settings match to the `org.keycloak.representations.adapters.config.AdapterConfig` class.
You'll just have to figure out how the json settings match to the `org.keycloak.representations.adapters.config.AdapterConfig` class.
+
[source]
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
@ -98,19 +95,15 @@ You'll just have to figure out how the json settings match to the `org.keycloak.
</Configure>
----
You do not have to crack open your WAR to secure it with keycloak.
Instead create the jetty-web.xml file in your webapps directory with the name of yourwar.xml.
Jetty should pick it up.
In this mode, you'll have to declare keycloak.json configuration directly within the xml file.
Finally you must specify both a `login-config` and use standard servlet security to specify role-base constraints on your URLs.
Here's an example:
. Create the jetty-web.xml file in your webapps directory with the name of yourwar.xml.
Jetty should pick it up. You do not need to open your WAR to secure it with {project_name}.
In this mode, you declare keycloak.json configuration directly within the xml file.
. Specify both a `login-config` and use standard servlet security to specify role-base constraints on your URLs. Here's an example:
+
[source,xml]
----
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"

4
securing_apps/topics/oidc/java/params_forwarding.adoc
View file

@ -1,5 +1,5 @@
[[_params_forwarding]]
==== Parameters 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
@ -39,7 +39,7 @@ More info in the link:{adminguide_link}#_client_suggested_idp[Identity Provider
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 link:{adminguide_link}[{adminguide_name}].
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

6
securing_apps/topics/oidc/java/servlet-filter-adapter.adoc
View file

@ -1,5 +1,5 @@
[[_servlet_filter_adapter]]
==== Java Servlet Filter Adapter
==== Java servlet filter adapter
If you are deploying your Java Servlet application on a platform where there is no {project_name} 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.
@ -97,7 +97,7 @@ NOTE: If your OSGi platform is Apache Karaf with Pax Web, you should consider us
====== 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 (e.g. via bundle activator) and declarative (using OSGi annotations).
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:
[source,java]
@ -144,7 +144,7 @@ karaf@root()> config:property-set keycloak.config.file '${karaf.etc}/keycloak.js
karaf@root()> config:update
----
If you need more control, like e.g. providing custom `KeycloakConfigResolver` to implement <<_multi_tenancy,multi tenancy>>, you can register the filter programmatically:
If you need more control, for example, providing custom `KeycloakConfigResolver` to implement <<_multi_tenancy,multi tenancy>>, you can register the filter programmatically:
[source,java]
----

53
securing_apps/topics/oidc/java/spring-boot-adapter.adoc
View file

@ -1,8 +1,5 @@
[[_spring_boot_adapter]]
==== Spring Boot Adapter
To be able to secure Spring Boot apps you must add the Keycloak Spring Boot adapter JAR to your app.
You then have to provide some extra configuration via normal Spring Boot configuration (`application.properties`). Let's go over these steps.
==== Spring Boot adapter
ifeval::[{project_product}==true]
====
@ -13,29 +10,29 @@ endif::[]
[[_spring_boot_adapter_installation]]
===== Adapter Installation
===== Installing the Spring Boot adapter
The Keycloak Spring Boot adapter takes advantage of Spring Boot's autoconfiguration so all you need to do is add the Keycloak Spring Boot starter to your project.
To be able to secure Spring Boot apps you must add the Keycloak Spring Boot adapter JAR to your app.
You then have to provide some extra configuration via normal Spring Boot configuration (`application.properties`).
To add it using Maven, add the following to your dependencies:
The Keycloak Spring Boot adapter takes advantage of Spring Boot's autoconfiguration so all you need to do is add this adapter Keycloak Spring Boot starter to your project.
.Procedure
. To add the starter to your project using Maven, add the following to your dependencies:
+
[source,xml,subs="attributes+"]
----
<dependency>
<groupId>org.keycloak</groupId>
<artifactId>keycloak-spring-boot-starter</artifactId>
</dependency>
----
Add the Adapter BOM dependency:
. Add the Adapter BOM dependency:
+
[source,xml,subs="attributes+"]
----
<dependencyManagement>
<dependencies>
<dependency>
@ -47,7 +44,6 @@ Add the Adapter BOM dependency:
</dependency>
</dependencies>
</dependencyManagement>
----
@ -58,17 +54,16 @@ Currently the following embedded containers are supported and do not require any
* Jetty
[[_spring_boot_adapter_configuration]]
===== Required Spring Boot Adapter Configuration
===== Configuring the Spring Boot Adapter
This section describes how to configure your Spring Boot app to use Keycloak.
Use the procedure to configure your Spring Boot app to use {project_name}.
Instead of a `keycloak.json` file, you configure the realm for the Spring Boot Keycloak adapter via the normal Spring Boot configuration.
For example:
.Procedure
. Instead of a `keycloak.json` file, you configure the realm for the Spring Boot adapter via the normal Spring Boot configuration. For example:
+
[source]
----
keycloak.realm = demorealm
keycloak.auth-server-url = http://127.0.0.1:8080/auth
keycloak.ssl-required = external
@ -76,19 +71,17 @@ keycloak.resource = demoapp
keycloak.credentials.secret = 11111111-1111-1111-1111-111111111111
keycloak.use-resource-role-mappings = true
----
+
You can disable the Keycloak Spring Boot Adapter (for example in tests) by setting `keycloak.enabled = false`.
To configure a Policy Enforcer, unlike keycloak.json, `policy-enforcer-config` must be used instead of just `policy-enforcer`.
You also need to specify the Jakarta EE security config that would normally go in the `web.xml`.
The Spring Boot Adapter will set the `login-method` to `KEYCLOAK` and configure the `security-constraints` at startup time.
Here's an example configuration:
. To configure a Policy Enforcer, unlike keycloak.json, use `policy-enforcer-config` instead of just `policy-enforcer`.
. Specify the Jakarta EE security config that would normally go in the `web.xml`.
+
The Spring Boot Adapter will set the `login-method` to `KEYCLOAK` and configure the `security-constraints` at startup time. Here's an example configuration:
+
[source]
----
keycloak.securityConstraints[0].authRoles[0] = admin
keycloak.securityConstraints[0].authRoles[1] = user
keycloak.securityConstraints[0].securityCollections[0].name = insecure stuff
@ -99,4 +92,4 @@ keycloak.securityConstraints[1].securityCollections[0].name = admin stuff
keycloak.securityConstraints[1].securityCollections[0].patterns[0] = /admin
----
WARNING: If you plan to deploy your Spring Application as a WAR then you should not use the Spring Boot Adapter and use the dedicated adapter for the application server or servlet container you are using. Your Spring Boot should also contain a `web.xml` file.
WARNING: If you plan to deploy your Spring Application as a WAR then you should not use the Spring Boot Adapter and use the dedicated adapter for the application server or servlet container you are using. Your Spring Boot should also contain a `web.xml` file.

17
securing_apps/topics/oidc/java/spring-security-adapter.adoc
View file

@ -1,5 +1,6 @@
<[[_spring_security_adapter]]
==== Spring Security Adapter
[[_spring_security_adapter]]
==== 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.
@ -26,7 +27,7 @@ public ServletListenerRegistrationBean<HttpSessionEventPublisher> httpSessionEve
----
===== Adapter Installation
===== Installing the adapter
Add Keycloak Spring Security adapter as a dependency to your Maven POM or Gradle build.
@ -40,11 +41,11 @@ Add Keycloak Spring Security adapter as a dependency to your Maven POM or Gradle
</dependency>
----
===== Spring Security Configuration
===== Configuring the Spring Security Adapter
The Keycloak Spring Security adapter takes advantage of Spring Security's flexible security configuration syntax.
====== Java Configuration
====== Java configuration
Keycloak provides a KeycloakWebSecurityConfigurerAdapter as a convenient base class for creating a https://docs.spring.io/spring-security/site/docs/4.0.x/apidocs/org/springframework/security/config/annotation/web/WebSecurityConfigurer.html[WebSecurityConfigurer] instance.
The implementation allows customization by overriding methods.
@ -103,7 +104,7 @@ TIP: The `@KeycloakConfiguration` annotation is a metadata annotation that defin
the `@KeycloakConfiguration` annotation and create your own custom meta annotation or just use specific Spring annotations
for the {project_name} adapter.
====== XML Configuration
====== XML configuration
While Spring Security's XML namespace simplifies configuration, customizing the configuration can be a bit verbose.
@ -183,11 +184,11 @@ While Spring Security's XML namespace simplifies configuration, customizing the
===== Multi Tenancy
The Keycloak Spring Security adapter also supports multi tenancy.
The Keycloak Spring Security adapter also supports Multi Tenancy.
Instead of injecting `AdapterDeploymentContextFactoryBean` with the path to `keycloak.json` you can inject an implementation of the `KeycloakConfigResolver` interface.
More details on how to implement the `KeycloakConfigResolver` can be found in <<_multi_tenancy,Multi Tenancy>>.
===== Naming Security Roles
===== Naming security roles
Spring Security, when using role-based authentication, requires that role names start with `ROLE_`.
For example, an administrator role must be declared in Keycloak as `ROLE_ADMIN` or similar, not simply `ADMIN`.

68
securing_apps/topics/oidc/java/tomcat-adapter.adoc
View file

@ -1,67 +1,67 @@
[[_tomcat_adapter]]
==== Tomcat 7, 8 and 9 Adapters
==== Tomcat 7, 8, and 9 adapters
To be able to secure WAR apps deployed on Tomcat 7, 8 and 9 you must install the Keycloak Tomcat 7 adapter or Keycloak Tomcat adapter into your Tomcat installation.
You then have to provide some extra configuration in each WAR you deploy to Tomcat.
Let's go over these steps.
To be able to secure WAR apps deployed on Tomcat 7, 8, and 9, you install the Keycloak Tomcat 7 adapter or Keycloak Tomcat adapter into your Tomcat installation. You then perform extra configuration to secure each WAR you deploy to Tomcat.
[[_tomcat_adapter_installation]]
===== Adapter Installation
===== Installing the adapter
Adapters are no longer included with the appliance or war distribution.
Each adapter is a separate download on the Keycloak download site.
They are also available as a maven artifact.
Each adapter is a separate download on the Keycloak Downloads site.
They are also available as a maven artifact.
You must unzip the adapter distro into Tomcat's `lib/` directory.
Including adapter's jars within your WEB-INF/lib directory will not work! The Keycloak adapter is implemented as a Valve and valve code must reside in Tomcat's main lib/ directory.
.Procedure
Install on Tomcat 7:
. Download the adapter for the Tomcat version on your system from the link:https://www.keycloak.org/downloads[Keycloak Downloads] site.
* Install on Tomcat 7:
+
[source]
----
$ cd $TOMCAT_HOME/lib
$ unzip keycloak-tomcat7-adapter-dist.zip
----
Install on Tomcat 8 or 9:
----
* Install on Tomcat 8 or 9:
+
[source]
----
$ cd $TOMCAT_HOME/lib
$ unzip keycloak-tomcat-adapter-dist.zip
----
===== Required Per WAR Configuration
This section describes how to secure a WAR directly by adding config and editing files within your WAR package.
The first thing you must do is create a `META-INF/context.xml` file in your WAR package.
This is a Tomcat specific config file and you must define a Keycloak specific Valve.
[source]
----
====
[NOTE]
Including the adapter's jars within your WEB-INF/lib directory will not work. The Keycloak adapter is implemented as a Valve and valve code must reside in Tomcat's main lib/ directory.
====
===== Securing a WAR
This section describes how to secure a WAR directly by adding config and editing files within your WAR package.
.Procedure
. Create a `META-INF/context.xml` file in your WAR package.
+
This is a Tomcat specific config file and you must define a Keycloak specific Valve.
+
[source]
----
<Context path="/your-context-path">
<Valve className="org.keycloak.adapters.tomcat.KeycloakAuthenticatorValve"/>
</Context>
----
Next you must create a `keycloak.json` adapter config file within the `WEB-INF` directory of your WAR.
The format of this config file is described in the <<_java_adapter_config,Java adapter configuration>>
Finally you must specify both a `login-config` and use standard servlet security to specify role-base constraints on your URLs.
Here's an example:
. Create a `keycloak.json` adapter config file within the `WEB-INF` directory of your WAR.
+
The format of this config file is described in the <<_java_adapter_config,Java adapter configuration>>
. Specify both a `login-config` and use standard servlet security to specify role-base constraints on your URLs. Here's an example:
+
[source,xml]
----
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
@ -91,4 +91,4 @@ Here's an example:
<role-name>user</role-name>
</security-role>
</web-app>
----
----

26
securing_apps/topics/oidc/javascript-adapter.adoc
View file

@ -1,5 +1,5 @@
[[_javascript_adapter]]
=== JavaScript Adapter
=== JavaScript adapter
{project_name} comes with a client-side JavaScript library that can be used to secure HTML5/JavaScript applications. The JavaScript adapter has built-in support for Cordova applications.
@ -12,7 +12,7 @@ NOTE: You can also download package from npm: https://www.npmjs.com/package/keyc
One important thing to note about using client-side applications is that the client has to be a public client as there is no secure way to store client
credentials in a client-side application. This makes it very important to make sure the redirect URIs you have configured for the client are correct and as specific as possible.
To use the JavaScript adapter you must first create a client for your application in the {project_name} Administration Console. Make sure `public`
To use the JavaScript adapter you must first create a client for your application in the {project_name} Admin Console. Make sure `public`
is selected for `Access Type`.
You also need to configure `Valid Redirect URIs` and `Web Origins`. Be as specific as possible as failing to do so may result in a security vulnerability.
@ -74,7 +74,7 @@ With this feature enabled, your browser won't do a full redirect to the {project
This is particularly useful in case of SPAs (Single Page Applications).
To enable the _silent_ `check-sso`, you have to provide a `silentCheckSsoRedirectUri` attribute in the init method.
This URI needs to be a valid endpoint in the application (and of course it must be configured as a valid redirect for the client in the {project_name} Administration Console):
This URI needs to be a valid endpoint in the application (and of course it must be configured as a valid redirect for the client in the {project_name} Admin Console):
[source,javascript]
----
@ -165,7 +165,7 @@ your application.
WARNING: Session Status iframe functionality is limited in some modern browsers. Please see <<_modern_browsers,Modern Browsers with Tracking Protection Section>>.
[[_javascript_implicit_flow]]
==== Implicit and Hybrid Flow
==== Implicit and hybrid flow
By default, the JavaScript adapter uses the https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code] flow.
@ -179,7 +179,7 @@ request to exchange the code for tokens, but it has implications when the access
However, sending the access token in the URL fragment can be a security vulnerability. For example the token could be leaked through web server logs and or
browser history.
To enable implicit flow, you need to enable the `Implicit Flow Enabled` flag for the client in the {project_name} Administration Console.
To enable implicit flow, you need to enable the `Implicit Flow Enabled` flag for the client in the {project_name} Admin Console.
You also need to pass the parameter `flow` with value `implicit` to `init` method:
[source,javascript]
@ -217,7 +217,7 @@ keycloak.init({
Keycloak support hybrid mobile apps developed with https://cordova.apache.org/[Apache Cordova]. The JavaScript adapter has two modes for this: `cordova` and `cordova-native`:
The default is cordova, which the adapter will automatically select if no adapter type has been configured and window.cordova is present.
When logging in, it will open an https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-inappbrowser/[InApp Browser] that lets the user interact with {project_name} and afterwards returns to the app by redirecting to `http://localhost`. Because of this, you must whitelist this URL as a valid redirect-uri in the client configuration section of the Administration Console.
When logging in, it will open an https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-inappbrowser/[InApp Browser] that lets the user interact with {project_name} and afterwards returns to the app by redirecting to `http://localhost`. Because of this, you must whitelist this URL as a valid redirect-uri in the client configuration section of the Admin Console.
While this mode is easy to setup, it also has some disadvantages:
@ -227,8 +227,8 @@ While this mode is easy to setup, it also has some disadvantages:
Use this example app to help you get started: https://github.com/keycloak/keycloak/tree/master/examples/cordova
The alternative mode `cordova-native` takes a different approach.
It opens the login page using the system's browser.
The alternative mode `cordova-native` takes a different approach.
It opens the login page using the system's browser.
After the user has authenticated, the browser redirects back into the app using a special URL.
From there, the {project_name} adapter can finish the login by reading the code or token from the URL.
@ -251,7 +251,7 @@ Please refer to the Android and iOS sections of the https://github.com/e-imaxina
There are different kinds of links for opening apps: custom schemes (i.e. `myapp://login` or `android-app://com.example.myapp/https/example.com/login`) and https://developer.apple.com/ios/universal-links/[Universal Links (iOS)]) / https://developer.android.com/training/app-links/deep-linking[Deep Links (Android)].
While the former are easier to setup and tend to work more reliably, the later offer extra security as they are unique and only the owner of a domain can register them.
Custom-URLs are deprecated on iOS.
Custom-URLs are deprecated on iOS.
We recommend that you use universal links, combined with a fallback site with a custom-url link on it for best reliability.
Furthermore, we recommend the following steps to improve compatibility with the Keycloak Adapter:
@ -261,7 +261,7 @@ Furthermore, we recommend the following steps to improve compatibility with the
[source,xml]
----
<preference name="AndroidLaunchMode" value="singleTask" />
<preference name="AndroidLaunchMode" value="singleTask" />
----
There is an example app that shows how to use the native-mode: https://github.com/keycloak/keycloak/tree/master/examples/cordova-native
@ -334,7 +334,7 @@ the browser is restrictive regarding cookies. The adapter tries to detect this s
===== Browsers with "SameSite=Lax by Default" Policy
All features are supported if SSL / TLS connection is configured on the {project_name} side as well as on the application
side. See link:{installguide_link}#_setting_up_ssl[configuring the SSL / TLS]. Affected is e.g. Chrome starting with
side. See link:{installguide_link}#_setting_up_ssl[configuring the SSL / TLS]. Affected is for example Chrome starting with
version 84.
===== Browsers with Blocked Third-Party Cookies
@ -352,7 +352,7 @@ Regular `check-sso` is affected as well. Since Session Status iframe is unsuppor
has to be made when the adapter is initialized to check user's login status. This is different from standard behavior when
the iframe is used to tell whether the user is logged in, and the redirect is performed only when logged out.
An affected browser is e.g. Safari starting with version 13.1.
An affected browser is for example Safari starting with version 13.1.
==== JavaScript Adapter Reference
@ -406,7 +406,7 @@ responseMode::
flow::
Flow passed in init.
adapter::
Allows you to override the way that redirects and other browser-related functions will be handled by the library.
Available options:

12
securing_apps/topics/oidc/nodejs-adapter.adoc
View file

@ -1,5 +1,5 @@
[[_nodejs_adapter]]
=== Node.js Adapter
=== Node.js adapter
{project_name} provides a Node.js adapter built on top of https://github.com/senchalabs/connect[Connect] to protect server-side JavaScript apps - the goal was to be flexible enough to integrate with frameworks like https://expressjs.com/[Express.js].
@ -8,7 +8,7 @@ The library can be downloaded directly from https://www.npmjs.com/package/keyclo
https://github.com/keycloak/keycloak-nodejs-connect[GitHub].
endif::[]
To use the Node.js adapter, first you must create a client for your application in the {project_name} Administration Console. The adapter supports public, confidential, and bearer-only access type. Which one to choose depends on the use-case scenario.
To use the Node.js adapter, first you must create a client for your application in the {project_name} Admin Console. The adapter supports public, confidential, and bearer-only access type. Which one to choose depends on the use-case scenario.
Once the client is created click the `Installation` tab, select `{project_name} OIDC JSON` for `Format Option`, and then click `Download`. The downloaded `keycloak.json` file should be at the root folder of your project.
@ -105,7 +105,7 @@ By default, the scope value `openid` is passed as a query parameter to {project_
[source,javascript]
var keycloak = new Keycloak({ scope: 'offline_access' });
==== Installing Middleware
==== Installing middleware
Once instantiated, install the middleware into your connect-capable app:
@ -116,7 +116,7 @@ Once instantiated, install the middleware into your connect-capable app:
app.use( keycloak.middleware() );
----
==== Configuration for Proxies
==== Configuration for proxies
If the application is running behind a proxy that terminates an SSL connection
Express must be configured per the link:https://expressjs.com/en/guide/behind-proxies.html[express behind proxies] guide.
@ -134,7 +134,7 @@ Example configuration:
app.use( keycloak.middleware() );
----
==== Checking Authentication
==== Checking authentication
To check that a user is authenticated before accessing a resource,
simply use `keycloak.checkSso()`. It will only authenticate if the user is already logged-in. If the user is not logged-in, the browser will be redirected back to the originally-requested URL and remain unauthenticated:
@ -144,7 +144,7 @@ simply use `keycloak.checkSso()`. It will only authenticate if the user is alrea
app.get( '/check-sso', keycloak.checkSso(), checkSsoHandler );
----
==== Protecting Resources
==== Protecting resources
Simple authentication::

28
securing_apps/topics/oidc/oidc-generic.adoc
View file

@ -1,4 +1,4 @@
=== Other OpenID Connect Libraries
=== Other OpenID Connect libraries
{project_name} can be secured by supplied adapters that are usually easier to use and provide better integration with {project_name}. However, if an adapter is not available for your programming language, framework, or platform you might opt to use a generic OpenID Connect Relying Party (RP) library instead. This chapter describes details specific to {project_name} and does not contain specific protocol details. For more information see the https://openid.net/connect/[OpenID Connect specifications] and https://datatracker.ietf.org/doc/html/rfc6749[OAuth2 specification].
@ -16,7 +16,7 @@ $$http://localhost:8080/auth/realms/master/.well-known/openid-configuration$$
Some RP libraries retrieve all required endpoints from this endpoint, but for others you might need to list the endpoints individually.
===== Authorization Endpoint
===== Authorization endpoint
....
/realms/{realm-name}/protocol/openid-connect/auth
....
@ -25,7 +25,7 @@ The authorization endpoint performs authentication of the end-user. This is done
For more details see the https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint[Authorization Endpoint] section in the OpenID Connect specification.
===== Token Endpoint
===== Token endpoint
....
/realms/{realm-name}/protocol/openid-connect/token
....
@ -35,7 +35,7 @@ The token endpoint is also used to obtain new access tokens when they expire.
For more details see the https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint[Token Endpoint] section in the OpenID Connect specification.
===== Userinfo Endpoint
===== Userinfo endpoint
....
/realms/{realm-name}/protocol/openid-connect/userinfo
....
@ -44,7 +44,7 @@ The userinfo endpoint returns standard claims about the authenticated user, and
For more details see the https://openid.net/specs/openid-connect-core-1_0.html#UserInfo[Userinfo Endpoint] section in the OpenID Connect specification.
===== Logout Endpoint
===== Logout endpoint
....
/realms/{realm-name}/protocol/openid-connect/logout
....
@ -56,7 +56,7 @@ The user agent can be redirected to the endpoint, in which case the active user
The endpoint can also be invoked directly by the application. To invoke this endpoint directly the refresh token needs to be included as well as the credentials required to authenticate the client.
[[_certificate_endpoint]]
===== Certificate Endpoint
===== Certificate endpoint
....
/realms/{realm-name}/protocol/openid-connect/certs
....
@ -64,7 +64,7 @@ The endpoint can also be invoked directly by the application. To invoke this end
The certificate endpoint returns the public keys enabled by the realm, encoded as a JSON Web Key (JWK). Depending on the realm settings there can be one or more keys enabled for verifying tokens. For more information see the link:{adminguide_link}[{adminguide_name}] and the https://datatracker.ietf.org/doc/html/rfc7517[JSON Web Key specification].
[[_token_introspection_endpoint]]
===== Introspection Endpoint
===== Introspection endpoint
....
/realms/{realm-name}/protocol/openid-connect/token/introspect
....
@ -74,7 +74,7 @@ It can only be invoked by confidential clients.
For more details on how to invoke on this endpoint, see https://datatracker.ietf.org/doc/html/rfc7662[OAuth 2.0 Token Introspection specification].
===== Dynamic Client Registration Endpoint
===== Dynamic Client Registration endpoint
....
/realms/{realm-name}/clients-registrations/openid-connect
....
@ -85,7 +85,7 @@ For more details see the <<_client_registration,Client Registration chapter>> an
https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dynamic Client Registration specification].
[[_token_revocation_endpoint]]
===== Token Revocation Endpoint
===== Token Revocation endpoint
....
/realms/{realm-name}/protocol/openid-connect/revoke
....
@ -94,7 +94,7 @@ The token revocation endpoint is used to revoke tokens. Both refresh tokens and
For more details on how to invoke on this endpoint, see https://datatracker.ietf.org/doc/html/rfc7009[OAuth 2.0 Token Revocation specification].
===== Device Authorization Endpoint
===== Device Authorization endpoint
....
/realms/{realm-name}/protocol/openid-connect/auth/device
....
@ -104,7 +104,7 @@ The device authorization endpoint is used to obtain a device code and a user cod
For more details on how to invoke on this endpoint, see https://datatracker.ietf.org/doc/html/rfc8628[OAuth 2.0 Device Authorization Grant specification].
[[_backchannel_authentication_endpoint]]
===== Backchannel Authentication Endpoint
===== Backchannel Authentication endpoint
....
/realms/{realm-name}/protocol/openid-connect/ext/ciba/auth
....
@ -115,7 +115,7 @@ For more details on how to invoke on this endpoint, see https://openid.net/specs
Also please refer to other places of {project_name} documentation like <<_client_initiated_backchannel_authentication_grant,Client Initiated Backchannel Authentication Grant section of this guide>> and link:{adminguide_link}#_client_initiated_backchannel_authentication_grant[Client Initiated Backchannel Authentication Grant section] of {adminguide_name}.
==== Validating Access Tokens
==== Validating access tokens
If you need to manually validate access tokens issued by {project_name} you can invoke the <<_token_introspection_endpoint,Introspection Endpoint>>.
The downside to this approach is that you have to make a network invocation to the {project_name} server. This can be slow and possibly overload the
@ -127,7 +127,7 @@ JWS. Depending what language you code in, there are a multitude of third party
==== Flows
===== Authorization Code
===== Authorization code
The Authorization Code flow redirects the user agent to {project_name}. Once the user has successfully authenticated with {project_name} an
Authorization Code is created and the user agent is redirected back to the application. The application then uses the authorization code along with its
@ -190,7 +190,7 @@ curl \
"http://localhost:8080/auth/realms/master/protocol/openid-connect/token"
----
===== Client Credentials
===== Client credentials
Client Credentials is used when clients (applications and services) wants to obtain access on behalf of themselves rather than on behalf of a user. This can
for example be useful for background services that applies changes to the system in general rather than for a specific user.

2
securing_apps/topics/oidc/oidc-overview.adoc
View file

@ -1,5 +1,5 @@
[[_oidc]]
== OpenID Connect
== Using OpenID Connect to secure applications and services
This section describes how you can secure applications and services with OpenID Connect using either {project_name} adapters or generic OpenID Connect
Relying Party libraries.

24
securing_apps/topics/overview/basic-steps.adoc Normal file
View file

@ -0,0 +1,24 @@
=== Basic steps to secure applications and services
These are the basic steps for securing an application or a service in {project_name}.
. Configure a client using one of these options:
* A {project_name} adapter
* A generic OpenID connect or SAML library
. Register a client using one of these options:
* The {project_name} Admin Console
* The client registration service
* The CLI
[role="_additional-resources"]
.Additional resources
* This guide provides the detailed instructions for these steps. Related information exists in the link:{adminguide_link}[Server Administration Guide]. That guide provides instructions for using Admin Console to create a client. Creating a client is the same task as registering a client using the {project_name} Client Registration Service.

2
securing_apps/topics/overview/overview.adoc
View file

@ -1,4 +1,4 @@
== Overview
== Planning for securing applications and services
{project_name} supports both OpenID Connect (an extension to OAuth 2.0) and SAML 2.0. When securing clients and services the first thing you need to
decide is which of the two you are going to use. If you want you can also choose to secure some with OpenID Connect and others with SAML.

2
securing_apps/topics/overview/supported-platforms.adoc
View file

@ -1,5 +1,7 @@
=== Supported Platforms
{project_name} enables you to protect applications running on different platforms and using different technology stacks using OpenID Connect and SAML protocols.
==== OpenID Connect
===== Java

2
securing_apps/topics/overview/supported-protocols.adoc
View file

@ -2,6 +2,8 @@
=== Supported Protocols
{project_name} supports both OpenID Connect and SAML protocols.
==== OpenID Connect
link:https://openid.net/connect/[OpenID Connect] (OIDC) is an authentication protocol that is an extension of link:https://datatracker.ietf.org/doc/html/rfc6749[OAuth 2.0].

14
securing_apps/topics/overview/terminology.adoc Normal file
View file

@ -0,0 +1,14 @@
=== Terminology
These terms are used in this guide:
* `Clients` are entities that interact with {project_name} to authenticate users and obtain tokens. Most often, clients are applications and services acting on behalf of users that provide a single sign-on experience to their users and access other services using the tokens issued by the server. Clients can also be entities only interested in obtaining tokens and acting on their own behalf for accessing other services.
* `Applications` include a wide range of applications that work for specific platforms for each protocol
* `Client adapters` are libraries that make it easy to secure applications and services with {project_name}. They provide a tight integration to the underlying platform and framework.
* `Creating a client` and `registering a client` are the same action. `Creating a Client` is the term used to create a client by using the Admin Console. `Registering a client` is the term used to register a client by using the {project_name} Client Registration Service.
* `A service account` is a type of client that is able to obtain tokens on its own behalf.

2
securing_apps/topics/overview/what-are-client-adapters.adoc
View file

@ -1,4 +1,4 @@
=== What are Client Adapters?
=== Client adapters
{project_name} client adapters are libraries that make it very easy to secure applications and services with {project_name}. We call them
adapters rather than libraries as they provide a tight integration to the underlying platform and framework. This makes our adapters easy to use and they

2
securing_apps/topics/saml/java/MigrationFromOlderVersions.adoc
View file

@ -2,7 +2,7 @@
===== Migrating to 1.9.0
====== SAML SP Client Adapter Changes
====== SAML SP Client Adapter changes
Keycloak SAML SP Client Adapter now requires a specific endpoint, `/saml` to be registered with your IdP.
The SamlFilter must also be bound to /saml in addition to any other binding it has.

2
securing_apps/topics/saml/java/assertion-api.adoc
View file

@ -1,5 +1,5 @@
==== Obtaining Assertion Attributes
==== Obtaining assertion attributes
After a successful SAML login, your application code may want to obtain attribute values passed with the SAML assertion.
`HttpServletRequest.getUserPrincipal()` returns a `Principal` object that you can typecast into a {project_name} specific class

2
securing_apps/topics/saml/java/general-config/idp_singlesignonservice_subelement.adoc
View file

@ -37,7 +37,7 @@ responseBinding::
assertionConsumerServiceUrl::
URL of the assertion consumer service (ACS) where the IDP login service should send responses to.
This setting is _OPTIONAL_. By default it is unset, relying on the configuration in the IdP.
When set, it must end in `/saml`, e.g. `\http://sp.domain.com/my/endpoint/for/saml`. The value
When set, it must end in `/saml`, for example `\http://sp.domain.com/my/endpoint/for/saml`. The value
of this property is sent in `AssertionConsumerServiceURL` attribute of SAML `AuthnRequest` message.
This property is typically accompanied by the `responseBinding` attribute.

2
securing_apps/topics/saml/java/general-config/roleidentifiers_element.adoc
View file

@ -1,5 +1,5 @@
===== RoleIdentifiers Element
===== RoleIdentifiers element
The `RoleIdentifiers` element defines what SAML attributes within the assertion received from the user should be used
as role identifiers within the Jakarta EE Security Context for the user.

2
securing_apps/topics/saml/java/general-config/sp-keys.adoc
View file

@ -1,6 +1,6 @@
[[_saml-sp-keys]]
===== Service Provider Keys and Key Elements
===== Service Provider keys and key elements
If the IdP requires that the client application (or SP) sign all of its requests and/or if the IdP will encrypt assertions, you must define the keys used to do this.
For client-signed documents you must define both the private and public key or certificate that is used to sign documents.

8
securing_apps/topics/saml/java/general-config/sp_element.adoc
View file

@ -1,5 +1,5 @@
===== SP Element
===== SP element
Here is the explanation of the SP element attributes:
@ -52,10 +52,10 @@ turnOffChangeSessionIdOnLogin::
Default value is `false`.
autodetectBearerOnly::
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,
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.
Keycloak auto-detects SOAP or REST clients based on typical headers like `X-Requested-With`, `SOAPAction` or `Accept`.
{project_name} auto-detects SOAP or REST clients based on typical headers like `X-Requested-With`, `SOAPAction` or `Accept`.
The default value is _false_.
logoutPage::

6
securing_apps/topics/saml/java/general-config/sp_role_mappings_provider_element.adoc
View file

@ -1,5 +1,5 @@
===== RoleMappingsProvider Element
===== RoleMappingsProvider element
The `RoleMappingsProvider` is an optional element that allows for the specification of the id and configuration of the
`org.keycloak.adapters.saml.RoleMappingsProvider` SPI implementation that is to be used by the SAML adapter.
@ -29,7 +29,7 @@ The configuration of the provider looks as follows:
The `id` attribute identifies which of the installed providers is to be used. The `Property` sub-element can be used multiple times
to specify configuration properties for the provider.
====== Properties Based Role Mappings Provider
====== Properties Based role mappings provider
{project_name} includes a `RoleMappingsProvider` implementation that performs the role mappings using a `properties` file. This
provider is identified by the id `properties-based-role-mapper` and is implemented by the `org.keycloak.adapters.saml.PropertiesBasedRoleMapper`
@ -92,7 +92,7 @@ Note: to use spaces in role names for mappings, use unicode replacements for spa
role\u0020A=roleX,roleY
----
====== Adding Your Own Role Mappings Provider
====== Adding your own role mappings provider
To add a custom role mappings provider one simply needs to implement the `org.keycloak.adapters.saml.RoleMappingsProvider` SPI.
For more details see the `SAML Role Mappings SPI` section in link:{developerguide_link}[{developerguide_name}].

2
securing_apps/topics/saml/java/java-adapters.adoc
View file

@ -1,4 +1,4 @@
=== Java Adapters
=== Java adapters
{project_name} comes with a range of different adapters for Java application. Selecting the correct adapter depends on the target platform.

76
securing_apps/topics/saml/java/jboss-adapter/jboss-adapter-rpms.adoc
View file

@ -1,87 +1,93 @@
[[_jboss_adapter_rpm_saml]]
==== Installing JBoss EAP Adapter from an RPM
Install the EAP 7 Adapters from an RPM:
[[_jboss7_adapter_rpm_saml]]
==== Installing JBoss EAP 7 Adapters from an RPM
NOTE: With Red Hat Enterprise Linux 7, the term channel was replaced with the term repository. In these instructions only the term repository is used.
You must subscribe to the JBoss EAP 7 repository before you can install the EAP 7 adapters from an RPM.
.Prerequisites
. Ensure that your Red Hat Enterprise Linux system is registered to your account using Red Hat Subscription Manager. For more information see the link:https://access.redhat.com/documentation/en-us/red_hat_subscription_management/1/html-single/quick_registration_for_rhel/index[Red Hat Subscription Management documentation].
You must subscribe to the JBoss EAP 7 repository before you can install the EAP 7 adapters from an RPM.
. If you are already subscribed to another JBoss EAP repository, you must unsubscribe from that repository first.
* Ensure that your Red Hat Enterprise Linux system is registered to your account using Red Hat Subscription Manager. For more information see the link:https://access.redhat.com/documentation/en-us/red_hat_subscription_management/1/html-single/quick_registration_for_rhel/index[Red Hat Subscription Management documentation].
* If you are already subscribed to another JBoss EAP repository, you must unsubscribe from that repository first.
+
For Red Hat Enterprise Linux 6, 7: Using Red Hat Subscription Manager, subscribe to the {appserver_name} {appserver_version} repository using the following command. Replace <RHEL_VERSION> with either 6 or 7 depending on your Red Hat Enterprise Linux version.
+
[source,bash,subs="attributes+"]
----
$ sudo subscription-manager repos --enable=jb-eap-7-for-rhel-<RHEL_VERSION>-server-rpms
----
+
For Red Hat Enterprise Linux 8: Using Red Hat Subscription Manager, subscribe to the {appserver_name} {appserver_version} repository using the following command:
+
[source,bash,subs="attributes+"]
----
$ sudo subscription-manager repos --enable=jb-eap-{appserver_version}-for-rhel-8-x86_64-rpms --enable=rhel-8-for-x86_64-baseos-rpms --enable=rhel-8-for-x86_64-appstream-rpms
----
Install the EAP 7 adapters for SAML using the following command:
.Procedure
. Install the EAP 7 adapters for SAML based on your version of Red Hat Enterprise Linux.
* Install on Red Hat Linux 7:
+
[source,bash,subs="attributes+"]
----
$ sudo yum install eap7-keycloak-saml-adapter-sso7_4
$ sudo yum install eap7-keycloak-saml-adapter-sso7_5
----
or use following one for Red Hat Enterprise Linux 8:
* Install on Red Hat Enterprise Linux 8:
+
[source,bash,subs="attributes+"]
----
$ sudo dnf install eap7-keycloak-adapter-sso7_4
$ sudo dnf install eap7-keycloak-adapter-sso7_5
----
+
NOTE: The default EAP_HOME path for the RPM installation is /opt/rh/eap7/root/usr/share/wildfly.
Run the appropriate module installation script.
For the SAML module, enter the following command:
. Run the installation script for the SAML module:
+
[source,bash,subs="attributes+"]
----
$ $EAP_HOME/bin/jboss-cli.sh -c --file=$EAP_HOME/bin/adapter-install-saml.cli
----
Your installation is complete.
Install the EAP 6 Adapters from an RPM:
[[_jboss6_adapter_rpm_saml]]
==== Installing JBoss EAP 6 Adapters from an RPM
NOTE: With Red Hat Enterprise Linux 7, the term channel was replaced with the term repository. In these instructions only the term repository is used.
You must subscribe to the JBoss EAP 6 repository before you can install the EAP 6 adapters from an RPM.
.Prerequisites
. Ensure that your Red Hat Enterprise Linux system is registered to your account using Red Hat Subscription Manager. For more information see the link:https://access.redhat.com/documentation/en-us/red_hat_subscription_management/1/html-single/quick_registration_for_rhel/index[Red Hat Subscription Management documentation].
You must subscribe to the JBoss EAP 6 repository before you can install the EAP 6 adapters from an RPM.
. If you are already subscribed to another JBoss EAP repository, you must unsubscribe from that repository first.
* Ensure that your Red Hat Enterprise Linux system is registered to your account using Red Hat Subscription Manager. For more information see the link:https://access.redhat.com/documentation/en-us/red_hat_subscription_management/1/html-single/quick_registration_for_rhel/index[Red Hat Subscription Management documentation].
Using Red Hat Subscription Manager, subscribe to the JBoss EAP 6 repository using the following command. Replace <RHEL_VERSION> with either 6 or 7 depending on your Red Hat Enterprise Linux version.
* If you are already subscribed to another JBoss EAP repository, you must unsubscribe from that repository first.
* Using Red Hat Subscription Manager, subscribe to the JBoss EAP 6 repository using the following command. Replace <RHEL_VERSION> with either 6 or 7 depending on your Red Hat Enterprise Linux version.
+
[source,bash,subs="attributes+"]
----
$ sudo subscription-manager repos --enable=jb-eap-6-for-rhel-<RHEL_VERSION>-server-rpms
----
Install the EAP 6 adapters for SAML using the following command:
.Procedure
. Install the EAP 6 adapters for SAML using the following command:
+
[source,bash,subs="attributes+"]
----
$ sudo yum install keycloak-saml-adapter-sso7_4-eap6
$ sudo yum install keycloak-saml-adapter-sso7_5-eap6
----
+
NOTE: The default EAP_HOME path for the RPM installation is /opt/rh/eap6/root/usr/share/wildfly.
Run the appropriate module installation script.
For the SAML module, enter the following command:
. Run the installation script for the SAML module:
+
[source,bash,subs="attributes+"]
----
$ $EAP_HOME/bin/jboss-cli.sh -c --file=$EAP_HOME/bin/adapter-install-saml.cli
----

72
securing_apps/topics/saml/java/jboss-adapter/jboss_adapter_installation.adoc
View file

@ -1,104 +1,106 @@
[[_saml-jboss-adapter-installation]]
===== Adapter Installation
==== Installing adapters from a ZIP file
Each adapter is a separate download on the {project_name} download site.
ifeval::[{project_community}==true]
NOTE: We only test and maintain adapter with the most recent version of WildFly available upon the release. Once new version of
WildFly is released, the current adapters become deprecated and support for them will be removed after next WildFly release.
The other alternative is to switch your applications from WildFly to the JBoss EAP, as the JBoss EAP adapter is supported for much longer period.
NOTE: We only test and maintain adapter with the most recent version of WildFly available upon the release. Once the new version of WildFly is released, the current adapters become deprecated and support for them will be removed after the next WildFly release.
The other alternative is to switch your applications from WildFly to the JBoss EAP, as the JBoss EAP adapter is supported for a much longer period.
Install on WildFly 9 or newer or on JBoss EAP 7:
.Procedure
. Install the adapter that applies to your application server from the link:https://www.keycloak.org/downloads[Downloads] site.
* Install on WildFly 9 or newer on JBoss EAP 7:
+
[source]
----
$ cd $WILDFLY_HOME
$ unzip keycloak-saml-wildfly-adapter-dist.zip
----
Install on JBoss EAP 6.x:
* Install on JBoss EAP 6.x:
+
[source]
----
$ cd $JBOSS_HOME
$ unzip keycloak-saml-eap6-adapter-dist.zip
----
+
These zip files create new JBoss Modules specific to the WildFly/JBoss EAP SAML Adapter within your WildFly or JBoss EAP distro.
endif::[]
ifeval::[{project_product}==true]
Install on JBoss EAP 7.x:
.Procedure
. Install the adapter that applies to your application server from the link:https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?downloadType=distributions&product=core.service.rhsso[Downloads] site.
* Install on JBoss EAP 7.x:
+
[source]
----
$ cd $EAP_HOME
$ unzip rh-sso-saml-eap7-adapter.zip
----
Install on JBoss EAP 6.x:
* Install on JBoss EAP 6.x:
+
[source]
+
----
$ cd $EAP_HOME
$ unzip rh-sso-saml-eap6-adapter.zip
----
These zip files create new JBoss Modules specific to the JBoss EAP SAML Adapter within your JBoss EAP distro.
+
These ZIP files create new JBoss Modules specific to the JBoss EAP SAML Adapter within your JBoss EAP distribution.
endif::[]
After adding the modules, you must then enable the {project_name} SAML Subsystem within your app server's server configuration: `domain.xml` or `standalone.xml`.
There is a CLI script that will help you modify your server configuration.
Start the server and run the script from the server's bin directory:
. Use a CLI script to enable the {project_name} SAML Subsystem within your app server's server configuration: `domain.xml` or `standalone.xml`.
+
Start the server and run the script that applies to your application server.
ifeval::[{project_community}==true]
.WildFly 11 or newer
* Install on WildFly 11 or newer.
+
[source]
----
$ cd $JBOSS_HOME
$ ./bin/jboss-cli.sh -c --file=bin/adapter-elytron-install-saml.cli
----
.WildFly 10 and older
* Install on WildFly 10 and older.
+
[source]
----
$ cd $JBOSS_HOME
$ ./bin/jboss-cli.sh -c --file=bin/adapter-install-saml.cli
----
+
NOTE: It is possible to use the legacy non-Elytron adapter on WildFly 11 or newer as well, meaning you can use `adapter-install-saml.cli`
even on those versions. However, we recommend to use the newer Elytron adapter.
endif::[]
ifeval::[{project_product}==true]
.JBoss EAP 7.1 or newer
* Use this command for JBoss EAP 7.1 or newer
+
[source]
----
$ cd $JBOSS_HOME
$ ./bin/jboss-cli.sh -c --file=bin/adapter-elytron-install-saml.cli
----
.JBoss EAP 7.0 and EAP 6.4
* Use this command for JBoss EAP 7.0 and EAP 6.4
+
[source]
----
$ cd $JBOSS_HOME
$ ./bin/jboss-cli.sh -c --file=bin/adapter-install-saml.cli
----
+
NOTE: It is possible to use the legacy non-Elytron adapter on JBoss EAP 7.1 or newer as well, meaning you can use `adapter-install-saml.cli`
even on those versions. However, we recommend to use the newer Elytron adapter.
+
endif::[]
The script will add the extension, subsystem, and optional security-domain as described below.
[source,xml]

2
securing_apps/topics/saml/java/jboss-adapter/required_per_war_configuration.adoc
View file

@ -1,5 +1,5 @@
===== Per WAR Configuration
===== Securing a WAR
This section describes how to secure a WAR directly by adding config and editing files within your WAR package.

10
securing_apps/topics/saml/java/jboss-adapter/securing_wars.adoc
View file

@ -1,7 +1,7 @@
===== Securing WARs via {project_name} SAML Subsystem
===== Securing WARs using the {project_name} SAML Subsystem
You do not have to crack open a WAR to secure it with {project_name}.
You do not have to open a WAR to secure it with {project_name}.
Alternatively, you can externally secure it via the {project_name} SAML Adapter Subsystem.
While you don't have to specify KEYCLOAK-SAML as an `auth-method`, you still have to define the `security-constraints` in `web.xml`.
You do not, however, have to create a `WEB-INF/keycloak-saml.xml` file.
@ -23,13 +23,13 @@ This metadata is instead defined within the XML in your server's `domain.xml` or
</secure-deployment>
</subsystem>
</profile>
----
----
The `secure-deployment` `name` attribute identifies the WAR you want to secure.
Its value is the `module-name` defined in `web.xml` with `.war` appended.
The rest of the configuration uses the same XML syntax as `keycloak-saml.xml` configuration defined in <<_saml-general-config,General Adapter Config>>.
An example configuration:
An example configuration:
[source,xml]
----
@ -79,4 +79,4 @@ An example configuration:
</SP>
</secure-deployment>
</subsystem>
----
----

8
securing_apps/topics/saml/java/jetty-adapter.adoc
View file

@ -1,7 +1,7 @@
[[_jetty_saml_adapter]]
==== Jetty SAML Adapters
==== Jetty SAML adapters
To be able to secure WAR apps deployed on Jetty you must install the {project_name} Jetty 9.x SAML adapter into your Jetty installation.
You then have to provide some extra configuration in each WAR you deploy to Jetty.
Let's go over these steps.
To be able to secure WAR apps deployed on Jetty you must install the {project_name} Jetty 9.x SAML adapter into your Jetty installation. You then provide some extra configuration in each WAR you deploy to Jetty.
Use the following installation and configuration procedures.

29
securing_apps/topics/saml/java/jetty-adapter/jetty9_installation.adoc
View file

@ -1,27 +1,30 @@
[[_jetty9_saml_adapter_installation]]
===== Jetty 9 Adapter Installation
===== Jetty 9 Installing the adapter
Keycloak has a separate SAML adapter for Jetty 9.x.
You then have to provide some extra configuration in each WAR you deploy to Jetty.
Let's go over these steps.
{project_name} has a separate SAML adapter for Jetty 9.x. Adapters are no longer included with the appliance or war distribution. Each adapter is a separate download on the Keycloak download site.
They are also available as a maven artifact.
Adapters are no longer included with the appliance or war distribution. Each adapter is a separate download on the Keycloak download site.
They are also available as a maven artifact.
You must unzip the Jetty 9.x distro into Jetty 9.x's root directory.
Including adapter's jars within your WEB-INF/lib directory will not work!
.Procedure
. Download the {project_name} Jetty 9.x adapter ZIP archive from the link:https://www.keycloak.org/downloads[Keycloak Downloads] site.
. Unzip the Jetty 9.x distro into Jetty 9.x's root directory.
+
====
[NOTE]
Including adapter's jars within your WEB-INF/lib directory will not work.
====
+
[source]
----
$ cd $JETTY_HOME
$ unzip keycloak-saml-jetty92-adapter-dist.zip
----
Next, you will have to enable the keycloak module for your jetty.base.
----
. Enable the keycloak module for your jetty.base.
+
[source]
----
$ cd your-base
$ java -jar $JETTY_HOME/start.jar --add-to-startd=keycloak
----
----

16
securing_apps/topics/saml/java/jetty-adapter/jetty9_per_war_config.adoc
View file

@ -1,12 +1,13 @@
[[_saml-jetty9-per-war]]
===== Jetty 9 Per WAR Configuration
===== Jetty 9 WAR Configuration
This section describes how to secure a WAR directly by adding config and editing files within your WAR package.
Use this procedure to secure a WAR directly.
The first thing you must do is create a `WEB-INF/jetty-web.xml` file in your WAR package.
.Procedure
. Create a `WEB-INF/jetty-web.xml` file in your WAR package.
This is a Jetty specific config file and you must define a Keycloak specific authenticator within it.
+
[source,xml]
----
<?xml version="1.0"?>
@ -21,12 +22,11 @@ This is a Jetty specific config file and you must define a Keycloak specific aut
</Configure>
----
Next you must create a `keycloak-saml.xml` adapter config file within the `WEB-INF` directory of your WAR.
. Create a `keycloak-saml.xml` adapter config file within the `WEB-INF` directory of your WAR.
The format of this config file is described in the <<_saml-general-config,General Adapter Config>> section.
Finally you must specify both a `login-config` and use standard servlet security to specify role-base constraints on your URLs.
Here's an example:
. Specify both a `login-config` and use standard servlet security to specify role-base constraints on your URLs. Here's an example:
+
[source,xml]
----
<web-app xmlns="http://java.sun.com/xml/ns/javaee"

4
securing_apps/topics/saml/java/logout.adoc
View file

@ -6,7 +6,7 @@ the browser at any url of your web application that has a security constraint an
This will log you out if you have an SSO session with your browser.
[[_saml_logout_in_cluster]]
===== Logout in Clustered Environment
===== Logout in clustered environment
Internally, the SAML adapter stores a mapping between the SAML session index, principal name (when known), and HTTP session ID.
This mapping can be maintained in JBoss application server family (WildFly 10/11, EAP 6/7) across cluster for distributable
@ -63,7 +63,7 @@ The data center 2 has to log out all sessions that are present in data center 1
share HTTP sessions).
To cover this case, the SAML session cache described <<_saml_logout_in_cluster,above>> needs to be replicated
not only within individual clusters but across all the data centers e.g.
not only within individual clusters but across all the data centers for example
https://access.redhat.com/documentation/en-us/red_hat_data_grid/6.6/html/administration_and_configuration_guide/chap-externalize_sessions#Externalize_HTTP_Session_from_JBoss_EAP_6.x_to_JBoss_Data_Grid[via standalone Infinispan/JDG server]:
1. A cache has to be added to the standalone Infinispan/JDG server.

12
securing_apps/topics/saml/java/saml-jboss-adapter.adoc
View file

@ -1,10 +1,10 @@
[[_saml_jboss_adapter]]
ifeval::[{project_community}==true]
==== JBoss EAP/WildFly Adapter
==== JBoss EAP/WildFly adapter
endif::[]
ifeval::[{project_product}==true]
==== JBoss EAP Adapter
==== JBoss EAP adapter
endif::[]
ifeval::[{project_community}==true]
@ -15,4 +15,10 @@ To be able to secure WAR apps deployed on JBoss EAP, you must install and config
endif::[]
You then provide a keycloak config, `/WEB-INF/keycloak-saml.xml` file in your WAR and change the auth-method to KEYCLOAK-SAML within web.xml.
Both methods are described in this section.
You install the adapters by using a ZIP file or an RPM.
* <<_saml-jboss-adapter-installation, Installing adapters from a ZIP file>>
* <<_jboss7_adapter_rpm_saml, Installing JBoss EAP 7 Adapters from an RPM>>
* <<_jboss6_adapter_rpm_saml, Installing JBoss EAP 6 Adapters from an RPM>>

2
securing_apps/topics/saml/java/servlet-filter-adapter.adoc
View file

@ -1,5 +1,5 @@
==== Java Servlet Filter Adapter
==== Java Servlet filter adapter
If you want to use SAML with a Java servlet application that doesn't have an adapter for that servlet platform, you can
opt to use the servlet filter adapter that {project_name} has.

2
securing_apps/topics/saml/java/tomcat-adapter.adoc
View file

@ -4,5 +4,5 @@
To be able to secure WAR apps deployed on Tomcat 7, 8 and 9 you must install the Keycloak Tomcat 7 SAML adapter or Keycloak Tomcat SAML adapter into your Tomcat installation.
You then have to provide some extra configuration in each WAR you deploy to Tomcat.
Let's go over these steps.

30
securing_apps/topics/saml/java/tomcat-adapter/tomcat_adapter_installation.adoc
View file

@ -1,28 +1,34 @@
[[_saml-tomcat-adapter-installation]]
===== Adapter Installation
===== Installing the adapter
Adapters are no longer included with the appliance or war distribution.
Each adapter is a separate download on the Keycloak download site.
They are also available as a maven artifact.
Each adapter is a separate download on the Keycloak Downloads site.
They are also available as a maven artifact.
You must unzip the adapter distro into Tomcat's `lib/` directory.
Including adapter's jars within your WEB-INF/lib directory will not work! The Keycloak SAML adapter is implemented as
a Valve and valve code must reside in Tomcat's main lib/ directory.
.Procedure
Install on Tomcat 7:
. Download the adapter for the Tomcat version on your system from the link:https://www.keycloak.org/downloads[Keycloak Downloads] site:
. Install on the Tomcat version on your system:
* Install on Tomcat 7:
+
[source]
----
$ cd $TOMCAT_HOME/lib
$ unzip keycloak-saml-tomcat7-adapter-dist.zip
----
Install on Tomcat 8 or 9:
[source]
----
* Install on Tomcat 8 or 9:
+
[source]
----
$ cd $TOMCAT_HOME/lib
$ unzip keycloak-saml-tomcat-adapter-dist.zip
----
====
[NOTE]
Including the adapter's jars within your WEB-INF/lib directory will not work. The Keycloak SAML adapter is implemented as a Valve and valve code must reside in Tomcat's main lib/ directory.
====

18
securing_apps/topics/saml/java/tomcat-adapter/tomcat_adapter_per_war_config.adoc
View file

@ -1,11 +1,13 @@
===== Per WAR Configuration
===== Securing a WAR
This section describes how to secure a WAR directly by adding config and editing files within your WAR package.
Use this procedure to secure a WAR directly by adding config and editing files within your WAR package.
The first thing you must do is create a `META-INF/context.xml` file in your WAR package.
.Procedure
. Create a `META-INF/context.xml` file in your WAR package.
This is a Tomcat specific config file and you must define a Keycloak specific Valve.
+
[source,xml]
----
<Context path="/your-context-path">
@ -13,12 +15,12 @@ This is a Tomcat specific config file and you must define a Keycloak specific Va
</Context>
----
Next you must create a `keycloak-saml.xml` adapter config file within the `WEB-INF` directory of your WAR.
. Create a `keycloak-saml.xml` adapter config file within the `WEB-INF` directory of your WAR.
The format of this config file is described in the <<_saml-general-config,General Adapter Config>> section.
Finally you must specify both a `login-config` and use standard servlet security to specify role-base constraints on your URLs.
. Specify both a `login-config` and use standard servlet security to specify role-base constraints on your URLs.
Here's an example:
+
[source,xml]
----
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
@ -52,4 +54,4 @@ Here's an example:
</web-app>
----
If the `keycloak-saml.xml` does not explicitly set `assertionConsumerServiceUrl`, the SAML adapter will implicitly listen for SAML assertions at the location `/my-context-path/saml`. This has to match `Master SAML Processing URL` in the IDP realm/client settings, e.g. `\http://sp.domain.com/my-context-path/saml`. If not, Tomcat will probably redirect infinitely to the IDP login service, as it does not receive the SAML assertion after the user logged in.
If the `keycloak-saml.xml` does not explicitly set `assertionConsumerServiceUrl`, the SAML adapter will implicitly listen for SAML assertions at the location `/my-context-path/saml`. This has to match `Master SAML Processing URL` in the IDP realm/client settings, for example `\http://sp.domain.com/my-context-path/saml`. If not, Tomcat will probably redirect infinitely to the IDP login service, as it does not receive the SAML assertion after the user logged in.

79
securing_apps/topics/saml/mod-auth-mellon.adoc
View file

@ -4,7 +4,7 @@
The https://github.com/latchset/mod_auth_mellon[mod_auth_mellon] module is an Apache HTTPD plugin for SAML. If your language/environment supports using Apache HTTPD as a proxy, then you can use mod_auth_mellon to secure your web application with SAML. For more details on this module see the _mod_auth_mellon_ GitHub repo.
To configure mod_auth_mellon you'll need:
To configure mod_auth_mellon you need:
* An Identity Provider (IdP) entity descriptor XML file, which describes the connection to {project_name} or another SAML IdP
* An SP entity descriptor XML file, which describes the SAML connections and configuration for the application you are securing.
@ -15,14 +15,17 @@ To configure mod_auth_mellon you'll need:
ifeval::[{project_community}==true]
If you have already defined and registered the client application within a realm on the {project_name} application server, {project_name} can generate all the files you need except the Apache HTTPD module configuration.
To generate the Apache HTTPD module configuration, complete the following steps:
Perform the following procedure to generate the Apache HTTPD module configuration.
. Go to the Installation page of your SAML client and select the Mod Auth Mellon files option.
.Procedure
. Go to the Installation page of your SAML client.
. Select the *Mod Auth Mellon* files option.
+
.mod_auth_mellon config download
image:{project_images}/mod-auth-mellon-config-download.png[]
. Click *Download* to download a zip file that contains the XML descriptor and PEM files you need.
. Click *Download* to download a ZIP file that contains the XML descriptor and PEM files you need.
endif::[]
==== Configuring mod_auth_mellon with {project_name}
@ -35,7 +38,7 @@ There are two hosts involved:
All of the following steps need to performed on $sp_host with root privileges.
===== Installing the Packages
===== Installing the packages
To install the necessary packages, you will need:
@ -47,9 +50,9 @@ To install the necessary packages, run this command:
yum install httpd mod_auth_mellon mod_ssl openssl
===== Creating a Configuration Directory for Apache SAML
===== Creating a configuration directory for Apache SAML
It is advisable to keep configuration files related to Apache's use of SAML in one location.
It is advisable to keep configuration files related to Apache's use of SAML in one location.
Create a new directory named saml2 located under the Apache configuration root /etc/httpd:
@ -68,7 +71,9 @@ Apache configuration directives typically follow a hierarchical tree structure i
This example has just one protected location: \https://$sp_host/private.
To configure the Mellon service provider, complete the following steps:
To configure the Mellon service provider, perform the following procedure.
.Procedure
. Create the file /etc/httpd/conf.d/mellon.conf with this content:
@ -110,7 +115,7 @@ MellonCookieSameSite none
The support for this configuration is available in the _mod_auth_mellon_ module from version 0.16.0.
===== Creating the Service Provider Metadata
===== Creating the Service Provider metadata
In SAML IdPs and SPs exchange SAML metadata, which is in XML format. The schema for the metadata is a standard, thus assuring participating SAML entities can consume each other's metadata. You need:
@ -131,9 +136,11 @@ SAML IdPs and SPs identify themselves using a unique name known as an EntityID.
* The EntityID, which is typically the URL of the SP, and often the URL of the SP where the SP metadata can be retrieved
* The URL where SAML messages for the SP will be consumed, which Mellon calls the MellonEndPointPath.
To create the SP metadata, complete the following steps:
To create the SP metadata, perform the following procedure.
. Create a few helper shell variables:
.Procedure
. Create a few helper shell variables:
+
[source]
----
@ -165,60 +172,72 @@ Assumption: The {project_name} IdP has already been installed on the $idp_host.
{project_name} supports multiple tenancy where all users, clients, and so on are grouped in what is called a realm. Each realm is independent of other realms. You can use an existing realm in your {project_name}, but this example shows how to create a new realm called test_realm and use that realm.
All these operations are performed using the {project_name} administration web console. You must have the admin username and password for $idp_host.
All these operations are performed using the {project_name} Admin Console. You must have the admin username and password for $idp_host to perform the following procedure.
To complete the following steps:
.Procedure
. Open the Admin Console and log on by entering the admin username and password.
+
After logging into the administration console there will be an existing realm. When {project_name} is first set up a root realm, master, is created by default. Any previously created realms are listed in the upper left corner of the administration console in a drop-down list.
After logging into the Admin Console, there will be an existing realm. When {project_name} is first set up a root realm, master, is created by default. Any previously created realms are listed in the upper left corner of the Admin Console in a drop-down list.
. From the realm drop-down list select *Add realm*.
. In the Name field type `test_realm` and click *Create*.
====== Adding the Mellon Service Provider as a Client of the Realm
====== Adding the Mellon Service Provider as a client of the realm
In {project_name} SAML SPs are known as clients. To add the SP we must be in the Clients section of the realm.
. Click the Clients menu item on the left and click *Create* in the upper right corner to create a new client.
====== Adding the Mellon SP Client
====== Adding the Mellon SP client
To add the Mellon SP client, complete the following steps:
To add the Mellon SP client, perform the following procedure.
. Set the client protocol to SAML. From the Client Protocol drop down list, select *saml*.
. Provide the Mellon SP metadata file created above (/etc/httpd/saml2/mellon_metadata.xml). Depending on where your browser is running you might have to copy the SP metadata from $sp_host to the machine on which your browser is running so the browser can find the file.
.Procedure
. Set the client protocol to SAML.
. From the Client Protocol drop down list, select *saml*.
. Provide the Mellon SP metadata file created above (/etc/httpd/saml2/mellon_metadata.xml).
+
Depending on where your browser is running you might have to copy the SP metadata from $sp_host to the machine on which your browser is running so the browser can find the file.
. Click *Save*.
====== Editing the Mellon SP Client
====== Editing the Mellon SP client
There are several client configuration parameters we suggest setting:
Use this procedure to set important client configuration parameters.
* Ensure "Force POST Binding" is On.
* Add paosResponse to the Valid Redirect URIs list:
.Procedure
. Ensure "Force POST Binding" is On.
. Add paosResponse to the Valid Redirect URIs list:
. Copy the postResponse URL in "Valid Redirect URIs" and paste it into the empty add text fields just below the "+".
. Change "postResponse" to "paosResponse". (The paosResponse URL is needed for SAML ECP.)
. Change "postResponse" to "paosResponse". (The paosResponse URL is needed for SAML ECP.)
. Click *Save* at the bottom.
Many SAML SPs determine authorization based on a user's membership in a group. The {project_name} IdP can manage user group information but it does not supply the user's groups unless the IdP is configured to supply it as a SAML attribute.
To configure the IdP to supply the user's groups as as a SAML attribute, complete the following steps:
Perform the following procedure to configure the IdP to supply the user's groups as as a SAML attribute.
.Procedure
. Click the Mappers tab of the client.
. In the upper right corner of the Mappers page, click *Create*.
. From the Mapper Type drop-down list select *Group list*.
. From the Mapper Type drop-down list select *Group list*.
. Set Name to "group list".
. Set the SAML attribute name to "groups".
. Click *Save*.
The remaining steps are performed on $sp_host.
====== Retrieving the Identity Provider Metadata
====== Retrieving the Identity Provider metadata
Now that you have created the realm on the IdP you need to retrieve the IdP metadata associated with it so the Mellon SP recognizes it. In the /etc/httpd/conf.d/mellon.conf file created previously, the MellonIdPMetadataFile is specified as /etc/httpd/saml2/idp_metadata.xml but until now that file has not existed on $sp_host. To get that file we will retrieve it from the IdP.
Now that you have created the realm on the IdP you need to retrieve the IdP metadata associated with it so the Mellon SP recognizes it. In the /etc/httpd/conf.d/mellon.conf file created previously, the MellonIdPMetadataFile is specified as /etc/httpd/saml2/idp_metadata.xml but until now that file has not existed on $sp_host.
. Retrieve the file from the IdP by substituting $idp_host with the correct value:
Use this procedure to retrieve that file from the IdP.
.Procedure
. Use this command, substituting with the correct value for $idp_host:
+
[source]
----
@ -228,7 +247,7 @@ https://$idp_host/auth/realms/test_realm/protocol/saml/descriptor
+
Mellon is now fully configured.
. To run a syntax check for Apache configuration files:
. To run a syntax check for Apache configuration files, use this command:
+
[source]
----

5
securing_apps/topics/saml/saml-overview.adoc
View file

@ -1,4 +1,3 @@
== SAML
== Using SAML to secure applications and services
This section describes how you can secure applications and services with SAML using either {project_name} client adapters or generic
SAML provider libraries.
This section describes how you can secure applications and services with SAML using either {project_name} client adapters or generic SAML provider libraries.

187
securing_apps/topics/token-exchange/token-exchange.adoc
View file

@ -1,7 +1,7 @@
[[_token-exchange]]
== Token Exchange
== Using token exchange
:tech_feature_name: Token Exchange
:tech_feature_setting: -Dkeycloak.profile.feature.token_exchange=enabled
@ -9,9 +9,11 @@ include::../templates/techpreview.adoc[]
[NOTE]
====
In order to use token exchange you should also enable the `token_exchange` feature. Please, take a look at link:{installguide_profile_link}[{installguide_profile_name}].
In order to use token exchange you should also enable the `token_exchange` feature. Please, take a look at link:{installguide_profile_link}[{installguide_profile_name}].
====
=== How token exchange works
In {project_name}, token exchange is the process of using a set of credentials or token to obtain an entirely different token.
A client may want to invoke on a less trusted application so it may want to downgrade the current token it has.
A client may want to exchange a {project_name} token for a token stored for a linked social provider account.
@ -35,7 +37,9 @@ It accepts form parameters (`application/x-www-form-urlencoded`) as input and th
Token exchange is a client endpoint so requests must provide authentication information for the calling client.
Public clients specify their client identifier as a form parameter. Confidential clients can also use form parameters
to pass their client id and secret, Basic Auth, or however your admin has configured the client authentication flow in your
realm. Here's a list of form parameters
realm.
==== Form parameters
client_id::
_REQUIRED MAYBE._ This parameter is required for clients using form parameters for authentication. If you are using
@ -76,6 +80,8 @@ scope::
NOTE: We currently only support OpenID Connect and OAuth exchanges. Support for SAML based clients and identity providers may be added in the future depending on user demand.
==== Responses from a token exchange request
A successful response from an exchange invocation will return the HTTP 200 response code with a content type that
depends on the `requested-token-type` and `requested_issuer` the client asks for. OAuth requested token types will return
a JSON document as described in the link:https://datatracker.ietf.org/doc/html/draft-ietf-oauth-token-exchange-16[OAuth Token Exchange] specification.
@ -117,55 +123,63 @@ For simplicity's sake, let's call a token minted by the current realm as an _int
an external realm or identity provider as an _external_ token.
=== Internal Token to Internal Token Exchange
=== Internal token to internal token exchange
With an internal token to token exchange you have an existing token minted to a specific client and you want to exchange
this token for a new one minted for a different target client. Why would you want to do this? This generally happens
this token for a new one minted for a different target client. Why would you want to do this? This generally happens+
when a client has a token minted for itself, and needs to make additional requests to other applications that require different
claims and permissions within the access token. Other reasons this type of exchange might be required is if you
need to perform a "permission downgrade" where your app needs to invoke on a less trusted app and you don't want
to propagate your current access token.
[[_client_to_client_permission]]
==== Granting Permission for the Exchange
==== Granting permission for the exchange
Clients that want to exchange tokens for a different client need to be authorized in the admin console to do so.
You'll need to define a `token-exchange` fine grain permission in the target client you want permission to exchange to.
Clients that want to exchange tokens for a different client need to be authorized in the Admin Console.
You need to define a `token-exchange` fine grain permission in the target client you want permission to exchange to.
.Target Client Permission
image:{project_images}/exchange-target-client-permission-unset.png[]
image:{project_images}/exchange-target-client-permission-unset.png[Target Client Permission]
Toggle the `Permissions Enabled` switch to ON.
.Procedure
. Toggle *Permissions Enabled* to *ON*.
+
.Target Client Permission
image:{project_images}/exchange-target-client-permission-set.png[]
+
That page displays a *token-exchange* link.
You should see a `token-exchange` link on the page. Click that to start defining the permission. It will bring you
to this page.
. Click that link to start defining the permission.
+
This setup page displays.
+
.Target Client Exchange Permission Setup
image:{project_images}/exchange-target-client-permission-setup.png[]
image:{project_images}/exchange-target-client-permission-setup.png[Target Client Exchange Permission Setup]
You'll have to define a policy for this permission. Click the `Authorization` link, go to the `Policies` tab and create
a `Client` Policy.
. Define a policy for this permission by clicking the *Authorization* link
. Click the *Policies* tab.
. Create a *Client* Policy.
+
.Client Policy Creation
image:{project_images}/exchange-target-client-policy.png[]
Here you enter in the starting client, that is the authenticated client that is requesting a token exchange. After you
create this policy, go back to the target client's `token-exchange` permission and add the client policy you just
defined.
. Enter in the starting client that is the authenticated client that is requesting a token exchange.
. After you create this policy, go back to the target client's *token-exchange* permission and add the client policy you just defined.
+
.Apply Client Policy
image:{project_images}/exchange-target-client-exchange-apply-policy.png[]
Your client now has permission to invoke. If you do not do this correctly, you will get a 403 Forbidden response if you
try to make an exchange.
==== Making the Request
==== Making the request
When your client is exchanging an existing token for a token targeting another client, you must use the `audience` parameter.
This parameter must be the client identifier for the target client that you configured in the admin console.
When your client is exchanging an existing token for a token targeting another client, you use the `audience` parameter.
This parameter must be the client identifier for the target client that you configured in the Admin Console.
[source,bash]
----
@ -193,10 +207,10 @@ an example JSON response you get back from this call.
}
----
=== Internal Token to External Token Exchange
=== Internal token to external token exchange
You can exchange a realm token for an externl token minted by an external identity provider. This external identity provider
must be configured within the `Identity Provider` section of the admin console. Currently only OAuth/OpenID Connect based external
must be configured within the `Identity Provider` section of the Admin Console. Currently only OAuth/OpenID Connect based external
identity providers are supported, this includes all social providers. {project_name} does not perform a backchannel exchange to the external provider. So if the account
is not linked, you will not be able to get the external token. To be able to obtain an external token one of
these conditions must be met:
@ -212,47 +226,47 @@ If the account is not linked, the exchange response will contain a link you can
discussed more in the <<_internal_external_making_request, Making the Request>> section.
[[_grant_permission_external_exchange]]
==== Granting Permission for the Exchange
==== Granting permission for the exchange
Internal to external token exchange requests will be denied with a 403, Forbidden response until you grant
permission for the calling client to exchange tokens with the external identity provider. To grant permission
to the client you must go to the identity provider's configuration page to the `Permissions` tab.
Internal to external token exchange requests will be denied with a 403, Forbidden response until you grant permission for the calling client to exchange tokens with the external identity provider. To grant permission to the client, you go to the identity provider's configuration page to the *Permissions* tab.
.Identity Provider Permission
image:{project_images}/exchange-idp-permission-unset.png[]
Toggle the `Permissions Enabled` switch to true.
.Procedure
. Toggle *Permissions Enabled* to *ON*.
+
.Identity Provider Permission
image:{project_images}/exchange-idp-permission-set.png[]
+
The page displays *token-exchange* link.
You should see a `token-exchange` link on the page. Click that to start defining the permission. It will bring you
to this page.
. Click the link to start defining the permission.
+
This setup page appears.
+
.Identity Provider Exchange Permission Setup
image:{project_images}/exchange-idp-permission-setup.png[]
You'll have to define a policy for this permission. Click the `Authorization` link, go to the `Policies` tab and create
a `Client` Policy.
image:{project_images}/exchange-idp-permission-setup.png[Identity Provider Exchange Permission Setup]
. Click the *Authorization* link and go to the *Policies* tab to create a client policy.
+
.Client Policy Creation
image:{project_images}/exchange-idp-client-policy.png[]
image:{project_images}/exchange-idp-client-policy.png[Client Policy Creation]
Here you enter in the starting client, that is the authenticated client that is requesting a token exchange. After you
create this policy, go back to the identity providers's `token-exchange` permission and add the client policy you just
defined.
. Enter the starting client that is the authenticated client that is requesting a token exchange.
. Return to the identity provider's *token-exchange* permission and add the client policy you just defined.
+
.Apply Client Policy
image:{project_images}/exchange-idp-apply-policy.png[]
image:{project_images}/exchange-idp-apply-policy.png[Apply Client Policy]
Your client now has permission to invoke. If you do not do this correctly, you will get a 403 Forbidden response if you
try to make an exchange.
Your client now has permission to invoke. If you do not do this correctly, you will get a 403 Forbidden response if you try to make an exchange.
[[_internal_external_making_request]]
==== Making the Request
==== Making the request
When your client is exchanging an existing internal token to an external one, you must provide the
`requested_issuer` parameter. The parameter must be the alias of a configured identity provider.
When your client is exchanging an existing internal token to an external one, you provide the `requested_issuer` parameter. The parameter must be the alias of a configured identity provider.
[source,bash]
----
@ -266,7 +280,6 @@ curl -X POST \
http://localhost:8080/auth/realms/myrealm/protocol/openid-connect/token
----
The `subject_token` parameter must be an access token for the target realm. The `requested_token_type` parameter
must be `urn:ietf:params:oauth:token-type:access_token` or left blank. No other requested token type is supported
at this time. Here's
@ -294,11 +307,11 @@ this JSON document:
----
The `error` claim will be either `token_expired` or `not_linked`. The `account-link-url` claim is provided
so that the client can perform link:{developerguide_link}[Client Initiated Account Linking]. Most (all?)
providers are requiring linking through browser OAuth protocol. With the `account-link-url` just add a `redirect_uri`
so that the client can perform link:{developerguide_link}[Client Initiated Account Linking]. Most, if not all,
providers require linking through browser OAuth protocol. With the `account-link-url` just add a `redirect_uri`
query parameter to it and you can forward browsers to perform the link.
=== External Token to Internal Token Exchange
=== External token to internal token exchange
You can trust and exchange external tokens minted by external identity providers for internal tokens. This can be
used to bridge between realms or just to trust tokens from your social provider. It works similarly to an identity provider
@ -313,24 +326,23 @@ and or refresh token depending on the `requested_token_type` parameter value. Y
user session will remain active until it times out or until you call the logout endpoint of the realm passing this
new access token.
These types of changes required a configured identity provider in the admin console.
These types of changes required a configured identity provider in the Admin Console.
NOTE: SAML identity providers are not supported at this time. Twitter tokens cannot be exchanged either.
==== Granting permission for the exchange
==== Granting Permission for the Exchange
Before external token exchanges can be done, you must grant permission for the calling client to make the exchange. This
Before external token exchanges can be done, you grant permission for the calling client to make the exchange. This
permission is granted in the same manner as <<_grant_permission_external_exchange, internal to external permission is granted>>.
If you also provide an `audience` parameter whose value points to a different client other than the calling one, you
must also grant the calling client permission to exchange to the target client specific in the `audience` parameter. How
to do this is <<_client_to_client_permission, discussed earlier>> in this section.
==== Making the Request
==== Making the request
The `subject_token_type` must either be `urn:ietf:params:oauth:token-type:access_token` or `urn:ietf:params:oauth:token-type:jwt`.
If the type is `urn:ietf:params:oauth:token-type:access_token` you must specify the `subject_issuer` parameter and it must be the
If the type is `urn:ietf:params:oauth:token-type:access_token` you specify the `subject_issuer` parameter and it must be the
alias of the configured identity provider. If the type is `urn:ietf:params:oauth:token-type:jwt`, the provider will be matched via
the `issuer` claim within the JWT which must be the alias of the provider, or a registered issuer within the providers configuration.
@ -377,14 +389,14 @@ For example, you may have an admin application that needs to impersonate a user
a problem.
==== Granting Permission for the Exchange
==== Granting permission for the exchange
The user that the subject token represents must have permission to impersonate other users. See the
link:{adminguide_link}[{adminguide_name}] on how to enable this permission. It can be done through a role or through
fine grain admin permissions.
==== Making the Request
==== Making the request
Make the request as described in other chapters except additionally specify the `requested_subject` parameter. The
value of this parameter must be a username or user id.
@ -413,40 +425,50 @@ is able to authenticate users itself, but not able to obtain a token.
WARNING: It is very risky to enable direct naked impersonation for a client. If the client's credentials are ever
stolen, that client can impersonate any user in the system.
==== Granting Permission for the Exchange
==== Granting permission for the exchange
If the `audience` parameter is provided, then the calling client must have permission to exchange to the client. How
to set this up is discussed earlier in this chapter.
Additionally, the calling client must be granted permission to impersonate users. In the admin console, go to the
`Users` screen and click on the `Permissions` tab.
Additionally, the calling client must be granted permission to impersonate users. In the Admin Console.
.Users Permission
image:{project_images}/exchange-users-permission-unset.png[]
.Procedure
Toggle the `Permissions Enabled` switch to true.
. Click *Users* in the menu.
. Click the *Permissions* tab.
+
.User Permissions
image:{project_images}/exchange-users-permission-unset.png[User Permissions]
. Toggle *Permissions Enabled* to true.
+
.Identity Provider Permission
image:{project_images}/exchange-users-permission-set.png[]
+
The page displays an *impersonation* link.
You should see a `impersonation` link on the page. Click that to start defining the permission. It will bring you
to this page.
. Click that link to start defining the permission.
+
This setup page displays.
+
.Users Impersonation Permission Setup
image:{project_images}/exchange-users-permission-setup.png[]
image:{project_images}/exchange-users-permission-setup.png[Users Impersonation Permission Setup]
You'll have to define a policy for this permission. Click the `Authorization` link, go to the `Policies` tab and create
a `Client` Policy.
. Click the *Authorization* link
. Go to the *Policies* tab and create a client policy.
+
.Client Policy Creation
image:{project_images}/exchange-users-client-policy.png[]
image:{project_images}/exchange-users-client-policy.png[Client Policy Creation]
Here you enter in the starting client, that is the authenticated client that is requesting a token exchange. After you
create this policy, go back to the users' `impersonation` permission and add the client policy you just
. Enter the starting client that is the authenticated client that is requesting a token exchange.
. Return to the users' *impersonation* permission and add the client policy you just
defined.
+
.Apply Client Policy
image:{project_images}/exchange-users-apply-policy.png[]
image:{project_images}/exchange-users-apply-policy.png[Apply Client Policy]
Your client now has permission to impersonate users. If you do not do this correctly, you will get a 403 Forbidden response if you
try to make this type of exchange.
@ -454,7 +476,7 @@ try to make this type of exchange.
NOTE: Public clients are not allowed to do direct naked impersonations.
==== Making the Request
==== Making the request
To make the request, simply specify the `requested_subject` parameter. This must be the username or user id of
a valid user. You can also specify an `audience` parameter if you wish.
@ -469,16 +491,16 @@ curl -X POST \
http://localhost:8080/auth/realms/myrealm/protocol/openid-connect/token
----
=== Expand Permission Model With Service Accounts
=== Expand permission model with service accounts
When granting clients permission to exchange, you don't necessarily have to manually enable those permissions for each and every client.
When granting clients permission to exchange, you don't necessarily manually enable those permissions for each and every client.
If the client has a service account associated with it, you can use a role to group permissions together and assign exchange permissions
by assigning a role to the client's service account. For example, you might define a `naked-exchange` role and any service account that has that
role can do a naked exchange.
=== Exchange Vulnerabilities
=== Exchange vulnerabilities
When you start allowing token exchanges, there's various things you have to both be aware of and careful of.
When you start allowing token exchanges, there are various things you have to both be aware of and careful of.
The first is public clients. Public clients do not have or require a client credential in order to perform an exchange. Anybody that has a valid
token will be able to __impersonate__ the public client and perform the exchanges that public client is allowed to perform. If there
@ -493,8 +515,3 @@ Direct naked exchanges are quite dangerous. You are putting a lot of trust in t
its client credentials. If those credentials are leaked, then the thief can impersonate anybody in your system. This is in direct
contrast to confidential clients that have existing tokens. You have two factors of authentication, the access token and the client
credentials, and you're only dealing with one user. So use direct naked exchanges sparingly.