Claims

OpenID Connect (OIDC) uses claims to describe individual pieces of information, like email or name, packaged into responses from the server. ID Tokens in particular contain claims, packaged within a JSON Web Token (JWT). A variety of other OIDC capabilities also supply information using claims, such as the OpenID Configuration (OpenIdConfiguration) metadata returned from the server, when introspecting a token.

Since claims are a common characteristic of authentication, this SDK provides features that improves the developer experience (DX) to simplify how this information is used, and to make these capabilities consistent across areas of the toolchain.

warning

Not all languages support features that enable all these use-cases. For some languages it may be necessary to support a subset of these features, or to provide them in a different language-specific mechanism.

info

When implementors review this document, please try to determine the best way to support these features in a language-native fashion, and propose updates to this document.

Types that have claims

A variety of types contain claims, which are identified by types that conform to the HasClaims protocol. This protocol provides common access patterns for using claims, and conveniences for simplfying how you can access them.

Some of these types include:

• JWT
• Token
• UserInfo
• TokenInfo
• OpenIdConfiguration
• Token/Metadata

To better understand how these types can be used, it's best to work with an example, starting with JWT.

Examples of using Claims

When a user signs in they are issued an ID token which is returned as a JSON Web Token JWT. This token contains information about the user, and other important values which could be useful to your application. For example, you may wish to retrieve the user's name and "subject" (their user identifier) to display within your interface. The HasClaims protocol makes this easy by providing several ways to extract information.

Keyed Subscripting, using strings

If you know the string identifier for the claim, you can use that as a subscript key on the relevant object.

if let identifier = token.idToken?["sub"] {
  Text("Username: \(identifier)")
}

This can be useful, especially when your application uses custom claims supplied from the authorization server, but when using standard claim values, it can be more convenient to use enums.

Keyed Subscripting, using claim enum values

Enum values are often more convenient to use since code auto-completion and compile-time warnings can ensure consistency when working with these values.

if let identifier = token.idToken?[.subject] {
  Text("Username: \(identifier)")
}

When working with claims, the type of enum is defined by the conforming type, which can help give you an insight into the possible options available to you.

Value conversion functions

Many types that conform to ClaimConvertable can transform values from a claims payload to a convenient type, but using keyed subscripting will always return an optional value. If you want to ensure that the claim you're retrieving exists, and is of the proper type, you can use the value functions available within the HasClaims protocol.

These functions include both throwing and optional variations, and are used from within the subscript convenience functions.

For example:

if let registrationUrl: URL = try openIdConfiguration.value(for: .registrationEndpoint) {
    // Use the value
}

This works for dictionaries and array values as well.

let scopes: [String] = try openIdConfiguration.value(for: .scopesSupported)


// Or
let profile: [String: String] = try idToken.value(for: "custom_claim")

Convenience properties

Finally, some common claims which are best represented as more concrete types, such as URL or Date, are provided to simplify your workflow. For example, if you want to retrieve the date the user was authenticated using HasClaims/authTime as a Date type, or the user's locale using HasClaims/userLocale a NSLocale object on Apple platforms.

if let authTime = token.idToken?.authTime,
    authTime.timeIntervalSinceNow < 3600 {
  // The user authenticated more than one hour ago
}

Enums and arrays of converted values

Some types conform to a special protocol called ClaimConvertable, which enables concrete types to be convertable from the raw claim values supplied by the authorization server. This can make interacting with claims easier and more developer-friendly.

One example of this type is the HasClaims/authenticationMethods property. The JWTClaim/authMethodsReference claim returns an array of the methods a user used to authenticate their account. The values for this claim can be represented by the AuthenticationMethod enum, so instead of performing string comparisons, you can reference this convenience property to work with the authentication methods reference as an array of enums.

if let authenticationMethods = token.idToken?.authenticationMethods,
   authenticationMethods.contains(.multipleFactor)
{
    // The user authenticated using some multifactor step
}