Introduction to Claims

Introduction to Claims


What are Claims and How Are They Used?


When designing a token-based architecture, it’s important to understand how identity data is passed around in the system. Claims provide a fundamental means for how to trust that the data is valid and true.

This article aims to explain what claims are and how they should be used.

What are claims?

A claim is statement that a particular entity has a particular property. The claim is asserted by some entity - the asserting party states that the subject has some attribute.

In authentication, we usually think of claims as assertions about a user, as asserted by the Identity Provider.

Its an assertion

Claims are assertions - they allow the application to trust attributes about a user.

The anatomy of claims

A claim can be made in plain text.

  • “Jim is a father,” Alexa says.
  • “Tom likes baseball,” states Oliver.
  • “Lisa is the newest member of the accounting team,” Jan asserts.

Here is an OAuth example:

  • “Curity states that the Resource Owner has this list of attributes.”
Asserting PartySubjectClaims
CurityResource OwnerAttributes


It is important to note that a claim is only usable as a statement of fact if and only if the party asserting it is trusted. Of course, it is possible to accept a claim and use it even if it’s not from a trusted source, but mixing trusted and untrusted claims in the same source (e.g. a token) is not recommended.


On the technical level, the value in a claim can be anything - a string, a dictionary, a list, a simple boolean or anything else. Of course if you want to use something very unusual, you need to make sure that it can be managed by any application that needs to handle it.

Claims mapped to scopes

Claims are mapped to a Scope (scope of access). In Curity this can be arbitrarily mapped. Read more about claims and scopes here.

Default claims

With OpenID Connect, we get a default set of basic claims for user details which provides a clear framework, giving a proper interface to applications, while allowing the user a good grasp of what information they are sharing.

The OpenID Connect standard defines a standardized grouping:

emailemail, email_verified
profilename, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at
phonephone_number, phone_number_verified
openidsub, auth_time, acr

Why claims?

While you may consider a claim a simple name/value pair inside Access and ID Tokens, you should keep their primary purposes in mind. They are a way of allowing the user to consent to what data it shares with an application or API (discussed in the consent overview). They are also a way to enable applications to provide services and perform actions on the user’s behalf.

When to use Claims

Claims are the contents of tokens. In essence this means that the claims in the token become the API or contract between the OpenID Connect provider and the Client. The Client is configured to be allowed to receive a certain set of claims. If the user consents to this, these are issued and the tokens are populated accordingly.

In systems where identity information needs to be communicated to the Client (or the API), claims are the way to provide this. Claims can range from the user’s email to more system specific things such as a subscriber-id or favourite color.

However, the rule of thumb is that it should be a generally useful value, and not too application specific.


A user-preferred background color in the app is not a generally useful claim since it is app specific.

Favourite color is a better claim since it provides general information about the user.

A note on tokens

When including claims in the token, you have complete freedom to provide an abundance of claims. But as always, this should be done advisedly and with consideration of the possible consequences. As a best practice, try to keep the claims provided to a minimum, only providing specifically requested claims or a base set that most applications and APIs need. The claims in the Token form an API between the identity server and the token consumer. Changing the content of a token should be considered a breaking change.

Scopes and claims in use

When used in the authorization flows, the client sends an authorize request, including the scope or scopes or specific claims it needs (and ideally, only those it needs) to the OpenID Connect provider. This eventually results in the issuance of one or many tokens, which contains claims according to the requested scopes.

Claims, not scope

If the request is for less than the full scope, the returned token contains a list of claims, and does not include the scope itself.

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.

Keep up with our latest articles and how-tos RSS feeds.