Scopes and Claims Explained

Maria Pelagia — Thu, 02 May 2024 08:45:43 +0000

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

Best Practices for Handling JWTs

Maria Pelagia — Wed, 11 Jan 2023 12:34:43 +0000

Even though JSON Web Tokens (JWT) are widely used in the OAuth and OpenID protocols, maintaining a high level of security while using them is not always easy. This article will focus on some best practices for handling JWTs so that you can maintain a high level of security in your applications.

What is a JWT?

JWTs are not protocols, they are message formats.
They are used to pass messages between two parties, e.g., a client and a server, or between services.
A JSON Web Token has a form of a string divided into parts which are base64 encoded and separated by dots.
A JWT can either be a JWS (a signed token) or a JWE (an encrypted token). These types of tokens define the parts that the JSON Web Token will consist of.
Most often JWTs are used as Access Tokens or ID Tokens (but they can also be used in other scenarios as well).

JWT Best Practices

Protect Valuable API Data in Access Tokens

When JWTs are issued to your clients to be used as Access Tokens, client developers are able to access the data in the token. In such cases developers can start using the data from JWTs in their applications which can cause issues if you decide to change the structure of the data in the JWT. As the token can easily be accessed or read, personal information about users can also be easily leaked and valuable API data can become prone to cyber attacks. Either avoid adding sensitive data to access tokens or utilise a pattern like the Phantom Token, where the data is concealed by an opaque token.

JWTs and Algorithms

Encrypted and signed tokens always contain an alg claim in the header to show which algorithm has been used. When verifying and decrypting tokens it is considered a best practice to check the value of this claim against a list of algorithms that your system accepts and which are verified to be secure. If the alg claim contains a none value, make sure that you know both the identity of the issuer of the token and of the client that uses the token before proceeding.

Always Validate an Incoming JWT

Another best practice is to always validate an incoming token. This should be done even when a service is only accessible on an internal network, to prevent situations where someone manages to make requests from inside the network. Many times when services are moved to a public domain the security measures are overlooked, thus it’s important to have them properly protected from the beginning.

Verify the Issuer

Always check the issuer of the JWT to make sure that you can trust them by checking the iss claim. This is especially important when downloading the keys needed to validate / decrypt the tokens. Make sure to confirm that any cryptographic keys used to sign or encrypt the token belong to the issuer. The verification of the issuer depends on the implementation of the JWT. For example, when using OpenID Connect the issuer should be an HTTPS URL. This makes it easier to confirm the ownership.

Conclusion

In this article we have explored a few best practices when using JWTs. It's important to remember that JWT safety depends greatly on how the tokens are implemented and used. At Curity, we have written a complete guide on how to keep your JWTs secure, following best practices. Make sure to also check any changes in the RFCs which talk about the good practices for JWTs: in RFC 8725 JSON Web Token Best Current Practices and in RFC 7518 JSON Web Algorithms (JWA).

DEV Community: Maria Pelagia