Scopes vs Claims

Overview

This article provides an explanation of scopes and claims, how they relate to each other, and how APIs and clients use them.

Scopes vs Claims

In OAuth 2.0 and OpenID Connect you often hear the terms scopes and claims. Yet, very often, tutorials or courses overlook their importance. Here, we provide a brief overview of what scopes and claims are and how you should use them.

Simply put:

• Claims are assertions that one subject (an asserting party) makes about itself or another subject (the relying party).
• Scopes are groups of claims.

Claims are a statement of a fact only believable if the asserting party is trusted. In OAuth 2.0 and OpenID Connect, the asserting party is the Authorization Server, the subject is the Resource Owner, and the API or the client are the relying party.

The relying party receives both scopes and claims in tokens. You use claims to deliver secure values like user IDs to your applications. Since tokens are integrity-protected, the relying party can trust the scopes and claims it receives and be certain that no malicious party has altered the values.

What are Claims?

Claims are part of tokens and provide you with information about a subject or granted access. For example, in OpenID Connect an ID token contains claims with information about the user, maybe their first and last name, e-mail or address.

More importantly, you can use claims to enable the correct authorization in your APIs. They can carry any type of information you want, about the client, the user, your business permissions or runtime conditions. The token itself uses claims (like audience) that allow you to express where it can be used. Claims Explained provides further information on claims concepts.

What are Scopes?

Scopes provide a logical grouping of claims. One example is the standard OpenID Connect scope profile. An ID Token with the profile scope can include the following claims: name, family_name, given_name, middle_name, nickname, preferred_username, profile_picture, website, gender, birthdate, zone_info, locale, updated_at.

OAuth clients request scopes. This enables them to get access tokens that contain a collection of claims which they send to APIs. Scopes Explained provides further information on scope concepts.

Scopes, Claims and APIs

APIs receive access tokens containing both scopes and claims. APIs then use the scopes and claims for their authorization. Scopes enable you to design which APIs accept which access tokens, so that you can set security boundaries.

API authorization focuses primarily on claims. APIs receive user attributes or business permissions via claims and use them to restrict access to business resources. For more information on how this works, see Using Claims in APIs.

Scopes, Claims and the Client

When clients want to call APIs they request an access token from the authorization server and indicate which scopes they want. The authorization server issues a collection of claims in the access token depending on the scope. The client then sends the access token to APIs.

Scopes, on the one hand, provide a mechanism to limit the access of the client (the requesting party) to API resources. For example, a client can request scope orders_read, meaning that it can only query the orders endpoints with the issued access token and not to make any changes. The authorization server restricts the scopes a client can use. Scopes, on the other hand, also define what claims an API - or a relying party in general - receives as they represent a logical group of claims.

Claims allow a relying party to operate on the identity or user level. ID tokens deliver claims to clients. Access tokens are a way for a client to send claims to APIs. See Scopes, Claims and the Client for further information on how clients get tokens.

Conclusion

Scopes and claims are of central importance in OAuth security, to secure your APIs and clients. Scopes enable security boundaries, and they group claims. Claims provide data to relying parties in a secure manner. You should start by understanding their basic relationships. Together, scopes and claims provide you with a highly flexible solution for communicating secure values and implementing authorization.