Introduction

The Connect API provides a building block for simple authentication.

Instead of relying on the traditional pattern of username and password as login credentials, users are authenticated via SMS. This relies on the user’s mobile phone number, and their response to an SMS message with the one-time passcode as generated by Telstra.

The advantage of Connect is that users don’t need to remember yet another login and password in order to access your application. Rather, they simply just enter their mobile phone number and then respond to an SMS.

Once you have implemented Connect in your application, users who choose it as the login method will be redirected to a form hosted by Telstra, where they are prompted to enter their mobile phone number. Upon replying to the SMS with the correct code, the user’s browser will automatically redirect to the page you have specified.

Considerations
  • Only works with Australian mobile numbers.
  • Your users may incur a charge in order to send the reply SMS containing the one-time passcode.
  • OpenID Connect may not be appropriate for applications which require strong security as it does not involve a ‘secret’ credential. For example, if someone had access to the user’s mobile phone, they may be able to authenticate without any needing other information or password.

Authorisation

The first step when using the 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 name are shared).

As part of the authorisation process, the end user is first authenticated. Once the user is authenticated, your application then becomes authorised to access the end user’s details from Telstra. Once consent has been granted, your application continues to be authorised to access the end user’s details from that point on.

Once the authenticated session has expired however, the ‘authorize’ endpoint is required to be called in order to create a new authenticated session (authorisation to access details has previously been provided to your application).

The 'authorize' endpoint 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
https://api.telstra.com/v1/identity/authorize
Header Description Example
response_type Must be code code
client_id Your application Consumer Key AbCdEf12345678900987654321aBcDeF
scope Must be CONNECT CONNECT
redirect_uri This is where the user is redirected after a successful authentication. Make sure it matches what was used during registration! http://en.wikipedia.org/wiki/Area_51
state (optional) Temporary opaque value that was provided as a request parameter to authorize to prevent CSRF by maintaining state between the request and the callback. This would ordinarily be stored in a browser cookie and compared to the state value returned in the response.
Response

After the authentication process is complete, a 302 redirect is issued back to the url specified in the redirect_uri parameter in the original authorize request.

Param Description
redirect_uri This is where the user is being redirected to after the successful login
scope Will always be CONNECT
state Temporary opaque value that was provided as a request parameter to authorize.
Used to maintain state between the request and the callback.
Should be validated to be the same as the original request by the client application (usually through the use of browser cookies).
code The code used to retrieve the authorisation token

Token

The next step in the process is to obtain an access token by exchanging the authorisation code obtained in authorisation.

Request
https://api.telstra.com/v1/identity/token
Query param Description Example
client_id Your application Consumer Key AbCdEf12345678900987654321aBcDeF
client_secret Your application Consumer Secret 1234567890ABCDEF
grant_type Must be 'authorization_code' (or refresh_token) authorization_code
code The code parameter from the Authorisation redirection ABCD1234
Response
Attribute Description
access_token This is the token that you will need to retrieve the user info
id_token JSON Web Token (JWT) that contains Claims about the Authentication event.
refresh_token Use this token to request an extension on the expiry time
expires_in The time (in seconds) until the access token becomes invalid. Default is 3600 seconds (1 hour)

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 OpenID 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 use 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
https://api.telstra.com/v1/identity/userinfo
Header Description Example
Authorization 'Bearer' followed by the access_token from the token response Bearer ABCD22bjvGHS22YkE5QVIBdbCXYZ
Response

The list of attributes returned for a subscriber are:

Attribute Description Example
sub Unique subscriber identifier 1234567886daa3222efe81bfaabbccdd

Example Implementation

The diagram below describes a suggested implementation of this API.
In this implementation:

  1. The user begins the authentication process on a web form served from the client application
  2. In response, the browser is issued with a 302 redirect to the authorize end point
  3. The authorize end point will guide the user through the authentication and authorisation process, eventually resulting in a 302 redirect to the provided redirect_uri which the browser follows
  4. In response to the redirect_uri request, the client application sends a token request to the API to retrieve a token
  5. The client application then sends a user info request to the API to retrieve the user's sub identifier
  6. The sub id is used to lookup the user's profile in the client application's database, and the user is successfully authenticated

 

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 Connect API demo application: https://mobile-connect.herokuapp.com and source code