Red Hat Single Sign-On is a separate server that you manage on your network. Applications are configured to point to and be secured by this server. Red Hat Single Sign-On uses open protocol standards like Open ID Connect or SAML 2.0 to secure your applications. Browser applications redirect a user’s browser from the application to the Red Hat Single Sign-On authentication server where they enter their credentials. This is important because users are completely isolated from applications and applications never see a user’s credentials. Applications instead are given an identity token or assertion that is cryptographically signed. These tokens can have identity information like username, address, email, and other profile data. They can also hold permission data so that applications can make authorization decisions. These tokens can also be used to make secure invocations on REST-based services.

There are some key concepts and terms you should be aware of before attempting to use Red Hat Single Sign-On to secure your web applications and REST services.

When you boot Red Hat Single Sign-On for the first time a pre-defined realm is created for you. This initial realm is called the master realm and is the king of all realms. Admins in this realm have permissions to view and manage any other realm created on the server instance. When you define your initial admin account, you are creating an account in the master realm. Your initial login to the admin console will also be through the master realm.

It is recommended that you do not use the master realm to manage the users and applications in your organization. Keep the master realm as a place for super admins to create and manage the realms in your system. This keeps things clean and organized.

It is possible to disable the master realm and define admin accounts at each individual new realm you create. Each realm has its own dedicated Admin Console that you can log into with local accounts. This guide talks more about this in the Dedicated Realm Admin Consoles chapter.

Creating a new realm is very simple. Mouse over the top left corner drop down menu that is titled with Master. If you are logged in the master realm this drop down menu lists all the realms created. The last entry of this drop down menu is always Add Realm. Click this to add a realm.

This menu option will bring you to the Add Realm page. Specify the realm name you want to define and click the Create button. Alternatively you can import a JSON document that defines your new realm. We’ll go over this in more detail in the Export and Import chapter.

After creating the realm you are brought back to the main Admin Console page. The current realm will now be set to the realm you just created. You can switch between managing different realms by doing a mouse over on the top left corner drop down menu.

Each realm has an SSL Mode associated with it. The SSL Mode defines the SSL/HTTPS requirements for interacting with the realm. Browsers and applications that interact with the realm must honor the SSL/HTTPS requirements defined by the SSL Mode or they will not be allowed to interact with the server.

To configure the SSL Mode of your realm, you need to click on the Realm Settings left menu item and go to the Login tab.

The Require SSL option allows you to pick the SSL Mode you want. Here is an explanation of each mode:

The authentication protocols that are used by Red Hat Single Sign-On require cryptographic signatures and sometimes even encryption. Red Hat Single Sign-On uses an asymmetric key pair, a private and public key to accomplish this. When a realm is created a key pair is automatically generated. It is recommended that you cycle this key pair occasionally. How often you do this is dependent on your organizational needs and security requirements as you have to make sure every application that needs the public key or certificate of your realm gets this updated. This can be a lot of work!

To cycle a key pair click on the Realm Settings left menu item, go to the Keys tab, and push the Generate new keys button.

This will create a brand new key pair for your realm.

Red Hat Single Sign-On will cache everything it can in memory within the limits of your JVM and/or the limits you’ve configured it for. If the Red Hat Single Sign-On database is modified by a third party (i.e. a DBA) outside the scope of the server’s REST APIs or Admin Console there’s a chance parts of the in-memory cache may be stale. You can clear the realm and user caches from the Admin Console by going to the Realm Settings left menu item and the Cache tab.

Just click the clear button on the cache you want to evict.

Red Hat Single Sign-On sends emails to users to verify their email address, when they forget their passwords, or when an admin needs to receive notifications about a server event. To enable Red Hat Single Sign-On to send emails you need to provide Red Hat Single Sign-On with your SMTP server settings. This is configured per realm. Go to the Realm Settings left menu item and click the Email tab.

As emails are used for recovering usernames and passwords it’s recommended to use SSL or TLS, especially if the SMTP server is on an external network. To enable SSL click on Enable SSL or to enable TLS click on Enable TLS. You will most likely also need to change the Port (the default port for SSL/TLS is 465).

If your SMTP server requires authentication click on Enable Authentication and insert the Username and Password.

Themes allow you to change the look and feel of any UI in Red Hat Single Sign-On. Themes are configured per realm. To change a theme go to the Realm Settings left menu item and click on the Themes tab.

Pick the theme you want for each UI category and click Save.

The Server Developer Guide goes into how to create a new themes or modify existing ones.

If you need to manage a specific user, click on Users in the left menu bar.

This menu option brings you to the user list page. In the search box you can type in a full name, last name, or email address you want to search for in the user database. The query will bring up all users that match your criteria. The View all users button will list every user in the system. This will search just local Red Hat Single Sign-On database and not the federated database (ie. LDAP) because some backends like LDAP don’t have a way to page through users. So if you want the users from federated backend to be synced into Red Hat Single Sign-On database you need to either:

See User Federation for more details.

To create a user click on Users in the left menu bar.

This menu option brings you to the user list page. On the right side of the empty user list, you should see an Add User button. Click that to start creating your new user.

