In OAuth and OpenID Connect, scopes and claims appear quite often. However, many times their explanation is overlooked. This brief article will explain what scopes and claims are and how you can use them.

Claims Explained

Claims are statements of facts that are only believable if the asserting party is trusted. In OAuth and OpenID Connect, the asserting party is the authorization server. A claim can be asserted about a subject or an entity—often the user—that is claimed to be true by an asserting party. The subject is the resource owner; the API or the client is the relying party.

Scopes Explained

Scopes are a set of claims. They are a shorthand way of requesting a level of access from the authorization server. Clients request one or more scopes to be issued to access tokens so that they get the API permissions they need.

Standard Claims and Scopes

In OpenID Connect, a profile scope consists of a group of claim names that include claim values. The claim names usually contain these variables: name, family_name, given_name, middle_name, profile, picture, website, gender,etc. When a user logs in, the values for those claims - if the authorization server can assert them - will be asserted as claim values. Instead of having to ask for a dozen different claims, you can simply request one scope that will contain this information.

Examples of standard OpenID groupings include: profile, openid, offline_access, email, address, phone. When a user logs in and is being authenticated, and their data is released in claims format, this information can be passed into an ID token user info or to an access token. Consequently, these claim values would end up manifesting themselves.

How are Claims and Scopes Useful?

Business Value

Scopes and claims provide the heart of a scalable security architecture for your APIs and clients. Scopes enable you to set security boundaries to define which clients can access which API endpoints. You can create custom scopes that are defined in terms of areas of your business.

Your APIs use claims to implement their business authorization. You can define custom claims to implement any finer-grained identity values your APIs need. Both scopes and claims are issued to access tokens returned to clients so that each client calls APIs with the correct level of business access.

User Consent

The consent user experience should be based on scopes not claims. The user sees a plain English message of a scope's meaning rather than technical information about many fine-grained permissions.

Summary & Conclusion

Claims are assertions made by one party about another. The authorization server is the asserting party, the user is the subject, the API and the client are the relying parties. Scopes are a group of claims and with claims less data is released. Lastly, claims provide a finer-grained authorization model.

Further Reading:

Scopes vs Claims
Introduction to Claims
Introduction to Scopes
Using Claims in APIs
Scopes, Claims and the Client
Consent and Claims