OIDC token request and response
OIDC Token Request
On receiving the authorisation code, the client organisation's digital service invokes the RealMe Token Endpoint by sending the following request parameters using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body. The RealMe OIDC Token Endpoint supports the "client_secret_basic" and "client_secret_post" authentication methods. Client organisations receive a "client_secret" value from RealMe as part of the integration process.
The Client organisation sends the following request parameters to the RealMe Token Endpoint:
|
Request Parameter |
Mandatory/ Optional |
Description |
|
code |
Mandatory |
The client organisation’s digital service redeems the authorisation code with the Token Endpoint for the ID token. |
|
grant_type |
Mandatory |
RealMe supports authorisation code flow only, therefore, the value must be "authorization_code". |
|
client_id |
Optional |
The "client_id" parameter value MUST be the same value that was included in the authorisation request. |
|
client_secret |
Optional |
The "client_secret" as provided by RealMe. Required for "client_secret_post" authentication method. |
|
scope |
Optional |
The "client_id" parameter value MUST be the same value that was included in the authorisation request. Required for "client_secret_post" authentication method. |
The following is a non-normative example of a Token Request using the "client_secret_basic" method:
POST /32179062-92f6-4eb0-89bc-df400a9e0367/B2C_1A_DIA_RealMe_OIDC_Service/oauth2/v2.0/token HTTP/1.1
Host: login.realme.govt.nz
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=116141b2-c3ad-4954-8f48-da9277d73ba6
&code=eyJraWQiOiJwOHROYy1aOGMwVndwRnVkNFBrWk......Gb9q-fkwAqE47Fdxsg
The following is a non-normative example of a Token Request using the "client_secret_post" method:
POST /32179062-92f6-4eb0-89bc-df400a9e0367/B2C_1A_DIA_RealMe_OIDC_Service/oauth2/v2.0/token HTTP/1.1
Host: login.realme.govt.nz
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=116141b2-c3ad-4954-8f48-da9277d73ba6
&code=eyJraWQiOiJwOHROYy1aOGMwVndwRnVkNFBrWk......Gb9q-fkwAqE47Fdxsg
&client_secret=czZCaGRSa3F0MzpnWDFmQmF0M2JW
&scope=116141b2-c3ad-4954-8f48-da9277d73ba6
OIDC Token Response
After receiving and validating a Token Request from the client organisation, RealMe returns a successful response that includes an ID Token.
|
Response Parameter |
Description |
|
id_token |
The token contains authentication information for the RealMe login journey and verified claims as requested in the authentication request for the RealMe assertion journey. |
|
token_type |
The value must be Bearer |
|
not_before |
The time at which the token is considered valid, in epoch time (seconds since Jan 01 1970 UTC). |
|
id_token_expires_in |
How long the id_token is valid (in seconds). |
|
profile_info |
A base-64 encoded JSON string. For RealMe, this string should be ignored. |
|
scope |
The scopes that the token is valid for. |
The following is a non-normative example of a successful Token Response.
HTTP/1.1 200 OK
Content-Type: application/json
{
"id_token":"eyJhbGciOiJ......HWSAp_iCMsg",
"token_type":"Bearer",
"not_before":1723153444,
"id_token_expires_in":3600,
"profile_info":"eyJ2ZXIiOiIx......bnVsbCwiaWRwIjpudWxsfQ",
"scope":"openid"
}
ID Token
The ID token is a security token that contains claims about the authentication statement of the customer for the RealMe login journey and includes verified claims about the customer for the RealMe assertion journey. The ID token is a JSON Web Token (external link) [JWT] signed using the RealMe signing key as per JSON Web Signing (JWS) standard. The following table describes the contents of the ID Token.
|
ID Token Claim |
Login/ Assertion Journey |
Description |
|
exp |
Both |
The expiration time on or after which the ID Token MUST NOT be accepted for processing. The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. |
|
nbf |
Both |
The time at which the token is considered valid, in epoch time (seconds since Jan 01 1970 UTC). |
|
ver |
Both |
1.0 |
|
iss |
Both |
The RealMe ODIC Authorisation Server Entity ID. |
|
sub |
Both |
The Subject Identifier also known as Federated Login Tag (FLT). A locally unique and never reassigned identifier within the RealMe for the customer, which is intended to be consumed by the client organisation. For AssertOnly services this is returned as a transient GUID. |
|
aud |
Both |
The Client Organisation digital service Entity ID. |
|
acr |
Both |
Same value as acr_values, as passed in the Authentication Request. |
|
nonce |
Both |
A string value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. If present in the ID Token, Clients MUST verify that the nonce Claim Value is equal to the value of the nonce parameter sent in the Authentication Request. |
|
iat |
Both |
The time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. |
|
auth_time |
Both |
The time when the customer authentication occurred. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. |
|
amr |
Both |
Authentication Methods References. A JSON array of strings that are identifiers for authentication methods used in the authentication. For example · password only authentication (Low Strength) the value includes pwd, · password and OTP authentication (Moderate Strength) the value includes pwd, otp. |
|
login_attribute_token |
Both |
Login Attribute Token (LAT) issued for RCMS flows / interaction with RealMe APIs for configured services. Supplied for login or login and assertion journeys (not AssertOnly unless configured to receive a verified Photo). |
|
fit |
Assertion |
Federated Identity Tag, issued by IVS per user and client service privacy domain association. Returned as a string value. |
|
given_name |
Assertion |
RealMe verified identity customer’s given name or first name. Returned as a string value. |
|
family_name |
Assertion |
RealMe verified identity customer’s surname or family name. Returned as a string value. |
|
middle_name |
Assertion |
RealMe verified identity customer’s middle name(s). Returned as a string value. |
|
birthdate |
Assertion |
RealMe verified identity customer’s birthday, represented in YYYY-MM-DD format. Returned as a string value. |
|
placeofbirth_locality |
Assertion |
RealMe verified identity customer’s place of birth. Returned as a string value. |
|
placeofbirth_country |
Assertion |
RealMe verified identity customer’s country of birth. Returned as a string value. |
|
gender |
Assertion |
RealMe verified identity customer’s gender the supported values are male (M), female (F), other (O). Returned as a string value. |
|
name_disputed |
Assertion |
Represents true if name is disputed. |
|
birthdate_disputed |
Assertion |
Represents true if birthdate is disputed. |
|
gender_disputed |
Assertion |
Represents true if gender is disputed. |
|
placeofbirth_disputed |
Assertion |
Represents true if place of birth is disputed. |
|
address_street |
Assertion |
Customer’s verified RealMe residential address street. Returned as a string value. |
|
address_suburb |
Assertion |
Customer’s verified RealMe residential address suburb name. Returned as a string value. |
|
address_city |
Assertion |
Customer’s verified RealMe residential address city name. Returned as a string value. |
|
address_postcode |
Assertion |
Customer’s verified RealMe residential address rural delivery. Returned as a string value. |
|
address_country |
Assertion |
Customer’s verified RealMe residential address country name. Returned as a string value. |