The only required field is Username. Click save. This will bring you to the management page for your new user.

Beyond basic user metadata like name and email, you can store arbitrary user attributes. Choose a user to manage then click on the Attributes tab.

Enter in the attribute name and value in the empty fields and click the Add button next to it to add a new field. Note that any edits you make on this page will not be stored until you hit the Save button.

When viewing a user if you go to the Credentials tab you can manage a user’s credentials.

Required Actions are tasks that a user must finish before they are allowed to log in. A user must provide their credentials before required actions are executed. Once a required action is completed, the user will not have to perform the action again. Here are an explanation of some of the built in required action types:

Admins can add required actions for each individual user within the user’s Details tab in the Admin Console.

In the Required User Actions list box, select all the actions you want to add to the account. If you want to remove one, click the X next to the action name. Also remember to click the Save button after you’ve decided what actions to add.

It is often useful for an admin to impersonate a user. For example, a user may be experiencing a bug in one of your applications and an admin may want to impersonate the user to see if they can duplicate the problem. Admins with the appropriate permission can impersonate a user. There are two locations an admin can initiate impersonation. The first is on the Users list tab.

You can see here that the admin has searched for jim. Next to Jim’s account you can see an impersonate button. Click that to impersonate the user.

Also, you can impersonate the user from the user Details tab.

Near the bottom of the page you can see the Impersonate button. Click that to impersonate the user.

When impersonating, if the admin and the user are in the same realm, then the admin will be logged out and automatically logged in as the user being impersonated. If the admin and user are not in the same realm, the admin will remain logged in, but additionally be logged in as the user in that user’s realm. In both cases, the browser will be redirected to the impersonated user’s User Account Management page.

Any user with the realm’s impersonation role can impersonate a user. Please see the Admin Console Access Control chapter for more details on assigning administration permissions.

You can enable Red Hat Single Sign-On to allow user self registration. When enabled, the login page has a registration link the user can click on to create their new account. Enabling registration is pretty simple. Go to the Realm Settings left menu and click it. Then go to the Login tab. There is a User Registration switch on this tab. Turn it on, then click the Save button.

After you enable this setting, a Register link should show up on the login page.

Clicking on this link will bring the user to the registration page where they have to enter in some user profile information and a new password.

You can change the look and feel of the registration form as well as removing or adding additional fields that must be entered. See the Server Developer Guide for more information.

If you enable it, users are able to reset their credentials if they forget their password or lose their OTP generator. Go to the Realm Settings left menu item, and click on the Login tab. Switch on the Forgot Password switch.

A forgot password link will now show up on your login pages.

Clicking on this link will bring the user to a page where they can enter in their username or email and receive an email with a link to reset their credentials.

The text sent in the email is completely configurable. You just need to extend or edit the theme associated with it. See the Server Developer Guide for more information.

When the user clicks on the email link, they will be asked to update their password, and, if they have an OTP generator set up, they will also be asked to reconfigure this as well. Depending on the security requirements of your organization you may not want users to be able to reset their OTP generator through email. You can change this behavior by going to the Authentication left menu item, clicking on the Flows tab, and selecting the Reset Credentials flow:

If you do not want OTP reset, then just chose the disabled radio button to the right of Reset OTP.

If a logged in user closes their browser, their session is destroyed and they will have to log in again. You can set things up so that if a user checks a remember me checkbox, they will remain logged in even if the browser is closed. This basically turns the login cookie from a session-only cookie to a persistence cookie.

To enable this feature go to Realm Settings left menu item and click on the Login tab and turn on the Remember Me switch:

Once you save this setting, a remember me checkbox will be displayed on the realm’s login page.

Each new realm created has no password policies associated with it. This means users can have as short, as long, as complex, as insecure a password as they want. This is great for development or if you are just learning and playing around with Red Hat Single Sign-On, but pretty much unacceptable in production environment. Red Hat Single Sign-On has a rich set of password policies you can enable through the Admin Console.

Click on the Authentication left menu item and go to the Password Policy tab. Choose the policy you want to add in the right side drop down list box. This will add the policy in the table on the screen. Choose the parameters for the policy. Hit the Save button to store your changes.

After saving your policy, user registration and the Update Password required action will enforce your new policy. Here’s what it would look like if the user failed the policy check:

Unfortunately, users are not required to update their password if the password policy changes and there is no nice way of triggering an Update Password required action other than setting it manually for every user. This is scheduled as a future enhancement.

Red Hat Single Sign-On has a number of policies you can set up for your FreeOTP or Google Authenticator One-Time Password generator. Click on the Authentication left menu item and go to the OTP Policy tab.

Any policies you set here will be used to validate one-time passwords. When configuring OTP, FreeOTP and Google Authenticator can scan a QR code that is generated on the OTP set up page that Red Hat Single Sign-On has. The bar code is also generated from information configured on the OTP Policy tab.

