Introduction to Claims
On this page
Overview
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.
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.
Here is an OAuth example:
- "Curity states that the Resource Owner has this list of attributes."
| Asserting Party | Subject | Claims |
|---|---|---|
| Curity | Resource Owner | Attributes |
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 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:
| Scope | Claims |
|---|---|
email, email_verified | |
| address | address |
| profile | name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at |
| phone | phone_number, phone_number_verified |
| openid | sub, 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.
Example
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
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
Join our Newsletter
Get the latest on identity management, API Security and authentication straight to your inbox.
Start Free Trial
Try the Curity Identity Server for Free. Get up and running in 10 minutes.
Start Free Trial
