---
title: "Groups Authorization Manager"
description: "A tutorial on how to protect identity resources using the groups authorization manager."
url: "https://curity.io/resources/learn/groups-authorization-manager/"
date: "2023-09-01"
area: "tutorials"
topic: "howtos"
pagegroup: "users"
---

# 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](https://curity.io/resources/learn/user-management/)
-   [GraphQL User Management](https://curity.io/resources/learn/graphql-user-management/)
-   [GraphQL Client Management](https://curity.io/resources/learn/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](https://curity.io/resources/learn/devops-dashboard-user-administration/) 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.

```json
{
  "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:

```javascript
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 Microsoft Entra ID](https://curity.io/resources/learn/oicd-authenticator-azure/) 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:

![Token Designer](https://curity.io/images/resources/tutorials/configuration/devops-dashboard/groups-claim-configuration.jpg)

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:

```javascript
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:

![Token Designer](https://curity.io/images/resources/tutorials/configuration/devops-dashboard/groups-claim-token.jpg)

## 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](https://curity.io/resources/learn/admin-access-rules/) tutorial.

![Built In Users](https://curity.io/images/resources/tutorials/configuration/devops-dashboard/built-in-users.jpg)

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.

| User Type | Groups Claim Name |
| --- | --- |
| Users saved to XML Configuration | urn:se:curity:claims:admin:groups |
| Users from an external system or data source | groups |

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

![User Access Levels](https://curity.io/images/resources/tutorials/configuration/devops-dashboard/user-access-levels.jpg)

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](https://curity.io/resources/learn/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.
