Chapter 8. Managing Clients

OAuth 2.0 Mutual TLS Client Certificate Bound Access Token

Mutual TLS binds an access token and a refresh token with a client certificate exchanged during TLS handshake. This prevents an attacker who finds a way to steal these tokens from exercising the tokens. This type of token is called a holder-of-key token. Unlike bearer tokens, the recipient of a holder-of-key token can verify whether the sender of the token is legitimate.

If the following conditions are satisfied on a token request, Red Hat Single Sign-On will bind an access token and a refresh token with a client certificate and issue them as holder-of-key tokens. If all conditions are not met, Red Hat Single Sign-On rejects the token request.

To enable mutual TLS in Red Hat Single Sign-On, see Enable mutual SSL in WildFly.

In the following cases, Red Hat Single Sign-On will verify the client sending the access token or the refresh token; if verification fails, Red Hat Single Sign-On rejects the token.

Please see Mutual TLS Client Certificate Bound Access Tokens in the OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens for more details.

WARNING: None of the keycloak client adapters currently support holder-of-key token verification. Instead, keycloak adapters currently treat access and refresh tokens as bearer tokens.

If you’ve set the client’s access type to confidential in the client’s Settings tab, a new Credentials tab will show up. As part of dealing with this type of client you have to configure the client’s credentials.

The Client Authenticator list box specifies the type of credential you are going to use for your confidential client. It defaults to client ID and secret. The secret is automatically generated for you and the Regenerate Secret button allows you to recreate this secret if you want or need to.

Alternatively, you can opt to use a signed Json Web Token (JWT) or x509 certificate validation (also called Mutual TLS) instead of a secret.

When choosing this credential type you will have to also generate a private key and certificate for the client. 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 and certificate button to start this process.

When you generate these keys, Red Hat Single Sign-On will store the certificate, and you’ll need to download the private key and certificate for your client to use. Pick the archive format you want and specify the password for the private key and store.

You can also opt to generate these via an external tool and just import the client’s certificate.

There are multiple formats you can import from, just choose the archive format you have the certificate stored in, select the file, and click the Import button.

Finally note that you don’t even need to import certificate if you choose to Use JWKS URL . In that case, you can provide the URL where client publishes it’s public key in JWK format. This is flexible because when client changes it’s keys, Red Hat Single Sign-On will automatically download them without need to re-import anything on Red Hat Single Sign-On side.

If you use client secured by Red Hat Single Sign-On adapter, you can configure the JWKS URL like https://myhost.com/myapp/k_jwks assuming that https://myhost.com/myapp is the root URL of your client application. See Server Developer Guide for additional details.

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

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

There are two ways for Red Hat Single Sign-On to obtain the Client ID from the request. The first option is the client_id parameter in the query (described in Section 2.2 of the OAuth 2.0 Specification). The second option is to supply client_id as a query parameter.

Each OIDC client has a built-in service account which allows it to obtain an access token. This is covered in the OAuth 2.0 specifiation under Client Credentials Grant. To use this feature you must set the Access Type of your client to confidential. When you do this, the Service Accounts Enabled switch will appear. You need to turn on this switch. Also make sure that you have configured your client credentials.

To use it you must have registered a valid confidential Client and you need to check the switch Service Accounts Enabled in Red Hat Single Sign-On admin console for this client. In tab Service Account Roles you can configure the roles available to the service account retrieved on behalf of this client. Remember that you must have the roles available in Role Scope Mappings (tab Scope) of this client as well, unless you have Full Scope Allowed on. As in a normal login, roles from access token are the intersection of:

The REST URL to invoke on is /auth/realms/{realm-name}/protocol/openid-connect/token. Invoking on this URL is a POST request and requires you to post the client credentials. By default, client credentials are represented by clientId and clientSecret of the client in 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 use the parameter grant_type=client_credentials as per the OAuth2 specification.

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

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

    grant_type=client_credentials

The response would be this standard JSON document 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":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"bearer",
    "expires_in":60,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
    "refresh_expires_in":600,
    "id_token":"tGzv3JOkF0XG5Qx2TlKWIA",
    "not-before-policy":0,
    "session_state":"234234-234234-234234"
}

The retrieved access token can be refreshed or logged out by an out-of-bound request.

The typical environment where the Red Hat Single Sign-On is deployed generally consists of a set of confidential or public client applications (frontend client applications) which use Red Hat Single Sign-On for authentication.

There are also services (called Resource Servers in the OAuth 2 specification), which serve requests from frontend client applications and provide resources. These services typically require an Access token (Bearer token) to be sent to them to authenticate for a particular request. This token was previously obtained by the frontend application when it tries to log in against Red Hat Single Sign-On.

In the environment where the trust among services is low, you may encounter this scenario:

This flow may not be an issue in many environments with the high level of trust among services. However in other environments, where the trust among services is lower, this can be problematic.

To prevent any misuse of the access token as in the example above, it is recommended to limit Audience on the token and configure your services to verify the audience on the token. If this is done, the flow above will change, like this:

If the client wants to invoke the good-service later, it will need to obtain another token by issuing the SSO login with the scope=good-service. The returned token will then contain good-service as an audience:

"audience": [ "good-service" ]

and can be used to invoke good-service.

IDP Initiated Login is a feature that allows you to set up an endpoint on the Red Hat Single Sign-On 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/auth/realms/{realm}/protocol/saml/clients/{url-name}

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/auth/realms/{realm}/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 manually registering a SAML 2.0 client, you can import it via a standard SAML Entity Descriptor XML file. There is an Import option on the Add Client page.

Click the Select File button and load your entity descriptor file. You should review all the information there to make sure everything is set up correctly.

Some SAML client adapters like mod-auth-mellon need the XML Entity Descriptor for the IDP. You can obtain this by going to this public URL: root/auth/realms/{realm}/protocol/saml/descriptor

Mapper implementations have priority order. This priority order is not the configuration property of the mapper; rather, it is the property of the concrete implementation of the mapper.

Mappers are sorted in the admin console by the order in the list of mappers and the changes in the token or assertion will be applied using that order with the lowest being applied first. This means that implementations which are dependent on other implementations are processed in the needed order.

For example, when we first want to compute the roles which will be included with a token, we first resolve audiences based on those roles. Then, we process a JavaScript script that uses the roles and audiences already available in the token.

The Script Mapper allows you to map claims to tokens by running a user-defined JavaScript code. For more details about how to deploy scripts to the server, please take a look at JavaScript Providers.

Once you have your scripts deployed, you should be able to select the scripts you deployed from the list of available mappers.

When you are creating the client scope, you must choose the Protocol. Only the clients which use same protocol can then be linked with this client scope.

Once you have created new realm, you can see that there is a list of pre-defined (builtin) client scopes in the menu.

The client scope, offline_access, is useful when client wants to obtain offline tokens. Learn about offline tokens in the Offline Access section or in the OpenID Connect specification, where scope parameter is defined with the value offline_access.

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

For example, when you click to 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, that client automatically inherits all the protocol mappers defined in the phone client scope. Access tokens issued for this client will contain the phone number information about the user, assuming that the user has a defined phone number.

Builtin client scopes contain exactly the protocol mappers as defined per the specification, however you are free to edit client scopes and create/update/remove any protocol mappers (or role scope mappings).

The client scope roles is not defined in the OpenID Connect specification and it is also not added automatically to the scope claim in the access token. This client scope has some mappers, which are used to add roles of the user to the access token and possibly add some audiences for the clients with at least one client role as described in the Audience section.

The client scope web-origins is also not defined in the OpenID Connect specification and not added to the scope claim. This is used to add allowed web origins to the access token allowed-origins claim.

Client scope contains options related to the consent screen. Those options are useful only if the linked client is configured to require consent (if the Consent Required switch is enabled on the client).

Linking between client scope and client is configured in the Client Scopes tab of the particular client. There are 2 ways of linking between client scope and client.

scope=openid phone

The tabs Mappers and Scope of the client contain the protocol mappers and role scope mappings declared solely for this client. They do not contain the mappers and scope mappings inherited from client scopes. However, it may be useful to see what the effective protocol mappers will be (protocol mappers defined on the client itself as well as inherited from the linked client scopes) and the effective role scope mappings used when you generate the token for the particular client.

You can see all of these when you click the Client Scopes tab for the client and then open the sub-tab Evaluate. From here you can select the optional client scopes that you want to apply. This will also show you the value of the scope parameter, which needs to be sent from the application to the Red Hat Single Sign-On OpenID Connect authorization endpoint.

When issuing tokens for a particular user, the client scope is applied only if the user is permitted to use it. In the case that a client scope does not have any role scope mappings defined on itself, then each user is automatically permitted to use this client scope. However, when a client scope has any role scope mappings defined on itself, then the user must be a member of at least one of the roles. In other words, there must be an intersection between the user roles and the roles of the client scope. Composite roles are taken into account when evaluating this intersection.

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

The Realm Default Client Scopes allow you to define set of client scopes, which will be automatically linked to newly created clients.

Open the left menu item Client Scopes and then select Default Client Scopes.

From here, select the client scopes that you want to add as Default Client Scopes to newly created clients and Optional Client Scopes to newly created clients.

Once the client is created, you can unlink the default client scopes, if needed. This is similar to how you remove Default Roles.

The term scope is used in Red Hat Single Sign-On on few places. Various occurences of scopes are related to each other, but may have a different context and meaning. To clarify, here we explain the various scopes used in Red Hat Single Sign-On.