Chapter 8. Managing Clients

Clients are entities that can request authentication of a user. Clients come in two forms. The first type of client is an application that wants to participate in single-sign-on. These clients just want Red Hat Single Sign-On to provide security for them. The other type of client is one that is requesting an access token so that it can invoke other services on behalf of the authenticated user. This section discusses various aspects around configuring clients and various ways to do it.

8.1. OIDC Clients

OpenID Connect is the preferred protocol to secure applications. It was designed from the ground up to be web friendly and work best with HTML5/JavaScript applications.

To create an OIDC client go to the Clients left menu item. On this page you’ll see a Create button on the right.

Clients

clients

This will bring you to the Add Client page.

Add Client

add client oidc

Enter in the Client ID of the client. This should be a simple alpha-numeric string that will be used in requests and in the Red Hat Single Sign-On database to identify the client. Next select openid-connect in the Client Protocol drop down box. Ignore the Client Template listbox for now, we’ll go over that later in this chapter. Finally enter in the base URL of your application in the Root URL field and click Save. This will create the client and bring you to the client Settings tab.

Client Settings

client settings oidc

Let’s walk through each configuration item on this page.

Client ID

This specifies an alpha-numeric string that will be used as the client identifier for OIDC requests.

Name

This is the display name for the client whenever it is displayed in a Red Hat Single Sign-On UI screen. You can localize the value of this field by setting up a replacement string value i.e. ${myapp}. See the Server Developer Guide for more information.

Description

This specifies the description of the client. This can also be localized.

Enabled

If this is turned off, the client will not be allowed to request authentication.

Consent Required

If this is on, then users will get a consent page which asks the user if they grant access to that application. It will also display the metadata that the client is interested in so that the user knows exactly what information the client is getting access to. If you’ve ever done a social login to Google, you’ll often see a similar page. Red Hat Single Sign-On provides the same functionality.

Access Type

This defines the type of the OIDC client.

confidential
Confidential access type is for server-side clients that need to perform a browser login and require a client secret when they turn an access code into an access token, (see Access Token Request in the OAuth 2.0 spec for more details). This type should be used for server-side applications.
public
Public access type is for client-side clients that need to perform a browser login. With a client-side application there is no way to keep a secret safe. Instead it is very important to restrict access by configuring correct redirect URIs for the client.
bearer-only
Bearer-only access type means that the application only allows bearer token requests. If this is turned on, this application cannot participate in browser logins.

Root URL

If Red Hat Single Sign-On uses any configured relative URLs, this value is prepended to them.

Valid Redirect URIs

This is a required field. Enter in a URL pattern and click the + sign to add. Click the - sign next to URLs you want to remove. Remember that you still have to click the Save button! Wildcards (\*) are only allowed at the end of a URI, i.e. http://host.com/*

You should take extra precautions when registering valid redirect URI patterns. If you make them too general you are vulnerable to attacks. See Threat Model Mitigation chapter for more information.

Base URL

If Red Hat Single Sign-On needs to link to the client, this URL is used.

Standard Flow Enabled

If this is on, clients are allowed to use the OIDC Authorization Code Flow.

Implicit Flow Enabled

If this is on, clients are allowed to use the OIDC Implicit Flow.

Direct Grants Enabled

If this is on, clients are allowed to use the OIDC Direct Grants.

Admin URL

For Red Hat Single Sign-On specific client adapters, this is the callback endpoint for the client. The Red Hat Single Sign-On server will use this URI to make callbacks like pushing revocation policies, performing backchannel logout, and other administrative operations. For Red Hat Single Sign-On servlet adapters, this can be the root URL of the servlet application. For more information see Securing Applications and Services Guide.

Web Origins

This option centers around CORS which stands for Cross-Origin Resource Sharing. If browser JavaScript tries to make an AJAX HTTP request to a server whose domain is different from the one the JavaScript code came from, then the request must use CORS. The server must handle CORS requests in a special way, otherwise the browser will not display or allow the request to be processed. This protocol exists to protect against XSS, CSRF and other JavaScript-based attacks.

Red Hat Single Sign-On has support for validated CORS requests. The way it works is that the domains listed in the Web Origins setting for the client are embedded within the access token sent to the client application. The client application can then use this information to decide whether or not to allow a CORS request to be invoked on it. This is an extension to the OIDC protocol so only Red Hat Single Sign-On client adapters support this feature. See Securing Applications and Services Guide for more information.

To fill in the Web Origins data, enter in a base URL and click the + sign to add. Click the - sign next to URLs you want to remove. Remember that you still have to click the Save button!

8.1.1. Confidential Client Credentials

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.

Credentials Tab

client 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) instead of a secret.

Signed JWT

client credentials jwt

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.

Generate Keys

generate client keys

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.

Import Certificate

import client cert

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.

Warning

For the performance purposes, Red Hat Single Sign-On caches the public keys of the OIDC clients. If you think that private key of your client was compromised, it is obviously good to update your keys, but it’s also good to clear the keys cache. See Clearing the cache section for more details.

