Chapter 11. Admin Console Access Control and Permissions

There are two realm-level roles in the master realm. These are:

Users with the admin role are super users and have full access to manage any realm on the server. Users with the create-realm role are allowed to create new realms. They will be granted full access to any new realm they create.

Admin users within the master realm can be granted management privileges to one or more other realms in the system. Each realm in Red Hat Single Sign-On is represented by a client in the master realm. The name of the client is <realm name>-realm. These clients each have client-level roles defined which define varying level of access to manage an individual realm.

The roles available are:

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

Let’s look first at allowing an admin to manage one client and one client only. In our example we have a realm called test and a client called sales-application. In realm test we will give a user in that realm permission to only manage that application.

Another thing you might want to do is to restrict the set a roles an admin is allowed to assign to a user. Continuing our last example, let’s expand the permission set of the 'sales-admin' user so that he can also control which users are allowed to access this application. Through fine grain permissions we can enable it so that the sales-admin can only assign roles that grant specific access to the sales-application. We can also restrict it so that the admin can only map roles and not perform any other types of user administration.

The sales-application has defined three different client roles.

We want the sales-admin user to be able to map these roles to any user in the system. The first step to do this is to allow the role to be mapped by the admin. If we click on the viewLeads role, you’ll see that there is a Permissions tab for this role.

If we click on that tab and turn the Permissions Enabled on, you’ll see that there are a number of actions we can apply policies to.

The one we are interested in is map-role. Click on this permission and add the same User Policy that was created in the earlier example.

What we’ve done is say that the sales-admin can map the viewLeads role. What we have not done is specify which users the admin is allowed to map this role too. To do that we must go to the Users section of the admin console for this realm. Clicking on the Users left menu item brings us to the users interface of the realm. You should see a Permissions tab. Click on that and enable it.

The permission we are interested in is map-roles. This is a restrictive policy in that it only allows admins the ability to map roles to a user. If we click on the map-roles permission and again add the User Policy we created for this, our sales-admin will be able to map roles to any user.

The last thing we have to do is add the view-users role to the sales-admin. This will allow the admin to view users in the realm he wants to add the sales-application roles to.

You can do a lot more with fine grain permissions beyond managing a specific client or the specific roles of a client. This chapter defines the whole list of permission types that can be described for a realm.

It’s recommended to regularly rotate keys. To do so you should start by creating new keys with a higher priority than the existing active keys. Or create new keys with the same priority and making the previous keys passive.

Once new keys are available all new tokens and cookies will be signed with the new keys. When a user authenticates to an application the SSO cookie is updated with the new signature. When OpenID Connect tokens are refreshed new tokens are signed with the new keys. This means that over time all cookies and tokens will use the new keys and after a while the old keys can be removed.

How long you wait to delete old keys is a tradeoff between security and making sure all cookies and tokens are updated. In general it should be acceptable to drop old keys after a few weeks. Users that have not been active in the period between the new keys where added and the old keys removed will have to re-authenticate.

This also applies to offline tokens. To make sure they are updated the applications need to refresh the tokens before the old keys are removed.

As a guideline it may be a good idea to create new keys every 3-6 months and delete old keys 1-2 months after the new keys where created.

To add a new generated keypair select Providers and choose rsa-generated from the dropdown. You can change the priority to make sure the new keypair becomes the active keypair. You can also change the keysize if you want smaller or larger keys (default is 2048, supported values are 1024, 2048 and 4096).

Click Save to add the new keys. This will generated a new keypair including a self-signed certificate.

Changing the priority for a provider will not cause the keys to be re-generated, but if you want to change the keysize you can edit the provider and new keys will be generated.

To add a keypair and certificate obtained elsewhere select Providers and choose rsa from the dropdown. You can change the priority to make sure the new keypair becomes the active keypair.

Click on Select file for Private RSA Key to upload your private key. The file should be encoded in PEM format. You don’t need to upload the public key as it is automatically extracted from the private key.

If you have a signed certificate for the keys click on Select file next to X509 Certificate. If you don’t have one you can skip this and a self-signed certificate will be generated.

To add a keypair and certificate stored in a Java Keystore file on the host select Providers and choose java-keystore from the dropdown. You can change the priority to make sure the new keypair becomes the active keypair.

Fill in the values for Keystore, Keystore Password, Key Alias and Key Password and click on Save.

Locate the keypair in Active or All then click on the provider in the Provider column. This will take you to the configuration screen for the key provider for the keys. Click on Active to turn it OFF, then click on Save. The keys will no longer be active and can only be used for verifying signatures.

Locate the keypair in Active or All then click on the provider in the Provider column. This will take you to the configuration screen for the key provider for the keys. Click on Enabled to turn it OFF, then click on Save. The keys will no longer be enabled.

Alternatively, you can delete the provider from the Providers table.

Red Hat Single Sign-On has the signing keys stored just locally and they are never shared with the client applications, users or other entities. However if you think that your realm signing key was compromised, you should first generate new keypair as described above and then immediatelly remove the compromised keypair.

Then to ensure that client applications won’t accept the tokens signed by the compromised key, you should update and push not-before policy for the realm, which is doable from the admin console. Pushing new policy will ensure that client applications won’t accept the existing tokens signed by the compromised key, but also the client application will be forced to download new keypair from the Red Hat Single Sign-On, hence the tokens signed by the compromised key won’t be valid anymore. Note that your REST and confidential clients must have set Admin URL, so that Red Hat Single Sign-On is able to send them the request about pushed not-before policy.