Mobile Connect API Overview

The Mobile Connect API is fundamentally an OpenID Connect API, but defined using a different set of specifications called the Mobile Connect Profile or Mobile Connect API.

Typically an Identity Provider (IDP) requires users to identify themselves using a username and a password. With Mobile Connect, this has been replaced with a mobile number and access to the mobile device.

Authenticators

Authenticators allow the use of the mobile network infrastructure to authenticate a user. Each operator will implement at least one type of authenticator per Level of Assurance (LoA). The authenticator is the way the operators choose to authenticate a user in order to confirm that the user is who they claim to be. If your application requires a more secure method in the authentication process, the LoA value can be increased. (Please refer to the LoA section for more information). The higher the LoA, the more secure the technology applied by operators to perform authentication will be.

SMS+URL

An SMS+URL authenticator is an SMS sent to the user's device with a unique one-time only URL that the user selects to prove that they are in possession of the device and have access to the SMS. SMS+URL is best suited to LoA2.

*Dependencies: The user’s phone needs to have access to the internet (via WiFi or mobile data) and will also need to be connected to a mobile network (either home network or via roaming).

USSD

USSD (Unstructured Supplementary Service Data) is a protocol used by mobile networks to communicate with a terminal (mobile device). The operator will push a message to the terminal and can require a response. The user's device will display a message such as "Press 1 for OK. Press 2 for Not OK". If a user has access to the mobile device and is able to respond (correctly) to it, they will be authenticated. An LoA3 implementation is also possible where the user has to enter a PIN or pass code. If the user responds with the correct value, the authentication request is complete.
*Dependencies: the user needs to be connected to the mobile network (either home network or via roaming).

SIM Applet

SIM applets are applications that are stored within the SIM card and run on the mobile phone. When an authentication request occurs, a binary SMS will be sent to trigger the SIM applet. Once triggered, it will prompt the user for an input such as “Press OK to continue” or "Please enter your PIN". The SIM Applet will send a response back to the operator to validate the user.

*Dependencies: User needs to be connected to mobile network (either home network or via roaming).

Mobile Connect endpoints

Just like OIDC protocol, Mobile Connect supports the following endpoints:

Authorisation

This endpoint is used by the developer to request authentication. As the result of the process, the user will obtain a randomly generated code that will be returned to the developer via HTTP redirect. The destination of the HTTP redirect will be the redirect_uri parameter that you have provided and configured. As part of the security model, if you pass on a redirect_uri that has not been configured initially, the OIDC platform will respond with an error. This is to protect the API so that others are not able to hijack the authentication URL and replace the redirect_uri with their own address to obtain the code.

Token

The token endpoint is an API where you can use the code you receive from the authorization endpoint to exchange for tokens. Tokens that you will get in return are the access_token and the id_token. Each token has its own purpose.

The id_token comes in a form of JSON Web Token where you will need to decode it to be able to see its content. (Please refer to the JSON Web Token Section for further information). The content of the id_token contains information known as claims of the authentication/authorisation requests.

The access_token is a random string that you will be using to access other API's such as userInfo API. The access_token contains permission to what information you have access to. You can only access the correct information with the relevant permission. Each access_token comes with an expiry date. Once it has expired, you will be required to use the refresh_token to obtain a new access_token.

Refresh Token

The API can use a refresh_token to obtain a new access_token to access the API services.

Revoke Token

(not currently supported)

The API where you can destroy/invalidate/revoke an access_token or refresh_token that you have.

UserInfo

(not currently supported)

A basic API that provides the user's basic profile in JSON Object. To access this API, an access_token is required.

Mobile Connect API Reference

Authorization Endpoint

Request

GET Authorization Endpoint obtained from Discovery Response

Query parameters

Parameter name Value Method Description
Mandatory parameters
client_id string GET This is the client_id field from the Discovery Response.
response_type string GET The value MUST be “code”, to indicate that the grant type flow to be used is Authorisation Code. It also indicates that the access_token (and id_token) be returned in exchange of “code”.
scope string GET Space delimited and case-sensitive list of ASCII strings for OAuth 2.0 scope values. OIDC Authorisation request MUST contain the scope value “openid”. The other optional values for scope in OIDC are: “profile”, “email”, “address”, “phone” and “offline_access”.
redirect_uri string GET The redirect_uri that you have provided during the application creation. The response from the Authorization flow will be redirected to this URI.
acr_values string GET

Authentication Context class Reference. Space separated string that specifies the Authentication Context Reference to be used during authentication processing. The LOA required by the RP/Client for the use case can be used here. The values appear as order of preference. The acr satisfied during authentication is returned as acr claim value.
The recommended values are the LOAs as specified in ISO/IEC 29115 Clause 6 – 1, 2, 3, 4 – representing the LOAs of LOW, MEDIUM, HIGH and VERY HIGH.

The acr_values are indication of what authentication methods to used by the IDP. The authentication methods to be used are linked to the LOA value passed in the acr_values. The IDP configures the authentication method selection logic based on the acr_values.