8.2. Service Accounts

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. Don’t forget that you need those roles to be available in Scopes of this client as well (unless you have Full Scope Allowed on). As in normal login, roles from access token are the intersection of scopes and the service account roles.

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.

8.3. SAML Clients

Red Hat Single Sign-On supports SAML 2.0 for registered applications. Both POST and Redirect bindings are supported. You can choose to require client signature validation and can have the server sign and/or encrypt responses as well.

To create a SAML client go to the Clients left menu item. On this page you’ll see a Create button on the right.

Clients

clients

This will bring you to the Add Client page.

Add Client

add client saml

Enter in the Client ID of the client. This is often a URL and will be the expected issuer value in SAML requests sent by the application. Next select saml in the Client Protocol drop down box. Ignore the Client Template listbox for now, we’ll go over that later in this chapter. Finally enter in the Client SAML Endpoint URL. Enter the URL you want the Red Hat Single Sign-On server to send SAML requests and responses to. Usually applications have only one URL for processing SAML requests. If your application has different URLs for its bindings, don’t worry, you can fix this in the Settings tab of the client. Click Save. This will create the client and bring you to the client Settings tab.

Client Settings

client settings saml

Client ID
This value must match the issuer value sent with AuthNRequests. Red Hat Single Sign-On will pull the issuer from the Authn SAML request and match it to a client by this value.
Name
This is the display name for the client whenever it is displayed in a Red Hat Single Sign-On UI screen. You can localize the value of this field by setting up a replacement string value i.e. ${myapp}. See the Server Developer Guide for more information.
Description
This specifies the description of the client. This can also be localized.
Enabled
If this is turned off, the client will not be allowed to request authentication.
Consent Required
If this is on, then users will get a consent page which asks the user if they grant access to that application. It will also display the metadata that the client is interested in so that the user knows exactly what information the client is getting access to. If you’ve ever done a social login to Google, you’ll often see a similar page. Red Hat Single Sign-On provides the same functionality.
Include AuthnStatement
SAML login responses may specify the authentication method used (password, etc.) as well as a timestamp of the login. Setting this to on will include that statement in the response document.
Sign Documents
When turned on, Red Hat Single Sign-On will sign the document using the realm’s private key.
Optimize REDIRECT signing key lookup
When turned on, the SAML protocol messages will include Red Hat Single Sign-On native extension that contains a hint with signing key ID. When the SP understands this extension, it can use it for signature validation instead of attempting to validate signature with all known keys. This option only applies to REDIRECT bindings where the signature is transferred in query parameters where there is no place with this information in the signature information (contrary to POST binding messages where key ID is always included in document signature). Currently this is relevant to situations where both IDP and SP are provided by Red Hat Single Sign-On server and adapter. This option is only relevant when Sign Documents is switched on.
Sign Assertions
The Sign Documents switch signs the whole document. With this setting the assertion is also signed and embedded within the SAML XML Auth response.
Signature Algorithm
Choose between a variety of algorithms for signing SAML documents.
SAML Signature Key Name
Signed SAML documents sent via POST binding contain identification of signing key in KeyName element. This by default contains Red Hat Single Sign-On key ID. However various vendors might expect a different key name or no key name at all. This switch controls whether KeyName contains key ID (option KEY_ID), subject from certificate corresponding to the realm key (option CERT_SUBJECT - expected for instance by Microsoft Active Directory Federation Services), or that the key name hint is completely omitted from the SAML message (option NONE).
Canonicalization Method
Canonicalization method for XML signatures.
Encrypt Assertions
Encrypt assertions in SAML documents with the realm’s private key. The AES algorithm is used with a key size of 128 bits.
Client Signature Required
Expect that documents coming from a client are signed. Red Hat Single Sign-On will validate this signature using the client public key or cert set up in the SAML Keys tab.
Force POST Binding
By default, Red Hat Single Sign-On will respond using the initial SAML binding of the original request. By turning on this switch, you will force Red Hat Single Sign-On to always respond using the SAML POST Binding even if the original request was the Redirect binding.
Front Channel Logout
If true, this application requires a browser redirect to be able to perform a logout. For example, the application may require a cookie to be reset which could only be done via a redirect. If this switch is false, then Red Hat Single Sign-On will invoke a background SAML request to logout the application.
Force Name ID Format
If the request has a name ID policy, ignore it and used the value configured in the admin console under Name ID Format
Name ID Format
Name ID Format for the subject. If no name ID policy is specified in the request or if the Force Name ID Format attribute is true, this value is used. Properties used for each of the respective formats are defined below.
Root URL
If Red Hat Single Sign-On uses any configured relative URLs, this value is prepended to them.
Valid Redirect URIs
This is an optional field. Enter in a URL pattern and click the + sign to add. Click the - sign next to URLs you want to remove. Remember that you still have to click the Save button! Wildcards (\*) are only allowed at the end of of a URI, i.e. http://host.com/*. This field is used when the exact SAML endpoints are not registered and Red Hat Single Sign-On is pull the Assertion Consumer URL from the request.
Base URL
If Red Hat Single Sign-On needs to link to the client, this URL would be used.
Master SAML Processing URL
This URL will be used for all SAML requests and the response will be directed to the SP. It will be used as the Assertion Consumer Service URL and the Single Logout Service URL. If a login request contains the Assertion Consumer Service URL, that will take precedence, but this URL must be valided by a registered Valid Redirect URI pattern
Assertion Consumer Service POST Binding URL
POST Binding URL for the Assertion Consumer Service.
Assertion Consumer Service Redirect Binding URL
Redirect Binding URL for the Assertion Consumer Service.
Logout Service POST Binding URL
POST Binding URL for the Logout Service.
Logout Service Redirect Binding URL
Redirect Binding URL for the Logout Service.