An authentication flow is a container for all authentications, screens, and actions that must happen during login, registration, and other Red Hat Single Sign-On workflows. If you go to the admin console Authentication left menu item and go to the Flows tab, you can view all the defined flows in the system and what actions and checks each flow requires. This section does a walk through of the browser login flow. In the left drop down list select browser to come to the screen shown below:

If you hover over the tooltip (the tiny question mark) to the right of the flow selection list, this will describe what the flow is and does.

The Auth Type column is the name of authentication or action that will be executed. If an authentication is indented this means it is in a sub-flow and may or may not be executed depending on the behavior of its parent. The Requirement column is a set of radio buttons which define whether or not the action will execute. Let’s describe what each radio button means:

This is better described in an example. Let’s walk through the browser authentication flow.

Red Hat Single Sign-On supports login with a Kerberos ticket through the SPNEGO protocol. SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) is used to authenticate transparently through the web browser after the user has been authenticated when logging-in his session. For non-web cases or when ticket is not available during login, Red Hat Single Sign-On also supports login with Kerberos username/password.

A typical use case for web authentication is the following:

For setup there are 3 main parts:

sudo kadmin.local

addprinc -randkey HTTP/www.mydomain.org@MYDOMAIN.ORG
ktadd -k /tmp/http.keytab HTTP/www.mydomain.org@MYDOMAIN.ORG

[domain_realm]
  .mydomain.org = MYDOMAIN.ORG
  mydomain.org = MYDOMAIN.ORG

// Obtain accessToken in your application.
KeycloakPrincipal keycloakPrincipal = (KeycloakPrincipal) servletReq.getUserPrincipal();
AccessToken accessToken = keycloakPrincipal.getKeycloakSecurityContext().getToken();

// Retrieve kerberos credential from accessToken and deserialize it
String serializedGssCredential = (String) accessToken.getOtherClaims().
    get(org.keycloak.common.constants.KerberosConstants.GSS_DELEGATION_CREDENTIAL);

GSSCredential deserializedGssCredential = org.keycloak.common.util.KerberosSerializationUtils.
    deserializeCredential(serializedGssCredential);

// Create GSSContext to call other kerberos-secured services
GSSContext context = gssManager.createContext(serviceName, krb5Oid,
    deserializedGssCredential, GSSContext.DEFAULT_LIFETIME);

Open ID Connect (OIDC) is an authentication protocol that is an extension of OAuth 2.0. While OAuth 2.0 is only a framework for building authorization protocols and is mainly incomplete, OIDC is a full-fledged authentication and authorization protocol. OIDC also makes heavy use of the Json Web Token (JWT) set of standards. These standards define an identity token JSON format and ways to digitally sign and encrypt that data in a compact and web-friendly way.

There are really two types of use cases when using OIDC. The first is an application that asks the Red Hat Single Sign-On server to authenticate a user for them. After a successful login, the application will receive an identity token and an access token. The identity token contains information about the user such as username, email, and other profile information. The access token is digitally signed by the realm and contains access information (like user role mappings) that the application can use to determine what resources the user is allowed to access on the application.

The second type of use cases is that of a client that wants to gain access to remote services. In this case, the client asks Red Hat Single Sign-On to obtain an access token it can use to invoke on other remote services on behalf of the user. Red Hat Single Sign-On authenticates the user then asks the user for consent to grant access to the client requesting it. The client then receives the access token. This access token is digitally signed by the realm. The client can make REST invocations on remote services using this access token. The REST service extracts the access token, verifies the signature of the token, then decides based on access information within the token whether or not to process the request.

SAML 2.0 is a similar specification to OIDC but a lot older and more mature. It has its roots in SOAP and the plethora of WS-* specifications so it tends to be a bit more verbose than OIDC. SAML 2.0 is primarily an authentication protocol that works by exchanging XML documents between the authentication server and the application. XML signatures and encryption is used to verify requests and responses.

There is really two types of use cases when using SAML. The first is an application that asks the Red Hat Single Sign-On server to authenticate a user for them. After a successful login, the application will receive an XML document that contains something called a SAML assertion that specify various attributes about the user. This XML document is digitally signed by the realm and contains access information (like user role mappings) that the application can use to determine what resources the user is allowed to access on the application.

The second type of use cases is that of a client that wants to gain access to remote services. In this case, the client asks Red Hat Single Sign-On to obtain an SAML assertion it can use to invoke on other remote services on behalf of the user.

Choosing between OpenID Connect and SAML is not just a matter of using a newer protocol (OIDC) instead of the older more mature protocol (SAML).

In most cases Red Hat Single Sign-On recommends using OIDC.

SAML tends to be a bit more verbose than OIDC.

Beyond verbosity of exchanged data, if you compare the specifications you’ll find that OIDC was designed to work with the web while SAML was retrofitted to work on top of the web. For example, OIDC is also more suited for HTML5/JavaScript applications because it is easier to implement on the client side than SAML. As tokens are in the JSON format, they are easier to consume by JavaScript. You will also find several nice features that make implementing security in your web applications easier. For example, check out the iframe trick that the specification uses to easily determine if a user is still logged in or not.

