Claims Explained

Claims Explained

architect

Scopes, claims, tokens and all the things in between

Overview

This article provides a comprehensive overview of the claims ontology - Scopes, claims, tokens and how they are connected.


Getting to the basics

When getting into working with claims, you might feel confused and overwhelmed, especially if trying to start from the standards specification.

However, while there are a few moving parts, and some of them may feel like they are interacting in unexpected ways the basics are rather graspable.

If you haven't read the introduction we recommend to do so before reading this article.

Claims in depth

Let's start with a walk through of the elements involved.

Attributes

A natural place to start is an attribute that a user or other entity has:

image

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, but lost the assertion part.

An attribute is minimally defined as a name/value pair, specifying some attribute, and the value for that attribute.

image

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. It does not have to be a one-to-one mapping, it is perfectly possible to use multiple different attributes to create one claim:

image

The claims also have names and values, which may be different from the attributes used to create the claim, and attribute values may be transformed as the claim is asserted.

Claims to Scopes

The claims are grouped into scopes

image

A scope is a group of claims, and the standard includes a small set of default scopes and claims. See Default Scopes and Claims. There is no limit or specified rules for how you create your own groupings though. You can even create your own scopes containing claims already defined in other scopes, including the standard ones.

Also, the scopes themselves can be ordered into a name hierarchy, thereby having scopes grouped into higher order scopes, which is useful in order to avoid having to create a new scope for every single purpose.

Prefix Scopes

With prefix scopes, you only have the scope, they do not contain claims themselves, since their purpose is to act as "wildcards", and provide more flexibility. The wildcard scope is explained more in details in the Understanding Scopes.

In other aspects they will behave as regular scopes:

image

Mapping Claims

In order to manage the claims structure, and to use them to form tokens, we have a Claims Mapper.

image

The Claims Mapper uses the claims to create the various tokens, by aggregating claims according to the configuration we set up:

image

When tokens are issued, they contain the scopes and claims. What exactly the token contains of course depends on what requests for access have been made, and what the configuration look like:

image

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.

image

The clients can request tokens from the token service, and can be configured to restrict what tokens may be issued for the particular client:

image

Conclusion

And we now have a complete overview of the claims involving the major parts:

image

The claims infrastructure is an important part of any OpenID Connect Provider as it provides definitions not only about what a token should look like, but for what client it should have certain contents.

The claim values serve as information on which the API or 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.

More information

For more information, see the mentioned articles above, or the Curity Developer Portal

Was this page helpful?