Introduction to Claims

Introduction to Claims

architect

What are Claims and How They Are Used

Overview

When designing a token based architecture it's important to understand how identity data is passed around in the system. Claims provides 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, asserted by the Identity Provider.

It's 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.

Or for a more OAuth example:

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

Trust

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.

Values

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 strange, you need to make sure that, whatever it is, also is manageable 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:

ScopeClaims
emailemail, email_verified
addressaddress
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 purpose in mind. They are a way of allowing the user to provide consent to what data it shares with an application or API (discussed in the consent overview), and a way to enable applications to provide services and perform actions on the users behalf.

When to use Claims

The claims are the contents of the tokens. In essence this means that the claims in the token becomes 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. It can range from the user's email to more system specific things such as a subscriber-id or favourite color.

The rule of thumb is that if it's a generally useful value, that isn't too application specific, it can work as a claim.

Example

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

Favourite color is more likely a claim since it's 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 possible consequences. As a best practice, try to keep the claims provided to a minimum, generally always 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

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?