SAML has its uses though. As you see the OIDC specifications evolve you see they implement more and more features that SAML has had for years. What we often see is that people pick SAML over OIDC because of the perception that it is more mature and also because they already have existing applications that are secured with it.

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.

Realm level roles are a global namespace to define your roles. You can see the list of built-in and created roles by clicking on the Roles left menu item.

To create a role just click on the Add Role button on this page, enter in the name and description of the role and hit the Save button.

The value for the description field 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. If a client requires user consent, this description string will be displayed on the consent page for the user.

Client roles are basically a namespace dedicated to a client. Each client gets its own namespace. Client roles are managed under the Roles tab under each individual client. You interact with this UI the same way you do for realm level roles.

Any realm or client level role can be turned into a composite role. A composite role is a role that has one or more additional roles associated with it. When a composite role is mapped to the user, the user also gains the roles associated with that composite. This inheritance is recursive so any composite of composites also gets inherited.

To turn a regular role into a composite role, go to the role detail page and flip the Composite Role switch on.

Once you flip this switch the role selection UI will be displayed lower on the page and you’ll be able to associate realm level and client level roles to the composite you are creating. In this example, the employee realm-level role was associated with the developer composite role. Any user with the developer role will now also inherit the employee role too.

User role mappings can be assigned individually to each user through the Role Mappings tab for that single user.

In the above example, we are about to assign the composite role developer that was created in the Composite Roles chapter.

Once the developer role is assigned, you see that the employee role that is associated with the developer composite shows up in the Effective Roles. Effective Roles are all roles that are explicitly assigned to the user as well as any roles that are inherited from composites.

When an OIDC access token or SAML assertion is created, all the user role mappings of the user are, by default, added as claims within the token or assertion. Applications use this information to make access decisions on the resources controlled by that application. In Red Hat Single Sign-On, access tokens are digitally signed and can actually be re-used by the application to invoke on other remotely secured REST services. This means that if an application gets compromised or there is a rogue client registered with the realm, attackers can get access tokens that have a broad range of permissions and your whole network is compromised. This is where client scope becomes important.

Client scope is a way to limit the roles that get declared inside an access token. When a client requests that a user be authenticated, the access token they receive back will only contain the role mappings you’ve explicitly specified for the client’s scope. This allows you to limit the permissions each individual access token has rather than giving the client access to all of the user’s permissions. By default, each client gets all the role mappings of the user. You can view this in the Scope tab of each client.

You can see from the picture that the effective roles of the scope are every declared role in the realm. To change this default behavior, you must explicitly turn off the Full Scope Allowed switch and declare the specific roles you want in each individual client. Alternatively, you can also use client templates to define the scope for a whole set of clients.

In the IT world the concepts of Group and Role are often blurred and interchangeable. In Red Hat Single Sign-On, Groups are just a collection of users that you can apply roles and attributes to in one place. Roles define a type of user and applications assign permission and access control to roles

Aren’t Composite Roles also similar to Groups? Logically they provide the same exact functionality, but the difference is conceptual. Composite roles should be used to apply the permission model to your set of services and applications. Groups should focus on collections of users and their roles in your organization. Use groups to manage users. Use composite roles to manage applications and services.

Default groups allow you to automatically assign group membership whenever any new user is created or imported through Identity Brokering. To specify default groups go to the Groups left menu item, and click the Default Groups tab.

The master realm in Red Hat Single Sign-On is a special realm and treated differently than other realms. Users in the Red Hat Single Sign-On master realm can be granted permission to manage zero or more realms that are deployed on the Red Hat Single Sign-On server. When a realm is created, Red Hat Single Sign-On automatically creates various roles that grant fine-grain permissions to access that new realm. Access to The Admin Console and Admin REST endpoints can be controlled by mapping these roles to users in the master realm. It’s possible to create multiple super users, as well as users that can only manage specific realms.

Each realm has a dedicated Admin Console that can be accessed by going to the url /auth/admin/{realm-name}/console. Users within that realm can be granted realm management permissions by assigning specific user role mappings.

Each realm has a built-in client called realm-management. You can view this client by going to the Clients left menu item of your realm. This client defines client-level roles that specify permissions that can be granted to manage the realm.

Assign the roles you want to your users and they will only be able to use that specific part of the administration console.

When using Red Hat Single Sign-On as an identity broker, users are not forced to provide their credentials in order to authenticate in a specific realm. Instead, they are presented with a list of identity providers from which they can authenticate.

You can also configure a default broker. In this case the user will not be given a choice, but instead be redirected directly to the parent broker. The following diagram demonstrates the steps involved when using Red Hat Single Sign-On to broker an external identity provider:

There are some variations of this flow that we will talk about later. For instance, instead of presenting a list of identity providers, the client application can request a specific one. Or you can tell Red Hat Single Sign-On to force the user to provide additional information before federating his identity.

As you may notice, at the end of the authentication process Red Hat Single Sign-On will always issue its own token to client applications. What this means is that client applications are completely decoupled from external identity providers. They don’t need to know which protocol (eg.: SAML, OpenID Connect, OAuth, etc) was used or how the user’s identity was validated. They only need to know about Red Hat Single Sign-On.

