Overview
The Request Object enables Mobile Connect service requests to be passed in a signed JSON object containing the values in the payload table below. The object, encoded as a JWT string is passed to the ID Gateway in the request
parameter.
The following points need to be considered for Mobile Connect.
- When using a signature, the
alg
header parameter value of the header MUST be set to an appropriate algorithm as defined in JSON Web Algorithms. - The Private Key used to sign the content MUST be associated with a Public Key
- The Public Key used for signature verification must be published in the registered applications JWK set (via the JWKS URI).
- If there are multiple keys in the referenced JWK set, a
kid
value MUST be provided. - The key usage of the respective keys MUST support signing.
A more detailed introduction to introduction to JSON Web Tokens can be found here.
Creating the JWT
Creation of the Request Object is a multi-step process as detailed below.
1. Create the header
The header describes the signing algorithm, the token type and optionally identifies the signing key. See below for an example Request Object header:
{
"alg": "RS256",
"typ": "JWT",
"kid": "my_key_id"
}
The signing algorithm and public key must be declared by registering a JWKS URI
(which points to a JSON file storing the keys) and request_object_signing_alg
as part of application registration process. Both kid
and type
are optional. The kid
parameter identifies which JWK should be used to verify a signature where multiple keys are registered. The type
is only used where multiple different token types may be present.
2. Base64URL the Header
The header should be minified first and then Base 64 URL encoded to ensure that it can be safely transmitted. As an example the header above would be encoded as:
This gives us:
{"alg": "RS256", "typ": "JWT", "kid": "my-key-id"}
Which is encoded as
eyJhbGciOiAiUlMyNTYiLCAidHlwIjogIkpXVCIsICJraWQiOiAibXkta2V5LWlkIn0=
This is the Encoded JWS Header .
3. Create the payload
The Request Object payload can have the following parameters:
Name | Usage | Description |
---|---|---|
response_type | REQUIRED |
Must be |
client_id | REQUIRED |
The |
scope | REQUIRED |
Space delimited, case-sensitive ASCII string of the scope values indicating the service being requested. For more information see the Scope values page. Example: |
version | REQUIRED | Identifies the Mobile Connect profile version, for SI Polling this must be mc_si_v2.0 |
nonce | REQUIRED |
String value used to associate a client session with the ID Token. It is passed unmodified from Authorisation Request to ID Token. The value SHOULD be unique per session to mitigate replay attacks. The recommended format is UUID4. Example: |
prompt | OPTIONAL |
Specifies to the IDGW Server whether to prompt the end-user for re-authentication and consent. Values are:
|
max_age | OPTIONAL |
Specifies the maximum elapsed time in seconds since the last authentication of the user. If the elapsed time is greater, a re-authentication will be attempted. When this parameter exists in the request, the ID Token will contain the Example: |
ui_locales | OPTIONAL |
Space separated list of user preferred languages and scripts for the UI as per RFC 5646. If a requested locale is not supported then the user interface will be provided in the default language of the ID Gateway. Example: |
claims_locales | OPTIONAL |
Space separated list of user preferred languages and scripts for the claims, defines as per RFC 5646. The parameter is for guidance only and in case a requested locale is not supported then the claims will be provided in the default language of the ID Gateway. Example: |
id_token_hint | OPTIONAL |
Used in conjunction with Example: |
login_hint | OPTIONAL |
An indication to the ID Gateway about what ID to use for login. Using this parameter allows the end-user to skip the login identifier. The values passed will parameter type ('MSISDN:', 'ENCR_MSISDN:' or 'PCR') and the parameter value. REQUIRED if login_hint_token does not exist. Example: |
login_hint_token | OPTIONAL |
Encrypted JSON Web Token (JWT) that contains a user identifier (the MSISDN). It is returned by the Discovery Service. This parameter should only be used if indicated by the operator REQUIRED if login_hint does not exist. |
acr_values | REQUIRED |
Level of Assurance to be used to authenticate an end-user. A space separated list of values in order of preference. When it is present the Authentication endpoint should satisfy one values of for end-user's authentication. The recommended values are the LOAs as 2, 3, 4 (see the Level of Assurance page). Example: |
binding_message | OPTIONAL |
Only required for scope |
client_name | OPTIONAL |
Only required for scope |
context | OPTIONAL |
Only required for scope |
claims | OPTIONAL |
Only used for the MC KYC Match services. A JSON object listing specific claims to be returned in the response. See the KYC Claims page for more information. |
correlation_id | OPTIONAL |
Correlates a transaction across Mobile Connect components. The value is generated by the Service Provider and must be locally unique. The recommended format is UUID4. Example: |
client_notification_token | REQUIRED |
As defined in the OIDF CIBA Example: |
notification_uri | REQUIRED |
Notification URI to which the tokens will be sent. The URI MUST exactly match the notification URI value pre-registered with the operators. The notification URI MUST use the HTTPS scheme. Example: |
exp | OPTIONAL |
Desc Example: |
iat | OPTIONAL |
Desc Example: |
iss | REQUIRED |
The token issues ID. This is normally the Client ID returned in the Discovery response or provided by the Operator. Example: |
aud | REQUIRED |
The ID Gateway’s issuer identifier URL, obtained through operators Provider Metadata file. The URL is returned in the Discovery response or provided by the Operator. Example: |
A example Request Object for an ATP request to the Sandbox would look like this:
{
"response_type":"mc_si_polling",
"client_id":"ZmU4YTEzMGUtODczMS00NTZjLWFjZDgtZTc0OWEyYjk1NjVmOdG9yLWI=",
"scope":"openid mc_atp",
"version":"mc_si_v2.0",
"nonce":"49d28eecebc3ed3e855f97ee1ff20f18",
"login_hint":"PCR:11e93a80-bffc-43f4-abc3-f2addef08683",
"acr_values":"3",
"iss":"ZmU4YTEzMGUtODczMS00NTZjLWFjZDgtZTc0OWEyYjk1NjVmOm9wZXJhdG9yLWI=",
"aud":"https://operator-b.integration.sandbox.mobileconnect.io"
}
As can be seen many values are optional and some of these apply only to specific products.
4. Base64URL the payload
The payload should be minified first and then Base 64 URL encoded to ensure that it can be safely transmitted. As an example the above payload above would be encoded as:
This gives us:
{"response_type": "mc_si_polling", "client_id": "ZmU4YTEzMGUtODczMS00NTZjLWFjZDgtZTc0OWEyYjk1NjVmOdG9yLWI=", "scope": "openid mc_atp", "version": "mc_si_v2.0", "nonce": "49d28eecebc3ed3e855f97ee1ff20f18", "login_hint": "PCR:11e93a80-bffc-43f4-abc3-f2addef08683", "acr_values": "3", "iss": "ZmU4YTEzMGUtODczMS00NTZjLWFjZDgtZTc0OWEyYjk1NjVmOm9wZXJhdG9yLWI=", "aud": "https://operator-b.integration.sandbox.mobileconnect.io"}
Which is encoded as
eyJyZXNwb25zZV90eXBlIjogIm1jX3NpX3BvbGxpbmciLCAiY2xpZW50X2lkIjogIlptVTRZVEV6TUdVdE9EY3pNUzAwTlRaakxXRmpaRGd0WlRjME9XRXlZamsxTmpWbU9kRzl5TFdJPSIsICJzY29wZSI6ICJvcGVuaWQgbWNfYXRwIiwgInZlcnNpb24iOiAibWNfc2lfdjIuMCIsICJub25jZSI6ICI0OWQyOGVlY2ViYzNlZDNlODU1Zjk3ZWUxZmYyMGYxOCIsICJsb2dpbl9oaW50IjogIlBDUjoxMWU5M2E4MC1iZmZjLTQzZjQtYWJjMy1mMmFkZGVmMDg2ODMiLCAiYWNyX3ZhbHVlcyI6ICIzIiwgImlzcyI6ICJabVU0WVRFek1HVXRPRGN6TVMwME5UWmpMV0ZqWkRndFpUYzBPV0V5WWprMU5qVm1PbTl3WlhKaGRHOXlMV0k9IiwgImF1ZCI6ICJodHRwczovL29wZXJhdG9yLWIuaW50ZWdyYXRpb24uc2FuZGJveC5tb2JpbGVjb25uZWN0LmlvIn0
This is the Encoded JWS Payload .
5. Concatenate the values
Before signing, the header and payload need to be concatenated together. This is always the concatenation of the Encoded JWS Header, a period ('.') character, and the Encoded JWS Payload. Any padding characters can be removed before the concatenation.
As an example the header and payload above would give:
eyJhbGciOiAiUlMyNTYiLCAidHlwIjogIkpXVCIsICJraWQiOiAibXkta2V5LWlkIn0.eyJyZXNwb25zZV90eXBlIjogIm1jX3NpX3BvbGxpbmciLCAiY2xpZW50X2lkIjogIlptVTRZVEV6TUdVdE9EY3pNUzAwTlRaakxXRmpaRGd0WlRjME9XRXlZamsxTmpWbU9kRzl5TFdJPSIsICJzY29wZSI6ICJvcGVuaWQgbWNfYXRwIiwgInZlcnNpb24iOiAibWNfc2lfdjIuMCIsICJub25jZSI6ICI0OWQyOGVlY2ViYzNlZDNlODU1Zjk3ZWUxZmYyMGYxOCIsICJsb2dpbl9oaW50IjogIlBDUjoxMWU5M2E4MC1iZmZjLTQzZjQtYWJjMy1mMmFkZGVmMDg2ODMiLCAiYWNyX3ZhbHVlcyI6ICIzIiwgImlzcyI6ICJabVU0WVRFek1HVXRPRGN6TVMwME5UWmpMV0ZqWkRndFpUYzBPV0V5WWprMU5qVm1PbTl3WlhKaGRHOXlMV0k9IiwgImF1ZCI6ICJodHRwczovL29wZXJhdG9yLWIuaW50ZWdyYXRpb24uc2FuZGJveC5tb2JpbGVjb25uZWN0LmlvIn0
This is the JWS Signing Input .
6. Generate the JWS Signature
The signature is used to verify the message wasn't changed along the way, and, using a private key, it can also verify that the sender of the JWT is who it says it is.
To generate the signature take the JWS Signing Input and use the Private Key (associated with the previously shared Public Key) with the algorithm specified in the header to sign it. The output should then be Base64url encoded. The result of this is the Encoded JWS Signature .
The exact approach will depend upon the library used but the following pseudo code provides an example.
HMACSHA256(jwsSigningInput,secret)
7. Create the JWT
The final JWT is created by concatenating the the Encoded JWS Header, a period ('.') character, the Encoded JWS Payload, a period ('.') character and the Encoded JWS Signature. Any padding characters can be removed before the concatenation.
Given an Encoded JWS Signature of:
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
This would give us:
eyJhbGciOiAiUlMyNTYiLCAidHlwIjogIkpXVCIsICJraWQiOiAibXkta2V5LWlkIn0.eyJyZXNwb25zZV90eXBlIjogIm1jX3NpX3BvbGxpbmciLCAiY2xpZW50X2lkIjogIlptVTRZVEV6TUdVdE9EY3pNUzAwTlRaakxXRmpaRGd0WlRjME9XRXlZamsxTmpWbU9kRzl5TFdJPSIsICJzY29wZSI6ICJvcGVuaWQgbWNfYXRwIiwgInZlcnNpb24iOiAibWNfc2lfdjIuMCIsICJub25jZSI6ICI0OWQyOGVlY2ViYzNlZDNlODU1Zjk3ZWUxZmYyMGYxOCIsICJsb2dpbl9oaW50IjogIlBDUjoxMWU5M2E4MC1iZmZjLTQzZjQtYWJjMy1mMmFkZGVmMDg2ODMiLCAiYWNyX3ZhbHVlcyI6ICIzIiwgImlzcyI6ICJabVU0WVRFek1HVXRPRGN6TVMwME5UWmpMV0ZqWkRndFpUYzBPV0V5WWprMU5qVm1PbTl3WlhKaGRHOXlMV0k9IiwgImF1ZCI6ICJodHRwczovL29wZXJhdG9yLWIuaW50ZWdyYXRpb24uc2FuZGJveC5tb2JpbGVjb25uZWN0LmlvIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
This is the JSON Web Token (JWT) that is used as the Request Object and will be the value of the request
parameter.
Note: It is strongly recommended to make use of common libraries for JWT and JWS processing to avoid introducing implementation specific bugs. A useful list of libraries can be found on the OpenID site.