Mobile Connect Getting started

Workflow

Reference: MobileConnect-flow

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 

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).

 

    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 TelstraDev. You must agree to the GSMA Mobile Connect terms and conditions.

    2. Your application gets provisioned in TelstraDev and GSMA API Exchange.

    3. Once provisioned with API Exchange, API keys will be available to you on you TelstraDev 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 ":" | base64`
REDIRECT_URL="your redirect url"
CODE="code from authorisation"
 
curl -i -H "Accept: application/json" -H "Authorization: Basic " "https://api.telstra.com/v1/mobileconnect/token?grant_type=authorization_code&code=&redirect_uri="

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 " "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

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.

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