The identity broker configuration is all based on identity providers. Identity providers are created for each realm and by default they are enabled for every single application. That means that users from a realm can use any of the registered identity providers when signing in to an application.

In order to create an identity provider click the Identity Providers left menu item.

In the right hand drop down list box, choose the identity provider you want to add. This will bring you to the configuration page for that identity provider type.

Above is an example of configuring a Google social login provider. Once you configure an IDP, it will appear on the Red Hat Single Sign-On login page as an option.

Although each type of identity provider has its own configuration options, all of them share some very common configuration. Regardless the identity provider you are creating, you’ll see the following configuration options avaivable:

For Internet facing applications, it is quite burdensome for users to have to register at your site to obtain access. It requires them to remember yet another username and password combination. Social identity providers allow you to delegate authentication to a semi-trusted and respected entity where the user probably already has an account. Red Hat Single Sign-On provides built-in support for the most common social networks out there, such as Google, Facebook, Twitter, Github, LinkedIn, Microsoft and StackOverflow.

Red Hat Single Sign-On can broker identity providers based on the OpenID Connect protocol. These IDPs must support the Authorization Code Flow as defined by the specification in order to authenticate the user and authorize access.

To begin configuring an OIDC provider, go to the Identity Providers left menu item and select OpenID Connect v1.0 from the Add provider drop down list. This will bring you to the Add identity provider page.

The initial configuration options on this page are described in General IDP Configuration. You must define the OpenID Connection configuration options as well. They basically describe the OIDC IDP you are communicating with.

You can also import all this configuration data by providing a URL or file that points to OpenID Provider Metadata (see OIDC Discovery specification). If you are connecting to a Red Hat Single Sign-On external IDP, you can import the IDP setttings from the url <root>/auth/realms/{realm-name}/.well-known/openid-configuration. This link is a JSON document describing metadata about the IDP.

Red Hat Single Sign-On can broker identity providers based on the SAML v2.0 protocol.

To begin configuring an OIDC provider, go to the Identity Providers left menu item and select SAML v2.0 from the Add provider drop down list. This will bring you to the Add identity provider page.

The initial configuration options on this page are described in General IDP Configuration. You must define the SAML configuration options as well. They basically describe the SAML IDP you are communicating with.

You can also import all this configuration data by providing a URL or file that points to the SAML IDP entity descriptor of the external IDP. If you are connecting to a Red Hat Single Sign-On external IDP, you can import the IDP setttings from the url <root>/auth/realms/{realm-name}/protocol/saml/descriptor. This link is an XML document describing metadata about the IDP.

You can also import all this configuration data by providing a URL or XML file that points to the entity descriptor of the external SAML IDP you want to connect to.

http[s]://{host:port}/auth/realms/{realm-name}/broker/{broker-alias}/endpoint/descriptor

Each identity provider has an option Authenticate By Default, which allows that Identity provider to be automatically selected during authentication. The user won’t see the Red Hat Single Sign-On login page and will instead be automatically redirected to the default identity provider.

OIDC applications can also bypass the Red Hat Single Sign-On login page by specifying a hint on which identity provider they want to use. This is done by appending the kc_idp_hint query parameter in the Authorization Code Flow authorization endpoint.

Red Hat Single Sign-On OIDC client adapters also allow you to specify this query parameter when you access a secured resource at the application.

For example

GET /myapplication.com?kc_idp_hint=facebook HTTP/1.1
Host: localhost:8080

In this case, is expected that your realm has an identity provider with an alias facebook.

If you are using keycloak.js adapter, you can also achieve the same behavior:

var keycloak = new Keycloak('keycloak.json');

keycloak.createLoginUrl({
	idpHint: 'facebook'
});

You can import the SAML and OpenID Connect metadata provided by the external IDP you are authenticating with into the environment of the realm. This allows you to extract user profile metadata and other information so that you can make it available to your applications.

Each new user that logs into your realm via an external identity provider will have an entry for it created in the local Red Hat Single Sign-On database. The act of importing metadata from the SAML or OIDC assertions and claims will create this data with the local realm database.

If you click on an identity provider listed in the Identity Providers page for your realm, you will be brought to the IDPs Settings tab. On this page is also a Mappers tab. Click on that tab to start mapping your incoming IDP metadata.

There is a Create button on this page. Clicking on this create button allows you to create a broker mapper. Broker mappers can import SAML attributes or OIDC ID/Access token claims into user attributes and user role mappings.

Select a mapper from the Mapper Type list. Hover over the tooltip to see a description of what the mapper does. The tooltips also describe what configuration information you need to enter. Click Save and your new mapper will be added.

For JSON based claims, you can use dot notation for nesting and square brackets to access array fields by index. For example 'contact.address[0].country'.

To investigate the structure of user profile JSON data provided by social providers you can enable the DEBUG level logger org.keycloak.social.user_profile_dump. This is done in the server’s app-server configuration file (domain.xml or standalone.xml).

