Workflow

The Mobile Connect API is responsible for gaining user authentication and access to 'protected resources'. Mobile Connect is based on the OpenID Connect standard (see http://openid.net/developers/specs for more information). The OpenID Connect authorization sequence is as follows:

Mobile Connect authorisation flow Mobile Connect flow

The Mobile Connect sequence for an applicaiton wanting to authorise a user is as follows:

1. The user interacts with your application.

2. Your application sends an API request to the API Exchange to retrieve the Mobile Connect logo and invoke the Discovery API login page.

3. User enters their mobile phone number via the Mobile Connect login page.

4. Discovery API returns the authorisation endpoints for Telstra Mobile Connect

5. Your application calls the Telstra Mobile Connect API to initiate the authentication process

6. Telstra validates your application with the API Exchange to check if it has a valid subscription.

7. Telstra then asks the user to provide consent (using SMS PIN verification) and then returns back to the application with an authorisation code.

8. Using the authorisation code, your application uses the authorisation endpoint (from step 2) to request an access token from Telstra. The access token can then be used to retrieve information about the user from Telstra (also using a call to an authorisation endpoint from step 2).

 

Mobile Connect provisioning    Provisioning steps

    Before your application can use the Mobile Connect API it needs to be provisioned. below is an outline of the provisioning steps.

    1. Register your application in MyApps on T.DEV. You must agree to the GSMA Mobile Connect terms and conditions.

    2. Your application gets provisioned in T.DEV and GSMA API Exchange.

    3. Once provisioned with API Exchange, API keys will be available to you on you T.DEV portal.

 

 

 

 

 

Authorisation

 

Reference: Mobile Connect - Authorisation

The first step when using the Mobile Connect API is to seek authorisation from the end user to share their unique Telstra credential with your application - which in the current implementation is a unique subscriber number (no personal information such as names are shared).

The /authorize end point will respond with a 302 redirect to a Telstra hosted form that prompts the user to enter their mobile phone number. The end-user will then receive an SMS asking them to reply with a 4-digit code. Once the correct code is received another 302 redirect will be issued to send the end-user back to the URL specified in the redirect_uri parameter.

Due to the steps requiring user interaction this request is ordinarily executed from the end-user's browser.

Request

Authorise request parameters - https://api.telstra.com/v1/mobileconnect/authorize
Parameter Name Type Required Description Format Example
response_type URL Query Parameter Yes 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'. String 'code' code
client_id URL Query Parameter Yes Specifies the application 'Consumer Key' credential provided during developer/application registration on the Telstra Developer Portal String value f0132c20-9516-11e4-8e23-874e3aacae3d
scope URL Query Parameter Yes 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'. Space delimited string openid address phone email
redirect_uri URL Query Parameter Yes The URI where the response will be sent through redirection. The URI MUST match one of the pre-registered redirect_uris at client registration/provisioning. String URI https://example.com/authorisation
state URL Query Parameter Yes Value used by the client to maintain state between request and callback. Used as a security mechanism to prevent Cross-Site Request Forgery. String 9500-a70fc1c31c3b
nonce URL Query Parameter Yes 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. String 11e4-a998-3bb9a65e4400
login_hint URL Query Parameter No An indication to the IDP/Authorisation Server on what ID to use for login, e.g. emailid, MSISDN (phone_number) etc. It is Recommended that the value matches the value used in Discovery.
The login_hint can contain the MSISDN or the Encrypted MSISDN and SHOULD be tagged as MSISDN:<Value> and ENCR_MSISDN: respectively - in case MSISDN or Encrypted MSISDN is passed in login_hint.
Telstra Mobile Connect supports both MSISDN and ENCR_MSISDN.
String ENCR_MSISDN: RW5jcnlwdGVkIE1TSVNETg==
acr_values URL Query Parameter Yes 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 method 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.
Telstra Mobile Connect only accepts a value of '2'.
String (numeric space separated) 2

Response

After the authorisation process is complete, a 302 redirect is issued back to the URI specified in the redirect_uri parameter in the original authorisation request.

All response parameters are sent to the application/service by appending to the redirect_uri provided by the application/service. The application/service is responsible for extracting the parameters.

Example response

HTTP/1.1 302 Found
Location: https://example.com/authorisation?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj

 

Authorise response parameters - https://api.telstra.com/v1/mobileconnect/authorize
Parameter Name Type Description Format Example
code URL Query Parameter Specifies a one time use 'authorisation code' provided to the application/ service. This can be used with the Token API to obtain an 'access token'. String 18d368c4
state URL Query Parameter Value used by the client to maintain state between request and callback. Used as a security mechanism to prevent Cross-Site Request Forgery. String 9500-a70fc1c31c3b

Token

Reference: Mobile Connect - Token

Once the authorisation request has completed it will return an 'authorization code' to the application/service. This is a one time use code that can be exchanged by the application/service for an 'access token'.

The Token API call is a RESTful API call which is invoked directly by the application/service - this could be via client side or server side application/service unlike the authorisation API call which is invoked from the user's client side browser.

Note that HTTP Basic Authorization is required when using the Token API - this will include the 'Consumer Key' and 'Consumer Secret' for the application/service - usually returned from the Telstra Developer Portal or the GSMA Discovery API.

Request

CONSUMER_KEY="your consumer key"
CONSUMER_SECRET="your consumer secret"
AUTH=`echo "$CONSUMER_KEY:$CONSUMER_SECRET" | base64`
REDIRECT_URL="your redirect url"
CODE="code from authorisation"
 
curl -i -H "Accept: application/json" -H "Authorization: Basic $AUTH" "https://api.telstra.com/v1/mobileconnect/token?grant_type=authorization_code&code=$CODE&redirect_uri=$REDIRECT_URL"
Token request parameters - https://api.telstra.com/v1/mobileconnect/token
Parameter Name Type Required Description Format Example
Accept HTTP Header No Indicates the content type required for the response. The Token API is defined with a JSON (application/json) response type and servers may ignore this header or generate an error if a value other than application/json is specified.. String (Mime Type) application/json
Authorization HTTP Header Yes Requests to the Token API service require the application to be identified using HTTP Basic authorization. Normal Base 64 encoding is required for the application credentials (Consumer Key and Consumer Secret). Base64 encoded string {consumer_key}:{consumer_secret} Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
grant_type URL Query Parameter Yes The value MUST be set to the literal value authorization_code String authorization_code
code URL Query Parameter Yes The authorisation code received from the authorisation server, from the authorisation request String 537ed11e-9581
redirect_uri URL Query Parameter Yes Indicates the Redirect URI that was originally included in the 'authorisation request'. The URI MUST match one of the pre-registered redirect_uris at client registration/provisioning. String URI https://example.com/authorisation

Response

Parameter Name Type Description Format Example
access_token JSON (Mandatory) 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. String e68abc70-9595-11e4-a037-f37949abe7b7
token_type JSON (Mandatory) MUST be 'bearer' for the Mobile Connect Profile. String bearer
id_token JSON (Mandatory) This is the additional token used in Mobile Connect to provide the Identity token to the application/service (see below for further details). String (encoded) eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso
expires_in JSON (Optional) Expiration time in seconds (for the 'access token' and 'ID Token') from the time of generation of the response. Integer 3600
refresh_token JSON (Optional) A token which can be used to get a new 'access token' when the current 'access token' expires. If not included in the response this means the application/ service must request user authorisation again for a new 'access token' String ba95e4ae-9596-11e4-b23f-276271544387

User Info

Reference: Mobile Connect - User Info

This final step allows the application (through the use of the token obtained above) to retrieve attributes that describe the user.

In the current implementation of Mobile Connect only the unique Telstra subscriber identifier is returned. This identifier is what you would initially store against a user in your database, and then going forward would be used to determine who the person trying to authenticate into your application.

Future implementations are planned to return more information about the user which Telstra knows and stores.

Considerations:

  • There is a one to one mapping at Telstra's end between a mobile phone number and a subscriber identifier.

Request

TOKEN="<access_token>" 
curl -i -H "Authorization:Bearer $TOKEN" "https://api.telstra.com/v1/mobileconnect/userinfo"
Parameter Name Type Description Format Example
Accept HTTP Header Indicates the content type required for the response. The Userinfo API is defined with a JSON response type and servers may ignore this header or generate an error if a value other than application/json is specified. String (Mime Type) application/json
Authorization HTTP Header Requests to the userinfo endpoint require the application/service to provide a valid 'access_token' in the form of an HTTP Authorization bearer token. The provided 'access_token' must be valid (i.e. not expired) and be associated with an authorisation request which includes scope values accessing user attributes String Bearer e760f2a4-9586-11e4-827d-a7c00892f0aa

Response

Parameter Name Type Description Format Example
sub JSON data Subject Identifier of the user. String ffa1234567dff3222eff81bfffab39ff
updated_at JSON data Time at which the user's profile data was last updated. Its represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. Integer 1432611528899

 

Demo Application - ‘Secure Bank’

A sample application has been developed to illustrate how you might use the Connect API to login to a sample banking application. This application allows you to login with Connect and Mobile Connect APIs.

T.DEV's Mobile Connect demo application: https://mobile-connect.herokuapp.com and source code
GSMA Mobile Connect demonstration: http://mc.mobilesites.net/walkthrough.html