Chapter 8. Managing 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.

This will bring you to the Add Client page.

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 identity 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.

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.

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. See Securing Applications and Services Guide for more information.

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!

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 /{server-root-usualy-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.

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.

This will bring you to the Add Client page.

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.

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.

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.

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:

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.

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.

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.

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.

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.