After a user logs in from the external IDP, there’s some additional user session note data that Red Hat Single Sign-On stores that you can access. This data can be propagated to the client requesting a login via the token or SAML assertion being passed back to it by using an appropriate client mapper.

You can use a Protocol Mapper to propagate this information to your clients.

When a user logs in through identity brokering some aspects of the user are imported and linked within the realm’s local database. When Red Hat Single Sign-On successfully authenticates users through an external identity provider there can be two situations:

Different organizations have different requirements when dealing with some of the conflicts and situations listed above. For this, there is a First Login Flow option in the IDP settings which allows you to choose a workflow that will be used after a user logs in from an external IDP the first time. By default it points to first broker login flow, but you can configure and use your own flow and use different flows for different identity providers.

The flow itself is configured in admin console under Authentication tab. When you choose First Broker Login flow, you will see what authenticators are used by default. You can re-configure the existing flow. (For example you can disable some authenticators, mark some of them as required, configure some authenticators, etc).

Red Hat Single Sign-On allows you to store tokens and responses from the authentication process with the external IDP. For that, you can use the Store Token configuration option on the IDP’s settings page.

Application code can retrieve these tokens and responses to pull in extra user information, or to securely invoke requests on the external IDP. For example, an application might want to use the Google token to invoke on other Google services and REST APIs. To retrieve a token for a particular identity provider you need to send a request as follows:

GET /auth/realms/{realm}/broker/{provider_alias}/token HTTP/1.1
Host: localhost:8080
Authorization: Bearer {keycloak_access_token}

An application must have authenticated with Red Hat Single Sign-On and have received an access token. This access token will need to have the broker client-level role read-token set. This means that the user must have a role mapping for this role and the client application must have that role within its scope. In this case, given that you are accessing a protected service in Red Hat Single Sign-On, you need to send the access token issued by Red Hat Single Sign-On during the user authentication.

In the broker configuration page you can automatically assign this role to newly imported users by turning on the Stored Tokens Readable switch.

If you go to the Sessions left menu item you can see a top level view of the number of sessions that are currently active in the realm.

A list of clients is given and how many active sessions there currently are for that client. You can also logout all users in the realm by clicking the Logout all button on the right side of this list.

If your system is compromised you will want a way to revoke all sessions and access tokens that have been handed out. You can do this by going to the Revocation tab of the Sessions screen.

You can only set a time-based revocation policy. The console allows you to specify a time and date where any session or token issued before that time and date is invalid. The Set to now will set the policy to the current time and date. The Push button will push this revocation policy to any registered OIDC client that has the Red Hat Single Sign-On OIDC client adapter installed.

Red Hat Single Sign-On gives you fine grain control of session, cookie, and token timeouts. This is all done on the Tokens tab in the Realm Settings left menu item.

Let’s walk through each of the items on this page.

Offline access is a feature described in OpenID Connect specification . The idea is that during login, your client application will request an Offline token instead of a classic Refresh token. The application can save this offline token in a database or on disk and can use it later even if user is logged out. This is useful if your application needs to do some "offline" actions on behalf of user even when the user is not online. An example is a periodic backup of some data every night.

Your application is responsible for persisting the offline token in some storage (usually a database) and then using it to manually retrieve new access token from Red Hat Single Sign-On server.

The difference between a classic Refresh token and an Offline token is, that an offline token will never expire and is not subject of SSO Session Idle timeout . The offline token is valid even after a user logout or server restart. However by default you do need to use the offline token for a refresh token action at least once per 30 days (this value, Offline Session Idle timeout, can be changed in the administration console in the Tokens tab under Realm Settings). Also if you enable the option Revoke refresh tokens, then each offline token can be used just once. So after refresh, you always need to store the new offline token from refresh response into your DB instead of the previous one.

Users can view and revoke offline tokens that have been granted by them in the User Account Service. The admin user can revoke offline tokens for individual users in admin console in the Consents tab of a particular user. The admin can also view all the offline tokens issued in the Offline Access tab of each client. Offline tokens can also be revoked by setting a revocation policy.

To be able to issue an offline token, users need to have the role mapping for the realm-level role offline_access. Clients also need to have that role in their scope.

