Scopes and Claims#

Scopes are defined by RFC 6749 Section 3.3 as the permissions that the user grants the application (the client). Common practice is that these scopes are defined by, and represent, the APIs that the applications need access too.

Scopes are defined as simple strings or prefixes, and must be configured in the profile before they can be assigned to a client.

Claims are defined in Section 5. of the OpenID Connect Core specification. A claim is an attribute, that has a name and a value that is asserted by the issuer of the token, i.e. a claimed value. Where OpenID Connect specifies only profile-related claims, Curity Identity Server considers claims a more generic concept beyond those claims that are standardized by OpenID Connect.

Where OpenID Connect specifies a limited set of scopes to act as groups of claims (e.g. the email scope represents the claims email and email_verified), with Curity you can specify your own scope-to-claim mappings.

In general, Curity considers a scope a group of claims. When reading about scopes throughout this section, always keep that in mind. The exception to this, are prefix scopes, which can not contain claims by definition.

The Scopes and Claims designer#

The Scopes and Claims designer is a visual tool within the Curity Identity Server administrative UI that allows you to manage scopes and their associated claims efficiently. It provides an intuitive interface to create, edit, and organize scopes and claims, making it easier to configure and maintain your authorization settings.

Adding a scope to the profile#

When creating a new scope, the following factors need to be considered:

1. What should the scope be called
2. What claims, if any, should the scope represent
3. How long should it be valid for
4. Whether the scope is required
5. Whether the scope is a prefix scope

These questions will be discussed in the next sections, and the first is a matter of policy. Many organizations name their scopes according to some domain+operation schema. Such as insurance_read, books_write or titles_admin.

Curity does not enforce any particular naming scheme but recommend to not create too many scopes per function since it tends to explode in numbers and implode in usability. Prefix scopes may be a solution for cases where fine-grained access needs to be defined, as we’ll see below.

Adding a scope to a client#

When the scope exists in the profile’s configuration, it can be added to clients that should be allowed to request it, and by indirection, request the claims that the scope contains. Each client configuration holds a list of references to some or all of the existing profile’s scopes.

Claims of a scope#

All scopes can contain a number of claims.

When a scope does not include a claim, it can be marked as consentable. This means that when interactive consent is enabled for a client, the scope will show up in the list of items that a user must consent to.

When a scope includes claims, a request for that scope will translate in a request to the claims of the requested scope. It also works the other way around, except for prefix scopes: when all claims associated with a particular scope are requested (and successfully issued), then the scope itself will be added to the token.

There are quite some nuances to using claims, which are explained in the rest of this section.

Claims I/O#

In order to get claims included in a token, a client can request either a scope that represents a set of claims as configured, or it can request individual claims through the claims request parameter . The claims a client is allowed to request is restricted by the claims of the scopes that are configured for the client to be allowed to request.

If a client requests a scope, and all the claims of that scope are allowed (i.e. consent is given to release all the requested claims of that scope, either implicit or explicit), then a token is returned that contains both the requested scope as well as the claims of that scope. If one of the claims of the scope is not granted, then the token is issued with the allowed claims but without that scope. In other words: if a token is issued with a scope, then all the claims of the scope are also in the token.