state string GET Value used by the client to maintain state between request and callback. A security mechanism as well, if a cryptographic binding is done with the browser cookie, to prevent Cross-Site Request Forgery.
nonce string GET 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.
Optional parameters
display string GET

ASCII String value to specify the user interface display for the Authentication and Consent flow.
The values can be:
page: Default value, if the display parameter is not added. The UI SHOULD be consistent with a full page view of the User-Agent.
popup: The popup window SHOULD be 450px X 500px [wide X tall].
touch: The Authorisation Server SHOULD display the UI consistent with a “touch” based interface.

wap: The UI SHOULD be consistent with a “feature-phone” device display.

prompt string GET

Space delimited, case-sensitive ASCII string values to specify to the Authorisation Server whether to prompt or not for reauthentication and consent.
The values can be:
none: MUST NOT display any UI for reauthentication 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. This can be used as a mechanism to check existing authentication or consent.
login: SHOULD prompt the user for reauthentication or consent. In case it cannot be done, an error MUST be returned.
consent: SHOULD display a UI to get consent from the user.

select_account: In the situations, where the user has multiple accounts with the IDP/Authorisation Server, this SHOULD prompt the user to select the account. If it cannot be done, an error MUST be returned.

max-age string GET Specifies the maximum elapsed time in seconds since last authentication of the user. If the elapsed time is greater than this value, a reauthentication MUST be done. When this parameter is used in the request, the ID Token MUST contain the auth_time claim value.
ui-locales string GET Space separated list of user preferred languages and scripts for the UI as per RFC5646. This parameter is for guidance only and in case the locales are not supported, error SHOULD NOT be returned.
claims_locales boolean GET Space separated list of user preferred languages and scripts for the Claims being returned as per RFC5646. This parameter is for guidance only and in case the locales are not supported, error SHOULD NOT be returned.
id_token_hint string GET Generally used in conjunction with prompt=none to pass the previously issued ID Token as a hint for the current or past authentication session. If the ID Token is still valid and the user is logged in then the server returns a positive response, otherwise SHOULD return a login_error response. For the ID Token, the server need not be listed as audience, when included in the id_token_hint.
login_hint string GET

An indication to the IDP/Authorisation Server on what ID to use for login.

The login_hint can contain the MSISDN or the Encrypted MSISDN and SHOULD be tagged as MSISDN:<Value> and ENCR_MSISDN:<Value> respectively – in case MSISDN or Encrypted MSISDN is passed in login_hint. Encrypted MSISDN value is returned by Discovery API in the form of "subscriber_id"

dtbs string GET

Data To Be signed. The Data/String to be signed by the private key owned by the end-user.

The signed data is returned in the ID Claim, as private JWT claims for this profile.

Response

The Authentication Response comes in the form of HTTP 302 redirect to the "redirect_uri" that you have passed as the parameter.

< HTTP/1.1 302 Found
< X-Powered-By: Express
< Location: {Redirect_URL}?code=<value>&state=<value>
< Vary: Accept
< Content-Length: 0
< Date: Wed, 17 06 2015 12:31:46 GMT
< Vary: Origin
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Headers:
< Access-Control-Max-Age: 3628800
< Access-Control-Allow-Methods: GET, POST, OPTIONS
< Access-Control-Allow-Credentials: true
< X-Powered-By: Apigee
< Connection: keep-alive
<
Parameter Value Description
code string Authorisation Code as per OAuth 2.0. To be used as parameter in Token request to exchange for Tokens.
state string The same value as the "state" parameter sent during the authentication request. Use as a security mechanism to confirm that the response comes from the same authentication requests.

During the authentication flow, the user will face a "challenge" to prove that they actually have or own the MSISDN that they claims to have. These "challenges" vary depending on the "acr_values" parameters being passed, as described in the top of this document under Authenticator Section. Only when the "challenge" returns successful, does the developer receive the "code", otherwise they receive an error instead to inform that the authentication process has failed.

Token Endpoint

Request

POST Token Endpoint obtained from Discovery Response

Header parameters

Parameter Value Method Description
Mandatory parameters
Authorization string POST HTTP Basic authorization to access the API. Base64 encoded String of your "<client_id>:<client_secret>" (please note, these are client_id, client_secret value from the discovery response.)
Content-Type string POST Describe the format of the "POST" data that is being sent across. Always set to "application/x-www-form-urlencoded"

Query parameters

Parameter Value Method Description
Mandatory parameters
Authorizationcode string POST The "code" parameter you received from the Authentication request's response.
grant_type string POST The type of "code" that is being submitted. Always set to "authorization_code".
redirect_uri string POST Used as an extra level of security. If a mis-matched redirect_uri is passed (other than the registered), error will be thrown. Set the value to your registered redirect_uri in URL Encoded format.

 

Response

  < HTTP/1.1 200 OK
