Scopes, claims, tokens and everything in between
This article provides a comprehensive overview of the claims ontology: scopes, claims, tokens and how they are related.
Getting to the basics¶
When first working with claims, you might feel confused and overwhelmed, especially if starting from the standards specification.
However, while there are a few moving parts, and some of them may seem to interact in unexpected ways, the basics are not difficult to grasp.
If you haven't read the introduction, we recommend doing so before reading this article.
Claims in depth¶
Let's start with a walk-through of the elements involved.
A natural place to start is with an attribute that a user or other entity has.
Attributes are properties of the entity but are not themselves assertions and are therefore not claims. However, they may have been claims at some point and have since been incorporated in some way, only without an assertion.
An attribute is minimally defined as a name/value pair, specifying some attribute and the value for that attribute.
Attributes in Curity
In Curity, attributes can come from a number of sources: Authentication Attributes from login, Account Attributes retrieved from a data source with accounts, and/or simply fetched from generic data sources.
Attributes to Claims¶
The attributes provide a source of information to create the claims. This does not have to involve a one-to-one mapping. It is perfectly possible to use multiple attributes to create one claim.
Claims also have names and values that may be different from the attributes used to create them and attribute values may be transformed as a claim is asserted.
Claims to Scopes¶
Claims are grouped into scopes
A scope is a group of claims, and the standard includes a small set of default scopes and claims. See Default Scopes and Claims. But there is no limit or specific rule for how to create your own groupings. You can even create your own scopes containing claims already defined in other scopes including the standard ones.
Moreover, the scopes themselves can be ordered into a name hierarchy. Grouping scopes into higher order scopes is a useful way to avoid having to create a new scope for every single purpose.
With prefix scopes, there is only the scope. Prefix scopes do not contain claims themselves since their purpose is to act as "wildcards" providing maximum flexibility. The wildcard scope is explained in more detail in Understanding Scopes.
In other aspects they behave as regular scopes.
In order to manage the claims structure and use the claims to form tokens, there is a Claims Mapper.
The Claims Mapper uses claims to create various tokens by aggregating claims according to the configuration that has been set up.
When tokens are issued, they contain scopes and claims. What the token contains exactly depends of course on what requests for access have been made and what the configuration looks like.
The claims mapper is also used to configure clients, which are object representations of the Clients in the request flow. These client configurations define what a Client is allowed to do, including how claims are mapped into the tokens of a client request.
Clients can request tokens from the token service and can be configured to restrict what tokens may be issued for a particular Client.
We now have a complete overview of claims involving all the major parts.
The claims infrastructure is an important part of any OpenID Connect Provider, as it provides definitions not only concerning what a token should look like but also with regard to what contents the token should have for a Client.
The claim values serve to determine whether the API or the Client can make authorization decisions further down the line.
The Curity Solution¶
Curity provides the full benefits of OAuth and OpenID Connect standards, but also offers additional functionality to combat the risk for scope explosion.
There is also special handling of claims and scopes, such as mapping claims to specific clients and custom groupings that allow for greater flexibility and a more manageable architecture.
For more information, see the mentioned articles above, or the Curity Developer Portal