Chapter 13. Managing OpenID Connect and SAML Clients

To protect an application that uses the OpenID connect protocol, you create a client.

This action creates the client and bring you to the Settings tab, where you can perform Basic configuration.

The Settings tab includes many options to configure this client.

After completing the fields on the Settings tab, you can use the other tabs to perform advanced configuration.

If the Client authentication of the client is set to ON, the credentials of the client must be configured under the Credentials tab.

The Client Authenticator drop-down list specifies the type of credential to use for your client.

Client ID and Secret

This choice is the default setting. The secret is automatically generated. Click Regenerate to recreate the secret if necessary.

Signed JWT issued by the client

Signed JWT allows a client to authenticate with self-signed client assertions. This enables the client to authenticate without a shared secret.

In this authenticator you can enforce the Signature algorithm used by the client (any algorithm is valid by default) and the Max expiration allowed for the JWT token (tokens received after this period will not be accepted because they are too old, note that tokens should be issued right before the authentication, 60 seconds by default).

When choosing this credential type you will have to also generate a private key and certificate for the client in the tab Keys. The private key will be used to sign the JWT, while the certificate is used by the server to verify the signature.

Click on the Generate new keys button to start this process.

When you generate the keys, Red Hat build of Keycloak will store the certificate and you download the private key and certificate for your client.

You can also generate keys using an external tool and then import the client’s certificate by clicking Import Certificate.

Importing a certificate is unnecessary if you click Use JWKS URL. In this case, you can provide the URL where the public key is published in JWK format. With this option, if the key is ever changed, Red Hat build of Keycloak reimports the key.

If you are using a client secured by Red Hat build of Keycloak adapter, you can configure the JWKS URL in this format, assuming that https://myhost.com/myapp is the root URL of your client application:

https://myhost.com/myapp/k_jwks

https://myhost.com/myapp/k_jwks

See Server Developer Guide for more details.

Signed JWT issued by an Identity Provider

Signed JWT allows a client to authenticate with client assertions issued by an identity provider. Example use-cases include:

Before using this authentication mechanism, an identity provider capable of verifying client assertions should be configured.

The identity providers which support client assertions are:

Signed JWT with Client Secret

If you select this option, you can use a JWT signed by client secret instead of the private key.

The client secret will be used to sign the JWT by the client.

Like in the Signed JWT authenticator you can configure the Signature algorithm and the Max expiration for the JWT token.

X509 Certificate

Red Hat build of Keycloak will validate if the client uses proper X509 certificate during the TLS Handshake.

The validator also checks the Subject DN field of the certificate with a configured regexp validation expression. For some use cases, it is sufficient to accept all certificates. In that case, you can use (.*?)(?:$) expression.

Two ways exist for Red Hat build of Keycloak to obtain the Client ID from the request:

DPoP binds an access token and a refresh token together with the public part of a client’s key pair. This binding prevents an attacker from using stolen tokens.

This type of token is a holder-of-key token. Unlike bearer tokens, the recipient of a holder-of-key token can verify if the sender of the token is legitimate.

If you enable Require DPoP bound tokens in the Admin Console Settings tab under Capability config, the workflow is:

If verification fails, Red Hat build of Keycloak rejects the token.

If Require DPoP bound tokens is off, the client can still send DPoP proof in the token request. In that case, Red Hat build of Keycloak verifies DPoP proof and will add the thumbprint to the token. Also, if the switch is off, DPoP binding is not enforced by the Red Hat build of Keycloak server for this client. It is recommended to have this switch on if you want to make sure that particular client always uses DPoP binding.

Note that this Red Hat build of Keycloak switch maps to the switch dpop_bound_access_tokens introduced in the DPoP specification in client registration metadata.

In the following cases, Red Hat build of Keycloak verifies the client sending the access token or the refresh token:

Red Hat build of Keycloak also provides the client policy executor dpop-bind-enforcer. With this executor, you can specify the following:

For the details, see Client Policies, which contains general details on how to configure and set up client policies in your realm.

See OAuth 2.0 Demonstrating Proof of Possession (DPoP) specification for more details about DPoP.

For a client with Confidential Client authentication Red Hat build of Keycloak supports the functionality of rotating client secrets through Client Policies.