The client can request an offline token by adding the parameter scope=offline_access when sending authorization request to Red Hat Single Sign-On. The Red Hat Single Sign-On OIDC client adapter automatically adds this parameter when you use it to access secured URL of your application (i.e. http://localhost:8080/customer-portal/secured?scope=offline_access). The Direct Access Grant and Service Accounts also support offline tokens if you include scope=offline_access in the body of the authentication request.

To add a storage provider go to the User Federation left menu item in the Admin Console.

On the right side, there is an Add Provider list box. Choose the provider you want to add and you will be brought to the configuration page of that provider.

Red Hat Single Sign-On comes with a built-in LDAP/AD plugin. By default, it is set up only to import username, email, first name, and last name. But you are free to configure additional mappers and add more attributes or delete the default ones. It supports password validation via LDAP/AD protocols and different user metadata synchronization modes. To configure a federated LDAP store go to the Admin Console. Click on the User Federation left menu option. When you get to this page there is an Add Provider select box. You should see ldap within this list. Selecting ldap will bring you to the ldap configuration page.

Login events occur for things like when a user logs in successfully, when somebody enters in a bad password, or when a user account is updated. Every single event that happens to a user can be recorded and viewed. By default, no events are stored or viewed in the Admin Console. Only error events are logged to the console and the server’s log file. To start persisting you’ll need to enable storage. Go to the Events left menu item and select the Config tab.

To start storing events you’ll need to turn the Save Events switch to on under the Login Events Settings.

The Saved Types field allows you to specify which event types you want to store in the event store. The Clear events button allows you to delete all the events in the database. The Expiration field allows you to specify how long you want to keep events stored. Once you’ve enabled storage of login events and decided on your settings, don’t forget to click the Save button on the bottom of this page.

To view events, go to the Login Events tab.

As you can see, there’s a lot of information stored and, if you are storing every event, there are a lot of events stored for each login action. The Filter button on this page allows you to filter which events you are actually interested in.

In this screenshot, we’re filtering only Login events. Clicking the Update button runs the filter.

11:36:09,965 WARN  [org.keycloak.events] (default task-51) type=LOGIN_ERROR, realmId=master,
                    clientId=myapp,
                    userId=19aeb848-96fc-44f6-b0a3-59a17570d374, ipAddress=127.0.0.1,
                    error=invalid_user_credentials, auth_method=openid-connect, auth_type=code,
                    redirect_uri=http://localhost:8180/myapp,
                    code_id=b669da14-cdbb-41d0-b055-0810a0334607, username=admin

"eventsListener": {
    "email": {
        "exclude-events": [ "UPDATE_TOTP", "REMOVE_TOTP" ]
    }
}

Any action an admin performs within the admin console can be recorded for auditing purposes. The Admin Console performs administrative functions by invoking on the Red Hat Single Sign-On REST interface. Red Hat Single Sign-On audits these REST invocations. The resulting events can then be viewed in the Admin Console.

To enable auditing of Admin actions, go to the Events left menu item and select the Config tab.

In the Admin Events Settings section, turn on the Save Events switch.

The Include Representation switch will include any JSON document that is sent through the admin REST API. This allows you to view exactly what an admin has done, but can lead to a lot of information stored in the database. The Clear admin events button allows you to wipe out the current information stored.

To view the admin events go to the Admin Events tab.

If the Details column has a Representation box, you can click on that to view the JSON that was sent with that operation.

You can also filter for the events you are interested in by clicking the Filter button.

Import of most resources can be performed from the admin console. Exporting resources will be supported in future versions.

The files created during a "startup" export can be used to import from the admin UI. This way, you can export from one realm and import to another realm. Or, you can export from one server and import to another.

Like all UIs in Red Hat Single Sign-On, the User Account Service is completely themeable and internationalizable. See the Server Developer Guide for more details.

A brute force attack happens when an attacker is trying to guess a user’s password. Red Hat Single Sign-On has some limited brute force detection capabilities. If turned on, a user account will be temporarily disabled if a threshold of login failures is reached. To enable this feature go to the Realm Settings left menu item, click on the Security Defenses tab, then additional go to the Brute Force Detection sub-tab.

The way this works is that if there are Max Login Failures during a period of Failure Reset Time, the account is temporarily disabled for the Wait Increment multiplied by the number of failures over the max. After Failure Reset Time is reached all failures are wiped clean. The Max Wait is the maximum amount of time an account can be disabled. Another preventive measure is that if there are subsequent login failures for one account that are too quick for a human to initiate the account will be disabled. This is controlled by the Quick Login Check Milli Seconds value. So, if there are two login failures for the same account within that value, the account will be disabled for Minimum Quick Login Wait.

The downside of Red Hat Single Sign-On brute force detection is that the server becomes vulnerable to denial of service attacks. An attacker can simply try to guess passwords for any accounts it knows and these account will be disabled. Eventually we will expand this functionality to take client IP address into account when deciding whether to block a user.

A better option might be a tool like Fail2Ban. You can point this service at the Red Hat Single Sign-On server’s log file. Red Hat Single Sign-On logs every login failure and client IP address that had the failure. Fail2Ban can be used to modify firewalls after it detects an attack to block connections from specific IP addresses.

With clickjacking, a malicious site loads the target site in a transparent iFrame overlaid on top of a set of dummy buttons that are carefully constructed to be placed directly under important buttons on the target site. When a user clicks a visible button, they are actually clicking a button (such as a "login" button) on the hidden page. An attacker can steal a user’s authentication credentials and access their resources.

By default, every response by Red Hat Single Sign-On sets some specific browser headers that can prevent this from happening. Specifically, it sets X-FRAME_OPTIONS and Content-Security-Policy. You should take a look at the definition of both of these headers as there is a lot of fine-grain browser access you can control. In the admin console you can specify the values these headers will have. Go to the Realm Settings left menu item and click the Security Defenses tab and make sure you are on the Headers sub-tab.

By default, Red Hat Single Sign-On only sets up a same-origin policy for iframes.

If you do not use SSL/HTTPS for all communication between the Red Hat Single Sign-On auth server and the clients it secures you will be very vulnerable to man in the middle attacks. OAuth 2.0/OpenID Connect uses access tokens for security. Without SSL/HTTPS, attackers can sniff your network and obtain an access token. Once they have an access token they can do any operation that the token has been given permission for.

Red Hat Single Sign-On has three modes for SSL/HTTPS. SSL can be hard to set up, so out of the box, Red Hat Single Sign-On allows non-HTTPS communication over private IP addresses like localhost, 192.168.x.x, and other private IP addresses. In production, you should make sure SSL is enabled and required across the board.

On the adapter/client side, Red Hat Single Sign-On allows you to turn off the SSL trust manager. The trust manager ensures identity the client is talking to. It checks the DNS domain name against the server’s certificate. In production you should make sure that each of your client adapters is configured to use a truststore. Otherwise you are vulnerable to DNS man in the middle attacks.

Cross-site request forgery (CSRF) is a web-based attack whereby HTTP requests are transmitted from a user that the web site trusts or has authenticated with(e.g. via HTTP redirects or HTML forms). Any site that uses cookie based authentication is vulnerable to these types of attacks. These attacks are mitigated by matching a state cookie against a posted form or query parameter.

The OAuth 2.0 login specification requires that a state cookie be used and matched against a transmitted state parameter. Red Hat Single Sign-On fully implements this part of the specification so all logins are protected.

The Red Hat Single Sign-On Admin Console is a pure JavaScript/HTML5 application that makes REST calls to the backend Red Hat Single Sign-On admin REST API. These calls all require bearer token authentication and are made via JavaScript Ajax calls. CSRF does not apply here. The admin REST API can also be configured to validate the CORS origins as well.

The only part of Red Hat Single Sign-On that really falls into CSRF is the user account management pages. To mitigate this Red Hat Single Sign-On sets a state cookie and also embeds the value of this state cookie within hidden form fields or query parameters in action links. This query or form parameter is checked against the state cookie to verify that the call was made by the user.

For the Authorization Code Flow, if you register redirect URIs that are too general, then it would be possible for a rogue client to impersonate a different client that has a broader scope of access. This could happen for instance if two clients live under the same domain. So, it’s a good idea to make your registered redirect URIs as specific as feasible.

There are a few things you can do to mitigate access tokens and refresh tokens from being stolen. The most important thing is to enforce SSL/HTTPS communication between Red Hat Single Sign-On and its clients and applications. This might seem like a no-brainer, but since Red Hat Single Sign-On does not have SSL enabled by default, many naive admins might not realize they have to do this.

Another thing you can do to mitigate leaked access tokens is to shorten their lifespans. You can specify this within the timeouts page. Short lifespans (minutes) for access tokens for clients and applications to refresh their access tokens after a short amount of time. If an admin detects a leak, they can logout all user sessions to invalidate these refresh tokens or set up a revocation policy. Making sure refresh tokens always stay private to the client and are never transmitted ever is very important as well.

If an access token or refresh token is compromised, the first thing you should do is go to the admin console and push a not-before revocation policy to all applications. This will enforce that any tokens issued prior to that date are now invalid. You can also disable specific applications, clients, and users if you feel that any one of those entities is completely compromised.

For the OIDC Auth Code Flow, it would be very hard for an attacker to compromise Red Hat Single Sign-On access codes. Red Hat Single Sign-On generates a cryptographically strong random value for its access codes so it would be very hard to guess an access token. An access code can only be used once to obtain an access token. In the admin console you can specify how long an access token is valid for on the timeouts page. This value should be really short, as short as a few seconds and just long enough for the client to make the request to obtain a token from the code.

An attacker could use the end-user authorization endpoint and the redirect URI parameter to abuse the authorization server as an open redirector. An open redirector is an endpoint using a parameter to automatically redirect a user agent to the location specified by the parameter value without any validation. An attacker could utilize a user’s trust in an authorization server to launch a phishing attack.

Red Hat Single Sign-On requires that all registered applications and clients register at least one redirection URI pattern. Any time a client asks Red Hat Single Sign-On to perform a redirect (on login or logout for example), Red Hat Single Sign-On will check the redirect URI vs. the list of valid registered URI patterns. It is important that clients and applications register as specific a URI pattern as possible to mitigate open redirector attacks.

Red Hat Single Sign-On does not store passwords in raw text. It stores a hash of them using the PBKDF2 algorithm. It actually uses a default of 20,000 hasing iterations! This is the security community’s recommended number of iterations. This can be a rather large performance hit on your system as PBKDF2, by design, gobbles up a significant amount of CPU. It is up to you to decide how serious you want to be to protect your password database.

By default, each new client application has an unlimited scope. This means that every access token that is created for that client will contain all the permissions the user has. If the client gets compromised and the access token is leaked, then each system that the user has permission to access is now also compromised. It is highly suggested that you limit the roles an access token is assigned by using the Scope menu for each client.

At this point in time, there is no knowledge of any SQL injection vulnerabilities in Red Hat Single Sign-On.