ID tokens are signed and/or encrypted JWTs containing a set of claims representing the authentication state of an end user. A client may accept an ID token as proof that an end user has authenticated. Clients with sensitive security needs may also assess the claims in an ID token to determine if the end user’s level of authentication is acceptable.
ID tokens are defined by the OpenID Connect specification.
A client obtains an ID token by making an OpenID Connect request to the Data Governance Broker’s authorization endpoint. See authorization code grant type and implicit grant type for details about obtaining an ID token.
The ID tokens issued by the Data Governance Broker are signed JWTs containing the following claims:
|iss||string||A URL identifying the Data Governance Broker that issued the ID token.|
|sub||string||The unique identifier for the subject of the token; that is, the authenticated user represented by the token. This is a relative URL of the form
|aud||string||The audience that the ID token is intended for. This is the client ID of the application that requested the ID token.|
|exp||number||The date and time when the token will expire. This is an integer timestamp, measured in the number of seconds since January 1, 1970 UTC. The ID token must not be accepted if the
|iat||number||The date and time when the token was issued. This is an integer timestamp, measured in the number of seconds since January 1, 1970 UTC.|
|auth_time||number||The date and time when the end user was authenticated by the Data Governance Broker. This is an integer timestamp, measured in the number of seconds since January 1, 1970 UTC.|
|nonce||string||The nonce value provided with the client’s request. This may be used by the client to associate the ID token with a client session.|
|acr||string||Authentication Context Class Reference. The ACR that was used to satisfy the authentication request. The value will correspond to an ACR configured on the Data Governance Broker. See below for more information.|
|amr||array||Authentication Method References. An array of authentication methods that were used to authenticate the end user. The values correspond to identity authenticators configured on the Data Governance Broker. The table below lists some typical AMR values.|
|at_hash||string||A hash value of the access token that was issued along with the ID token, if one was issued.|
If the ID token is issued without an accompanying access token — i.e., when
response_type=id_token is used — then the ID token may contain a number of additional claims representing user profile attributes, depending on the scopes that were requested. These claims are identical to those used by the UserInfo endpoint and vary depending on the server configuration. The following table lists some typically used standard claims.
|name||string||The end user’s full name.|
|given_name||string||The end user’s given or first name.|
|family_name||string||The end user’s family or last name.|
|preferred_username||string||The end user’s username.|
|string||The end user’s email address.|
|phone_number||string||The end user’s phone number.|
|updated_at||number||An integer timestamp, measured in the number of seconds since January 1, 1970 UTC, which indicates when the end user’s profile was last updated.|
Authentication context class references (ACRs)
An authentication context class reference (ACR) refers to a set of criteria that must be fulfilled for an authentication to be successful. Often, a particular ACR value will represent a particular level of authentication (LOA). For example, a Data Governance Broker might have a ‘Default’ ACR that requires only username/password authentication, plus an ‘MFA’ ACR that requires both username/password authentication and a one-time password, indicating a stronger level of authentication. Clients may optionally specify one or more ACR values in an authentication request.
These criteria are defined by Data Governance Broker configuration and policies. They must be mutually understood by both the Data Governance Broker administrator and the client developer.
Authentication method references (AMRs)
An authentication method reference (AMR) is an identifier representing a type of authentication that was used to achieve an end user’s current authentication state. These roughly correspond to Data Governance Broker components called identity authenticators, but this is not necessarily a one-to-one relationship. For example, a Data Governance Broker may support delivering one-time passwords via either email or SMS. These OTP delivery methods may be implemented as distinct identity authenticators, but if either one is used during authentication, then the AMR may be the same:
otp. A single identity authenticator may also handle multiple authentication methods and be represented by multiple AMRs.
The names of AMR values and how they are used are determined by the Data Governance Broker administrator, and the meaning of each AMR value must be mutually understood by both the Data Governance Broker administrator and the client developer.
The following table lists some typical values that may appear in an ID token’s
amr claim. Other values may be available, as defined by the Data Governance Broker administrator.
|pwd||The end user was authenticated with a username and password.|
|captcha||The end user passed a CAPTCHA test.|
|external||The end user was authenticated via an external identity provider.|
|otp||The end user was authenticated using a one-time password. This includes one-time passwords sent via email or SMS, as well as time-based one-time passwords (TOTPs) generated by an application or device.|
|registration||The end user registered a new account during authentication.|