8.3.1. IDP Initiated Login

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:

  • IDP Initiated SSO URL Name is set to a name that will be published as IDP Initiated Login initial point,
  • Assertion Consumer Service POST Binding URL in the Fine Grain SAML Endpoint Configuration section has to be set to the following URL: broker-root/auth/realms/{broker-realm}/broker/{idp-name}/endpoint/clients/{client-id}, where:

    • broker-root is base broker URL
    • broker-realm is name of the realm at broker where external IDP is declared
    • idp-name is name of the external IDP at broker
    • client-id is the value of IDP Initiated SSO URL Name attribute of the SAML client defined at broker. It is this client, which will be made available for IDP Initiated Login from 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.

8.3.2. SAML Entity Descriptors

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.

Add Client

add client saml

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

8.5. OIDC Token and SAML Assertion Mappings

Applications that receive ID Tokens, Access Tokens, or SAML assertions may need or want different user metadata and roles. Red Hat Single Sign-On allows you to define what exactly is transferred. You can hardcode roles, claims and custom attributes. You can pull user metadata into a token or assertion. You can rename roles. Basically you have a lot of control of what exactly goes back to the client.

Within the Admin Console, if you go to an application you’ve registered, you’ll see a Mappers tab. Here’s one for an OIDC based client.

Mappers Tab

mappers oidc

Each client has several built-in mappers that are created for it by default. They map things like, for example, email address to a specific claim in the identity and access token. Their function should each be self explanatory from their name. There are additional pre-configured mappers that are not attached to the client that you can add by clicking the Add Builtin button.

Each mapper has common settings as well as additional ones depending on which type of mapper you are adding. Click the Edit button next to one of the mappers in the list to get to the config screen.

Mapper Config

mapper config

The best way to learn about a config option is to hover over its tooltip. There are a few config options that are common to all mappers:

Consent Required
If your client requires consent, this mapper will be displayed on the consent screen shown to the user.
Consent Text
If your client requires consent and the Consent switch is on, this is the text that will be displayed by the user. The value for this text is localizable by specifying a substitution variable with ${var-name} strings. The localized value is then configured within property files in your theme. See the Server Developer Guide for more information on localization.

Most OIDC mappers also allow you to control where the claim gets put. You can opt to include or exclude the claim from both the id and access tokens by fiddling with the Add to ID token and Add to access token switches.

Finally, you can also add other mapper types. If you go back to the Mappers tab, click the Create button.

Add Mapper

add mapper

Pick a Mapper Type from the list box. If you hover over the tooltip, you’ll see a description of what that mapper type does. Different config parameters will appear for different mapper types.

8.6. Generating Client Adapter Config

The Red Hat Single Sign-On can pre-generate configuration files that you can use to install a client adapter for in your application’s deployment environment. A number of adapter types are supported for both OIDC and SAML. Go to the Installation tab of the client you want to generate configuration for.

client installation

Select the Format Option you want configuration generated for. All Red Hat Single Sign-On client adapters for OIDC and SAML are supported. The mod-auth-mellon Apache HTTPD adapter for SAML is supported as well as standard SAML entity descriptor files.

8.7. Client Templates

If you have a lot of applications you need to secure and register within your organization it can become quite tedious to configure the protocol mappers and scope for each of these clients. Red Hat Single Sign-On allows you to define shared client configuration in an entity called a client template.

To create a client template, go to the Client Templates left menu item. This initial screen shows you a list of currently defined templates.

To create a template click the Create button. This brings you to a simple screen in which you name the template and hit save. A client template will have similar tabs to regular clients. You’ll be able to define protocol mappers and scope which can be inherited by other clients.

Having a client inherit from a template is as simple as choosing the template from the Client Template drop down list on either the Add Client or client Settings tab. You will see the Mappers and Scope tabs get additional switches which allow you to turn on or off inheriting from the parent template.

Future versions of client templating may get more inheritable configuration options, but for now, that’s all there is to talk about.