< Server: Cowboy
< Connection: keep-alive
< X-Powered-By: Express
< Access-Control-Allow-Origin: *
< Content-Type: application/json
< Content-Length: 396
< Vary: Accept-Encoding
< Date: Wed, 29 Jul 2015 13:46:30 GMT
<
{
"access_token":"37bbbc40-35f8-11e5-a6b7-179fcb054c5a",
"token_type":"Bearer",
"expires_in":3600,
"id_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJub25jZSI6IjAuMmo0ZTZwaDQ2Njl3d21pIiwic3ViIjoiZDVmMzhhOGZjYzUyZTkzMWQ0ZmI0ZGE0N2IyZjJiYjAiLCJpYXQiOjE0MzgxNzc1OTAsImV4cCI6MTQzODE4MTE5MCwiaXNzIjoiaHR0cDovL2Rpc2NvdmVyeS5zYW5kYm94Lm1vYmlsZWNvbm5lY3QuaW8ifQ.-ilE2B7W2Ozszi3nBW1kMqBjQp39Vd6uvI9XG6-k6SM",
"refresh_token":"37b234-3258-1gs5-a6gf-1790ujcs54c5a"
}
Parameter Value Description
Mandatory parameters
access_token string OAuth 2.0 access_token, used to get the UserInfo object from the UserInfo end-point and can be reused for accessing other protected resources, if required.
token_type string The type of token received. In Mobile Connect case, it should always be "Bearer".
id_token string Additional token used in OIDC to provide the Identity token claim. A Base64URL encoded String, when decoded contains all the claims in JSON format.
Optional parameters
expires_in string> Expiration time in seconds from the time of generation of the response.
refresh_token string OAuth 2.0 referesh token that can be used to request for a new access_token when the existing access_token expires.

Decoded id_token Payload

Here is a payload section of the decoded id_token. For more information, please refer to the JSON Web Token Section. (note: not all claims are mandatory and varies across different operators.)

{
"nonce": "0.2j4e6ph4669wwmi",
"sub": "d5f38a8fcc52e931d4fb4da47b2f2bb0",
"iat": 1438177590,
"exp": 1438181190,
"iss": "http://discovery.sandbox.mobileconnect.io"
}

id_token claims

Claims Description
Mandatory parameters
iss Issuer Identifier. It is a case-sensitive HTTPS based URL, with host. It MAY contain the port and path element (Optional) but no query parameters.
sub

Subject Identifier. A unique (locally) identifier of the end-user. It is a case-sensitive ASCII string with a maximum length of 255.
The MSISDN SHOULD not be passed as the sub value.

This is what we refer to as Pseudonymous Customer Reference (PCR)

aud The intended audience for the ID Token. It is an array of case-sensitive strings. It MUST contain the client_id of the RP/Client and MAY contain identifiers of other optional audiences.
exp The expiration time after which the ID Token MUST NOT be accepted for processing. It's represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time specified.
iat The time of issue of the ID Token. It's represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time specified.
auth_time Time of end-user authentication. It's represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time specified.
nonce

Opaque string value to associate the RP/Client session with the ID Token, to avoid the replay attacks.
The nonce value MUST be the same as the nonce used in the Authorisation request.

acr Authentication Context Class Reference. It’s a case sensitive string, representing the fact that the authentication process followed the acr [e.g. LOA] requested or not.
amr Authentication Methods References. An array of case-sensitive strings to indicate the authentication method used. The values need to be negotiated offline.
azp Authorised Party – the party to which the ID Token is issued. Represented as the client_id of the party.
Optional parameters
at_hash A base64url encoded value of the hash of the access_token [the hash algorithm is negotiated during registration].
dts Data Signed. The signed data with the user’s private key.
upk User Public Key.
dts_time The time of signing. It's represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time specified.

Example

{
  "ttl":1438265968232,
  "response":{
    "serving_operator":"Example Operator A",
    "country":"US",
    "currency":"USD",
    "apis":{
      "operatorid":{
        "link":[{
          "href":"http://operator_a.sandbox.mobileconnect.io/oidc/authorize",
          "rel":"authorization"
        },
        {
          "href":"http://operator_a.sandbox.mobileconnect.io/oidc/accesstoken",
          "rel":"token"
        },
        {
          "href":"http://operator_a.sandbox.mobileconnect.io/oidc/userinfo",
          "rel":"userinfo"
        },
        {
          "href":"openid profile email",
          "rel":"scope"
        }]
      }
    },
    "client_id":"0c9df219",
    "client_secret":"097097705fa43135c7a6bbcaede4f041",
    "subscriber_id":"ece68489e29b0d9c9ae333c7039651a221400d24cb617291ec8c8db08c03be761de7e289d45fd4f0a2d7211e54622fb0a15ec24db77c91c727326fee00b8ad92c6155f4162d92112ee593781db2e9e8f87d705541e5cb3ccf01483391af8345f1dae11a7015975a1d5e35cda3736b719a8337fa67c7569e5ed40ebe120e85d1e1cbb8586f6601e397181597649c7b1dc729d2f7580bf21305dec1667891780a87e704725e05b30c602423f4b029faa68f7604122d379dcdc688cc4ac2f9b08f0075d737b9642e4c59718279e6875ce871930e8ff96024ae290e1400e7cf7905ce7ba79dfddeeb7bab7b02307a8a2f5c049aff50281c191583eedf20afb711554"
  }
}