The client secrets rotation policy provides greater security in order to alleviate problems such as secret leakage. Once enabled, Red Hat build of Keycloak supports up to two concurrently active secrets for each client. The policy manages rotations according to the following settings:

When a client secret rotation occurs, a new main secret is generated and the old client main secret becomes the secondary secret with a new expiration date.

The following is an example of defining a secret rotation policy:

Each OIDC client has a built-in service account. Use this service account to obtain an access token.

Roles from access tokens are the intersection of:

The REST URL to invoke is /realms/{realm-name}/protocol/openid-connect/token. This URL must be invoked as a POST request and requires that you post the client credentials with the request.

By default, client credentials are represented by the clientId and clientSecret of the client in the Authorization: Basic header but you can also authenticate the client with a signed JWT assertion or any other custom mechanism for client authentication.

You also need to set the grant_type parameter to "client_credentials" as per the OAuth2 specification.

For example, the POST invocation to retrieve a service account can look like this:

    POST /realms/demo/protocol/openid-connect/token
    Authorization: Basic cHJvZHVjdC1zYS1jbGllbnQ6cGFzc3dvcmQ=
    Content-Type: application/x-www-form-urlencoded

    grant_type=client_credentials

    POST /realms/demo/protocol/openid-connect/token
    Authorization: Basic cHJvZHVjdC1zYS1jbGllbnQ6cGFzc3dvcmQ=
    Content-Type: application/x-www-form-urlencoded

    grant_type=client_credentials

Note that the value of cHJvZHVjdC1zYS1jbGllbnQ6cGFzc3dvcmQ= used in the Authorization header is Base64 encoded value of clientId and clientSecret in the format prescribed by the Authorization: Basic header. In this example, the client ID is product-sa-client and the client secret was password and hence the value was obtained for example by this command in the Unix platform:

echo 'product-sa-client:password' | base64

echo 'product-sa-client:password' | base64

Instead of using the header Authorization: Basic, it is also possible to send the credentials as parameters client_id and client_secret of the POST request. For other client credentials methods, the format of the parameters would be different as described above.

The response would be similar to this Access Token Response from the OAuth 2.0 specification.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"eyJhbGciOiJSUzI1NiIs...",
    "token_type":"Bearer",
    "expires_in":60,
    "scope": "email profile"
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"eyJhbGciOiJSUzI1NiIs...",
    "token_type":"Bearer",
    "expires_in":60,
    "scope": "email profile"
}

Only the access token is returned by default. No refresh token is returned and no user session is created on the Red Hat build of Keycloak side upon successful authentication by default. Due to the lack of a refresh token, re-authentication is required when the access token expires. However, this situation does not mean any additional overhead for the Red Hat build of Keycloak server because sessions are not created by default.

In this situation, logout is unnecessary. However, issued access tokens can be revoked by sending requests to the OAuth2 Revocation Endpoint as described in the OpenID Connect Endpoints section.

When a user authenticates, there are some roles that are added to the access token. By default, the Realm roles are added to the access token into the realm_access claim. The Client roles are added by default to the resource_access claim.

The roles added to the token are an intersection of:

Typically, the environment where Red Hat build of Keycloak is deployed consists of a set of confidential or public client applications that use Red Hat build of Keycloak for authentication. These clients are frontend clients, which may directly redirect user to Red Hat build of Keycloak to request browser authentication. The particular client would then receive set of tokens after successful authentication.

Services (Resource Servers in the OAuth 2 specification) are also available that serve requests from client applications and provide resources to these applications. These services require an Access token (Bearer token) to be sent to them from frontend application or from other service to authenticate a request.

The care must be taken to make sure that access tokens have limited privileges and the particular access token cannot be misused by the service to access other third-party services. In the environment where trust among services is low, you may encounter this example scenario:

This scenario is unlikely in environments with a high level of trust between services but not in environments where trust is low.

To prevent any misuse of the access token, the access token can contain the claim aud, which represents the audience. The claim aud should typically represent client ids of all services where the token is supposed to be used. In the environments with low trust among services, it is recommended to:

To prevent service1 from the example above to misuse the token, the secure variant of the flow may instead look like this:

The Settings tab includes many options to configure this client.

This tab has many fields for specific situations. Some fields are covered in other topics. For details on other fields, click the question mark icon.

IDP Initiated Login is a feature that allows you to set up an endpoint on the Red Hat build of Keycloak server that will log you into a specific application/client. In the Settings tab for your client, you need to specify the IDP Initiated SSO URL Name. This is a simple string with no whitespace in it. After this you can reference your client at the following URL: root/realms/{realm-name}/protocol/saml/clients/{url-name}

The IDP initiated login implementation prefers POST over REDIRECT binding (check saml bindings for more information). Therefore the final binding and SP URL are selected in the following way:

If your client requires a special relay state, you can also configure this on the Settings tab in the IDP Initiated SSO Relay State field. Alternatively, browsers can specify the relay state in a RelayState query parameter, i.e. root/realms/{realm-name}/protocol/saml/clients/{url-name}?RelayState=thestate.

When using identity brokering, it is possible to set up an IDP Initiated Login for a client from an external IDP. The actual client is set up for IDP Initiated Login at broker IDP as described above. The external IDP has to set up the client for application IDP Initiated Login that will point to a special URL pointing to the broker and representing IDP Initiated Login endpoint for a selected client at the brokering IDP. This means that in client settings at the external IDP:

Please note that you can import basic client settings from the brokering IDP into client settings of the external IDP - just use SP Descriptor available from the settings of the identity provider in the brokering IDP, and add clients/client-id to the endpoint URL.

Instead of registering a SAML 2.0 client manually, you can import the client using a standard SAML Entity Descriptor XML file.

The Client page includes an Import client option.

Some SAML client adapters, such as mod-auth-mellon, need the XML Entity Descriptor for the IDP. You can find this descriptor by going to this URL:

root/realms/{realm-name}/protocol/saml/descriptor

root/realms/{realm-name}/protocol/saml/descriptor

where realm is the realm of your client.

Mapper implementations have priority order. Priority order is not the configuration property of the mapper. It is the property of the concrete implementation of the mapper.

Mappers are sorted by the order in the list of mappers. The changes in the token or assertion are applied in that order with the lowest applying first. Therefore, the implementations that are dependent on other implementations are processed in the necessary order.

For example, to compute the roles which will be included with a token:

User session details are defined using mappers and are automatically included when you use or enable a feature on a client. Click Add builtin to include session details.

Impersonated user sessions provide the following details:

Service account sessions provide the following details:

Use the Script Mapper to map claims to tokens by running user-defined JavaScript code. For more details about deploying scripts to the server, see JavaScript Providers.

When scripts deploy, you should be able to select the deployed scripts from the list of available mappers.

Subject claim sub is mapped by default by Subject (sub) protocol mapper in the default client scope basic.

To use a pairwise subject identifier by using a protocol mapper such as Pairwise subject identifier, you can remove the Subject (sub) protocol mapper from the basic client scope. However it is not strictly needed as the Subject (sub) protocol mapper is executed before the Pairwise subject identifier mapper and hence the pairwise value will override the value added by the Subject mapper. This is due to the priority of the Subject mapper. So the only advantage of removing the built-in Subject (sub) mapper might be to save a little bit of performance by avoiding the use of the protocol mapper, which may not have any effect.

The access token in Red Hat build of Keycloak contains sensitive information, including Personal Identifiable Information (PII). Therefore, if the resource server does not want to disclose this type of information to third party entities such as clients, Red Hat build of Keycloak supports lightweight access tokens that remove PII from access tokens. Further, when the resource server acquires the PII removed from the access token, it can acquire the PII by sending the access token to Red Hat build of Keycloak’s token introspection endpoint.

When you create a client scope, choose the Protocol. Clients linked in the same scope must have the same protocol.

Each realm has a set of pre-defined built-in client scopes in the menu.

The client scopes profile, email, address and phone are defined in the OpenID Connect specification. These scopes do not have any role scope mappings defined but they do have protocol mappers defined. These mappers correspond to the claims defined in the OpenID Connect specification.

For example, when you open the phone client scope and open the Mappers tab, you will see the protocol mappers which correspond to the claims defined in the specification for the scope phone.

