Red Hat Single Sign-On Administration
Configure Red Hat Single Sign-On to authorize users and applications using the OpenID Connect (OIDC) protocol and the RBAC features of RH-SSO.
Red Hat Single Sign-On manages the authorization of users and applications by adding access claims to the OIDC tokens, or SAML assertions. The applications make access decisions by reading the claims that contain access information.
As an RH-SSO administrator, you control the access information by using different strategies and policies. The most used strategy is role-based access control (RBAC), although RH-SSO can use other fine-grained strategies such as attribute-based access control (ABAC), or rule-based access control.
An RBAC system is based on the concept of roles. A role represents a category of users, or applications, that have access to perform a specific task.
Note
To learn more about other authorization strategies, different from RBAC, refer to the Authorization Services Guide at https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.6/html-single/authorization_services_guide/index
In RH-SSO the roles are defined only with a string text.
The applications need to use that string text to make decissions related to authorization.
For example, the following Java code defines a resource only accesible by the users present in the auditors role.
import javax.annotation.security.RolesAllowed;
import javax.ws.rs.Path;
@Path("/showinvoices")
@RolesAllowed("auditors")
public class ShowInternalFinanceDocuments
... omitted ...RH-SSO defines the following three role types:
- Realm roles
The realm roles represent the responsibilities of a user in an organization. You can manage the realm roles from the RH-SSO Admin Console, by using the → menu.
Figure 3.14: Roles menu in RH-SSO Admin Console.There are other types of realm roles, which are the default roles. The default roles are realm roles that are assigned to every new user.
- Client Roles
Client roles are specific only to a client or application. Only the application understands its client roles.
- Composite roles
Composite roles allow you to chain other roles. Composite roles can be composed of client and realm roles.
You can transform any existing role into a composite role in the Admin Console, by activating the
Composite rolecontrol in the → menu.
Figure 3.15: Composite roles menu in RH-SSO Admin Console.
You can assign realm roles to groups or to users by using the Role Mappings tab when editing a user or a group.
Red Hat recommends avoiding defining a high number of roles. The higher the number of roles is, the harder it is to maintain the coherence of the access control.
Red Hat recommends using groups of users to assign the roles, instead of assigning roles directly to the users.
Note
To learn more about fine-grained authorization strategies, refer to the Authorization Services Guide at https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.6/html-single/authorization_services_guide/index
The OIDC and the JSON web Token (JWT) specifications define a set of standard claims, which include name, email, and others.
RH-SSO adds the authorization information to the OIDC tokens, or to SAML assertions.
As an RH-SSO administrator, you can define the content of the token claims by configuring the scopes of each client.
The concept of scope has many uses in SSO systems, and also in RH-SSO.
It has its origin in the OAuth2 specification.
In OAuth2, there is a scope claim that an external client has to include in the request to the identity provider.
The identity provider asks the user for consent to that specific client, to access a specific scope of the user identity data.
The use of OAuth2 scopes is another strategy for authorization, only for clients, or applications, external to the realm.
RH-SSO extends this use of the scope concept.
- Client scopes
In RH-SSO, a client scope is a shared configuration for more than one client. This configuration includes protocol mappers and role bindings. You can access the realm client scopes from the → menu, within the RH-SSO Admin Console.
Protocol mappers are transformations that RH-SSO performs on tokens, and are useful to map access information to token claims. Protocol mappers are always associated with the SAML or the OIDC protocol, but never with both at the same time.
You can configure protocol mappers for each client from the tab in the client configuration. You can configure role bindings for each client from the tab in the client configuration.
Client scopes are a way of adding protocol mappers and role bindings to more than one client. The following image shows preconfigured client scopes that are always assigned to new clients by default in a realm.
Figure 3.17: Client scopes always added to each client claim.You can see the protocol mappers associated to each client scope by clicking its name from the
Client Scopestab, and then the tab.
Figure 3.18: Protocol mappers of the "microprofile-jwt" client scopeClick the name of one protocol mapper to see its definition.
The tokens fill up the claims that are defined through the assigned scopes, and the protocol mappers of such scopes.
The assigned scopes can be:
At the realm level, with client scopes.
At the client level, with scopes defined only for one client.
The RH-SSO Admin Console contains a utility to inspect the tokens that a client emits for a specific user, after adding all the claims from all the scopes and mappings. The utility is located in the → page, under the tab, and its sub tab.
- Limiting the access of the token
As an RH-SSO admin you must control which actions a user can perform with a token. For example, an access token emitted for a client should not be used to access a resource in another client. The following example shows a snippet of an access token emitted by the
finance-webappapplication to thealiceuser. The user is assigned to thefinance-adminandsuperbossrealm roles.
{
...output omitted
"iss": "https://sso.lab.example.com:8080/auth/realms/rhtraining",
"typ": "Bearer",
"azp": "finance-webapp",
"session_state": "0c50039f-4719-4eed-9f05-fad42fe4dce2",
"acr": "1",
"allowed-origins": [
"http://localhost:8080"
],
"realm_access": {
"roles": [
"finance-admin",
"superboss"
]
},
"scope": "openid email profile",
"sid": "0c50039f-4719-4eed-9f05-fad42fe4dce2",
"email_verified": false,
"name": "Alice Liddel",
"preferred_username": "alice",
"given_name": "Alice",
"family_name": "Liddel",
"email": "alice@keycloak.org"
}Although the token is emitted for the finance-webapp client, it includes all the roles assigned to the alice user.
If an attacker steals the token, then they could access not only the finance-webapp client, but also other clients that use the superboss role.
To limit the access of a token emitted for a client, you need to configure the client to only allow specific roles. You can limit the roles from the RH-SSO Admin Console, in the client configuration, from the tab.
In the previous image, the finance-webapp client has the set to OFF.
You can select which realm roles and client roles to assign to the client.
If you assign only the finance-admin role to the scope of the client, then the access token only includes this role, despite the fact that the alice user is also assigned to the superboss role.
References
For more information about fine-grained access control, refer to the Authorization Services Guide from the Red Hat Single Sign-On documentation, at https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.6/html-single/authorization_services_guide/index
For more information about assigning access with roles, refer to the _ Assigning permissions and access using roles and groups_ chapter in the Server Administration Guide from the Red Hat Single Sign-On documentation at https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.6/html-single/server_administration_guide/index#assigning_permissions_and_access_using_roles_and_groups