JWT Claims in OpenID Connect: Real-world Example

OpenID Connect (OIDC) is a widely adopted standard for user authentication in modern web and mobile applications. One of its key features is the use of claims, which are pieces of information about the authenticated user issued by the identity provider in the form of a JSON Web Token (JWT). Embedding claims in the JWT lets identity providers communicate the user's details in a standardized, secure manner.

In this article, we will cover:

• What JWT claims are
• How they are issued by the identity provider
• What exactly happens when a user logs into a web application using a national eID. 

We’ll use the Danish MitID as an example, but the same principles apply to all eIDs supported by Criipto Verify.

JSON Web Tokens and Claims

JWTs are commonly used for transmitting authentication and authorization information between parties in the form of a JSON object. 

A JWT consists of three parts:

• Header, which contains general information about the token. 
• Payload, which contains claims that provide the actual information about the user who logged in, such as their identity, role, or permissions within the system.
• Signature, which identifies the issuer of the token and ensures that the token has not been tampered with during transmission.

Here is an example of claims that might be included in a JWT:

{
  "sub": "1234567890",
  "name": "Ditlev Von Testesen",
  "email": "ditlev.von.testesen@example.com",
  "iat": 1678382880,
  "exp": 1678382885
}

In this example, the JWT contains five claims:

• sub: the subject of the token, which in this case is a user’s unique identifier. “sub” is a standard claim representing the entity to which the token is issued (typically a user, a device, or an application).
• name: the name of the user.
• birthdate: the date of birth of the user.
• iat: when the token was issued (in Unix time). 
• exp: when the token will expire (in Unix time).

Each claim has a unique key (“sub,” “name”) and a corresponding value ("1234567890", "Ditlev Von Testesen"). These claims are included in the JWT token, which is then encoded and signed.

You can see exactly how this works and try creating your own JWT token on jwt.io. 

In a real web application, the process of creating and encoding a JWT token is handled by the OpenID Provider, and the validation and decoding typically happens on the server side and is done by the web application's backend code.

Logging in with an eID

In the context of OIDC, national eIDs can act as sources of identity via OpenID Providers. 

So when a user logs into a web application using an eID, it’s the OpenID Provider that issues a JWT containing a set of claims about the user, which is then returned to the web application.

Let's take an example of a user logging into a web application with a Danish MitID. Logging in with MitID will grant the user access to the application since OpenID Connect allows logging into multiple applications using a single set of credentials. To many people, this is now a familiar process that they prefer over a standard username and password combination. 

In turn, the application will gain access to the user’s data in the form of JWT claims.

To enable this flow, the application leverages Criipto Verify to present the user with an option to log in using MitID. If the user picks this option, they’ll see the familiar screen and enter their credentials.

Once the user is successfully authenticated, Criipto Verify generates a JWT token containing information about the user. The token is then signed and returned to the application. At this point, the application will have the user’s information. 

Below is an example of JWT claims returned to the application after the user signs in with Danish MitID.

{
  "identityscheme": "dkmitid",
  "nameidentifier": "0f9960a0d28d4353a3e2ea07f8ffa185",
  "sub": "{0f9960a0-d28d-4353-a3e2-ea07f8ffa185}",
  "uuid": "74ffcd31-fbaf-4c33-bdac-169f25c1e416",
  "cprNumberIdentifier": "2101270087",
  "birthdate": "1927-01-21",
  "age": "93",
  "name": "Ditlev Von Testesen",
  "country": "DK"
}

This example includes the following claims:

• identityscheme: refers to the eID used for authentication (MitID in our case).
• sub: the user’s unique eID identifier, as in the earlier example.
• nameidentifier: “sub” but in the legacy format. 
• uuid: a persistent pseudonym authorities use to identify the person. For citizens, it identifies the natural person. For employees, the legal person.
• cprNumberIdentifier: CPR number (the Danish version of SSN).

It’s also possible to add address information for users logging in with MitID. 

Once the application receives the token with claims, it will verify the signature to ensure the token was indeed issued by the expected OpenID Provider and has not been tampered with. (Learn more about JWT Validation and its implementation in our detailed guide with code samples.) The application is now also able to extract information about the user from the claims. (This can be used to, say, create a personalized user experience).
 

Criipto Verify as an OpenID Provider

Criipto Verify is an OpenID Provider.

This means we have implemented a set of standards and protocols and built software to authenticate users and provide identity information to other applications and services.

As an OpenID Provider, Criipto Verify will issue JWT tokens after users log in to a web or mobile application with one of the national eIDs we support. As explained, these JWTs will contain information like the user’s name, date of birth, and other attributes. Every national eID has a set of predefined claims that is slightly different from others. The JWT tokens issued by Criipto Verify can then be used by web and mobile applications to verify the user's identity and authorize access to protected resources.

Criipto Verify helps you simplify the process of managing user identities by letting your users log in with their own national eID using a familiar and secure process.

eID also supplies the identity of the user, which adds an extra layer of security to the authentication process.

Finally, using Criipto Verify isolates your application from any future changes in each eID implementation. You won’t have to worry about how the actual identity services evolve over time or how they are secured.