When the phone client scope is linked to a client, the client automatically inherits all the protocol mappers defined in the phone client scope. Access tokens issued for this client contain the phone number information about the user, assuming that the user has a defined phone number.

Built-in client scopes contain the protocol mappers as defined in the specification. You are free to edit client scopes and create, update, or remove any protocol mappers or role scope mappings.

Client scopes contain options related to the consent screen. Those options are useful if the linked client if Consent Required is enabled on the client.

There is the Include in token scope switch on the client scope. If on, the name of this client scope will be added to the access token property scope, and to the Token Response and Token Introspection Endpoint response claim scope. If off, this client scope will be omitted from the token and from the Token Introspection Endpoint response. As mentioned above, some built-in client scopes have this switch disabled, which means that they are not included in the scope claim even if they are applied for the particular request.

Linking between a client scope and a client is configured in the Client Scopes tab of the client. Here is how it looks for the client application myclient:

There are two ways of linking between the client scope and the client.

scope=openid phone

scope=openid phone

The Mappers tab contains the protocol mappers and the Scope tab contains the role scope mappings declared for this client. They do not contain the mappers and scope mappings inherited from client scopes. It is possible to see the effective protocol mappers (that is the protocol mappers defined on the client itself as well as inherited from the linked client scopes) and the effective role scope mappings used when generating a token for a client.

This will also show you the value of the scope parameter. This parameter needs to be sent from the application to the Red Hat build of Keycloak OpenID Connect authorization endpoint.

You can also simulate how the access token, ID token, or UserInfo response issued to this client looks for a particular selected user and for a specific value of the audience parameter. Note that the audience parameter is currently only supported for the token exchange grant. It is recommended to leave it empty when simulating any other grant.

All examples are generated for the particular user and issued for the particular client, with the specified value of the scope parameter. The examples include all of the claims and role mappings used.

When issuing tokens to a user, the client scope applies only if the user is permitted to use it.

When a client scope does not have any role scope mappings defined, each user is permitted to use this client scope. However, when a client scope has role scope mappings defined, the user must be a member of at least one of the roles. There must be an intersection between the user roles and the roles of the client scope. Composite roles are factored into evaluating this intersection.

If a user is not permitted to use the client scope, no protocol mappers or role scope mappings will be used when generating tokens. The client scope will not appear in the scope value in the token.

Use Realm Default Client Scopes to define sets of client scopes that are automatically linked to newly created clients.

To see the realm default client scopes, click the Client Scopes tab on the left side of the admin console. In the Assigned type column, you can specify whether a particular client scope should be added as a Default Client Scope or an Optional Client Scope to newly created clients. See this section for details on what default and optional client scopes are.

When a client is created, you can unlink the default client scopes, if needed. This is similar to removing Default Roles.

The term scope has multiple meanings within Red Hat build of Keycloak and across the OAuth/OIDC specifications. Below is a clarification of the different scopes used in Red Hat build of Keycloak:

Client Policies realize the following points mentioned as follows.

The client policy concept is independent of any specific protocol. Red Hat build of Keycloak currently supports especially client profiles for the OpenID Connect (OIDC) protocol, but there is also a client profile available for the SAML protocol.

Client Policies consists of the four building blocks: Condition, Executor, Profile and Policy.

Policies, profiles, conditions, executors can be configured by Admin REST API, which means also the Admin Console. To do so, there is a tab Realm Realm Settings Client Policies , which means the administrator can have client policies per realm.

The Global Client Profiles are automatically available in each realm. However there are no client policies configured by default. This means that the administrator is always required to create any client policy if they want for example the clients of his realm to be FAPI compliant. Global profiles cannot be updated, but the administrator can easily use them as a template and create their own profile if they want to do some slight changes in the global profile configurations. There is JSON Editor available in the Admin Console, which simplifies the creation of new profile based on some global profile.

Client Policies can replace Client Registration Policies described in the Client registration service from Securing applications and Services guide. However, Client Registration Policies also still co-exist. This means that for example during a Dynamic Client Registration request to create/update a client, both client policies and client registration policies are applied.

The current plans are for the Client Registration Policies feature to be removed and the existing client registration policies will be migrated into new client policies automatically.

See an example configuration for client secret rotation.