Groups Authorization Manager

The Curity Identity Server provides SCIM and GraphQL API endpoints for managing customer user accounts. GraphQL can also be used to manage other identity resources, including OAuth database clients. The following tutorials introduce the endpoints. An organization can access these APIs using either a built-in client called the DevOps Dashboard, or from its own client applications.

• SCIM User Management
• GraphQL User Management
• GraphQL Client Management

Since the identity resources contain sensitive information, access must be authorized. The groups authorization manager is used to enable coarse-grained authorization. This tutorial explains how the groups authorization manager is used, with the DevOps Dashboard as an example client. The same techniques can also be followed for an organization's own clients, if they need to call the GraphQL endpoints.

Access Tokens

When granting group access, start by understanding the client's access token payload. Any client that uses the groups authorization manager, including the DevOps dashboard, must get an access token containing a groups claim. An example for the DevOps dashboard is shown below, where the user is a member of the developers group.

{
  "sub": "janedoe",
  "purpose": "access_token",
  "iss": "https://localhost:8443/oauth/v2/oauth-anonymous",
  "active": true,
  "groups": [
    {
      "type": "",
      "value": "developers",
      "primary": true
    }
  ],
  "token_type": "bearer",
  "client_id": "devops_dashboard_restconf_client",
  "aud": [
    "urn:se:curity:audiences:admin:api",
    "devops_dashboard_restconf_client"
  ],
  "nbf": 1671185832,
  "scope": "openid urn:se:curity:scopes:admin:api",
  "exp": 1671186132,
  "delegationId": "acbb74b4-7d7c-4723-9f4e-eb1af497b950",
  "iat": 1671185832
}

Employee Groups

It is common for employees to already exist, with assigned roles or groups, in a cloud platform. Thus, if the cloud platform's identity provider is used for employee logins, the source role or group can be received as an authentication attribute. The DevOps dashboard tutorial provides an example deployment that simulates a source authentication attribute being set, using a script authentication action:

function result(context) {
    
    var attributes = context.attributeMap;

    if (attributes.subject === 'johndoe') {
        attributes.role = 'devops';
    }

    if (attributes.subject === 'janedoe') {
        attributes.role = 'developer';
    }
    
    return attributes;
}

In a real deployment, an organization would simply receive the groups claim from the external system and no script would be required. For an example, see the Authenticate using Azure Active Directory tutorial.

The Groups Claim

To issue the groups claim, navigate to Profiles → Token Service → Scopes and add a claim called groups, that is issued by the subject claims provider:

This must be a string array containing the group values, so it is common to need to use a small procedure to transform the source value:

function transform(attributes) {
  return [attributes.role];
}

Next, the groups claim must be added to a scope. When using the DevOps dashboard as a client, add the groups claim to the built-in scope of urn:se:curity:scopes:admin:api. For an organization's own clients, the groups claim should be added to a custom scope instead. Finally, ensure that the scope is then dragged into the access token pane of the token designer window:

Groups Claim Names

For convenience, the Curity Identity Server provides a default admin user. This is then saved to the XML configuration during backups. It is possible to add new users that are managed in this way, and to associate groups and permissions to them, as explained in the Access Control Rules tutorial.

To use the DevOps dashboard, this type of user requires a different group claim name. Therefore, ensure that you also add the longer group claim to the scope if you want to grant dashboard access to these users.

Coarse-Grained Authorization

Once group setup is understood, the authorization manager itself is configured by navigating to System → Authorization. When adding a groups authorization manager, first specify a scope. When this is the DevOps dashboard, the built-in scope of openid urn:se:curity:scopes:admin:api should be included. Additional scopes used by other clients can also be added.

Next assign create, read, update and delete permissions to each group. For dashboard clients, these CRUD values are combined with identity areas that each employee group is allowed to access.

Other Authorization Options

For further control over authorization, it is straightforward to upgrade to the Attribute Authorization Manager. This is configured in a similar way to the groups authorization manager, and enables finer control at both the resource and attribute level. It is therefore the preferred option for an organization's own applications.

Conclusion

The groups authorization manager allows multiple groups of users to be granted different access to identity resources. This is done by issuing access tokens with a scope that allows access, and a groups claim that can be used for authorization. Only coarse-grained access is enabled, so organizations should use the attribute authorization manager when greater control is needed.