The Request Object | Mobile Connect Developer Portal

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 `mc_si_polling` or `mc_si_async_code`. Indicates to the ID Gateway that it should return both an Access Token and an ID Token in response to a Polling Token Request.
client_id	REQUIRED	The `client_id` field obtained from the Discovery response or direct from the operator. Used as the unique client identifier.
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: `openid mc_atp`
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: `878aacd7-83f1-4b4f-9582-7347b0a6fa62`
prompt	OPTIONAL	Specifies to the IDGW Server whether to prompt the end-user for re-authentication and consent. Values are: `none`: Will not display any UI for re-authentication or consent to the user. If the user is not authenticated already, or authentication or consent is needed to process the Authorisation Request, a login_required error is returned. `login`: Will prompt the user for re-authentication or consent. If not possible, an error will be returned.
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 `auth_time` claim value. Example: `3600`
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: `fr-CA fr en`
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: `fr-CA fr en`
id_token_hint	OPTIONAL	Used in conjunction with `prompt=none` to pass a previously issued ID Token as a hint for the current or past authentication session. If the user is logged in and the ID Token is still valid, then the server returns a positive response, otherwise, it will return a login_error response. Example: `eyJhbGciOiJSUzI1NiIsImtpZCI6IjdlOGFkZmM`
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: `MSISDN:447700900907`
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: `3 2`
binding_message	OPTIONAL	Only required for scope `openid mc_authz`. Client provided plain text, to interlock the consumption device and authorisation device. Empty values are allowed (zero length).
client_name	OPTIONAL	Only required for scope `openid mc_authz`. A short name to identify the client application which will be displayed on the end-user device.
context	OPTIONAL	Only required for scope `openid mc_authz`. A transaction or action based message provided by the client Application which will be displayed on the authentication device of the end-user.
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: `42da5b19-457a-4d30-a5c4-038c62dccbb0`
client_notification_token	REQUIRED	As defined in the OIDF CIBA Example: `Wm1VFlURXpNR1V0T0Rjek1TMDBOVFpqTFdGalpEZ3`
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: `https://mc.example.com/callback`
exp	OPTIONAL	Desc Example: `e6da5b19-457a-4d30-a5c4-038c62d87d3`
iat	OPTIONAL	Desc Example: `e6da5b19-457a-4d30-a5c4-038c62dc6328`
iss	REQUIRED	The token issues ID. This is normally the Client ID returned in the Discovery response or provided by the Operator. Example: `e6da5b19-457a-4d30-a5c4-038c62dccbc5`
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: `https://operator.example.com`

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.