Claims Explained

Claims Explained

On this page

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: name and value

Attributes in Curity

In the Curity Identity Server, 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.

Using multiple attributes to create a 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

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

Prefix Scopes

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.

Mapping Claims

In order to manage the claims structure and use the claims to form tokens, a Claims Mapper is used.

Claims mapper

The Claims Mapper maps the claims to tokens by aggregating them according to the configuration that has been set up. This means that even if a claim is issued based on what scope a client requested, it may end up in a token that the client cannot read. As an example, the claims mapper may map PII sensitive claims into the Access Token which is opaque to the client but visible to the API.

Putting It Together

We start with a client.

Claims mapper: Setting up a client

The client is allowed to request certain scopes, based on its configuration.

Claims mapper: Allowing the client to request certain scopes

These scopes map to claims that now are allowed to be used by the client.

Claims mapper: Mapping scopes to claims allowed to be used by the client

Once they are issued, the Claims Mapper maps them into a token or the User Info Endpoint.

Claims mapper mapping claims into a token or the User Info Endpoint


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.

Highly sophisticated token based architectures can be constructed by understanding and utilizing the claims subsystem. Tokens can be designed to provide the APIs and Clients information via claims with high precision, something that is impossible when only using scopes.

The Curity Solution

With the Curity Identity Server, you get a Single Sign-On solution with all the benefits of the OpenID Connect standard, but also offers expanded features based on these standards, with a clearly implemented Neo-Security Architecture.

The Curity Identity Server does provide the standard OpenID Connect benefits for SSO, but also enables a range of other options that further improve the SSO experience and security.

The unified experience

Since you are sharing the SSO session between domains, it makes sense to also make that clear to the user through a unified user experience. In the Curity Identity Server, this is automatically enabled through the configuration.

Define the data

In the Curity Identity Server you can define in detail not only how to share the SSO session, but also specify which other data to share, allowing for differentiated security based on which client is making requests.

Embeddable OpenID Connect

In the Curity Identity Server, it's possible to run an OpenID Connect flow in a secure iframe. This means that the frame is only embeddable from the sites that have been pre-configured in the Curity Identity Server. Any other attempt to embed the frame will cause the frame to not load or to break out.

This makes it possible for organizations keep the user on the same site even when authenticating.

Single Logout

Not only does the Curity Identity Server support SSO but it also supports all single logout mechanisms defined in the OpenID Connect standard, giving you the perfect tools for ensuring that SSO is securely cleaned up.

More information

For more information, see the Curity Developer Portal.