Mobile Connect is the mobile operator facilitated authentication solution, that provides simple, secure and convenient access to online services. It is the convenient alternative to passwords that protect customer privacy. This is a concept introduced by the GSMA (GSM Association), which provides a global and secure authentication platform, by combining the user's unique mobile number and PIN, to verify and authenticate the user, anywhere anytime. It also allows the user to log into swiftly, without the need of any usernames or passwords.
To get a better understanding, read the following
The Mobile Connect flow consists of two standard APIs.
Discovery API (Powered by Apigee)
Mobile Connect API (By the IDP of MNO)
Mobile Connect Flow
The following diagram depicts the high level view of how the sequence of activities occur in terms of Mobile Connect Authentication.
Discovery API
The Discovery API service contains information related to many Mobile Network Operators and it's purpose is to provide necessary details of the Mobile Network Operators (MNOs) and also provide the relevant endpoints of each MNO, which can be used to contact each MNO's Mobile Connect API. Every Mobile Network Operator has a MNC (Mobile Network Code) , and a MCC (Mobile Country Code). The Discovery API service will identify the relevant MNO and identifies the MNC and MCC required to proceed with the authentication process. The Discovery API requires details related to the user's MSISDN (Mobile Station International Subscriber Directory Number) or MCC_MNC. The Service will automatically identify these details if the user is using a Mobile Internet Connection (i.e. GPRS, 3G, 4G etc.). This scenario is called "On-Net Mobile Connect".
If the user is using any other connection like a WiFi connection or a Broadband connection, then the user will be prompted for the MSISDN or the name of the MNO. The Discovery API will redirect to its own UI called " Operator Selection User Interface". This scenario is called "Off-Net Mobile Connect".
Operator Selection User Interface
This is a web based user interface provided by the Discovery API the determine the user's home operator (MNO). This interface also supports multi languages to provide flexibility to users all around the globe. This interface will be prompted by the service whenever it cannot automatically identify the Mobile Network Operator of the user.
Upon a successful lookup from the information provided by the user, it will provide the MNO's MCC and the MNC to the redirect URL that we specify at the application registration. To enable this functionality, the Mobile Network Operator has to implement this feature by injecting custom Http headers and other relevant information.
Use Cases of Discovery API
(1) Mobile Internet Connection + Mobile Device - The authentication process will happen seamlessly. No user interaction at all
(2) Mobile Internet Connection + Computer - The service will try the retrieve the relevant information from the sim. If failed, it will prompt for the user information, and manual authorization is required
(3) Broadband/ WiFi Connection + Computer/Mobile - The user will have to input relevant information and manual authorization is also required.
Environments of Discovery API
For us to access the "Discovery API", the GSMA has made available, two different kinds of environments for the ease of implementation.
Sandbox Environment: http://discovery.sandbox2.mobileconnect.io/v2/discovery
Production Environment: https://discover.mobileconnect.io/gsma/v2/discovery
Access to the sandbox environment can be retrieved from the Official Mobile Connect Developer Site. Access to the Production Environment should be received by contacting the GSMA and requesting for official access for the Discovery API.
Discovery API Specifications
REQUEST
Header Parameters
Mandatory Parameters
Eg: client_id = "key"
client_secret = "secret"
base 64 encode of "key:secret" = "a2V5OnNlY3JldA==" (Use this website to encode and decode) Authorization = "Basic a2V5OnNlY3JldA=="
Optional Parameters
Query Parameters
Mandatory Parameters
The "Redirect_URL" is the URL on our side, which will handle the response being sent by the "Discovery Service". This "Redirect_URL" should be passed as a query parameter to the Discovery Service and the redirect URL should be registered with the service at the registration of the application. Because if you send a different URL from what you used at the application registration, it will send an error message saying "Invalid Redirect URL".
Eg:
Optional Parameters
RESPONSE
"subscriber_id" in the response gives an encoded MSISDN value which could be passed to the "Mobile Connect API" along as a value for the parameter "login_hint". (see below for usages). If we send this value to the "Mobile Connect API", the MNO will identify the MSISDN and does the authorization accordingly. But if we don't pass the "subscriber_id" into the "Mobile Connect API", the MNO's Mobile Connect IDP will prompt for the user's mobile number at the "Authentication Endpoint". (See below for more).
The "client_id" and "client_secret" received by the above response, should be the credentials to be used to contact the relevant "Mobile Connect Endpoint".
Response codes sent by the Discovery API
(1) 200 - OK : The response from the servers are successful
(2) 404 - Not Found : Bad MSISDN is supplied/ wrong MCC_MNC
(3) 400 - Bad Request : Redirect URI is missing
(4) 401 - Unauthorized : Incorrect Credentials / Bad Session
Mobile Connect API
Mobile Connect API is a service which is based OpenID Connect and it is an extension which includes more flexibility to the entire process. And this extended version is called the Mobile Connect Profile or the Mobile Connect API. The Mobile Connect API is normally an implementation done from an IDP (Identity Provider) and instead of the normal Authorization mechanism which uses the traditional username and password, this uses the mobile number to access the mobile device for authorization.
Level of Assurance (LoA)
LoA or the Level of Assurance, describes the degree of confidence, in various security processes including authentication. (According to the ISO/IEC 29115 Standard). It provides assurance that the entity claiming a particular identity, is the entity to which that identity was assigned. During the Mobile Connect Authorization process, the application declares the degree of confidence required in the returned identity. The greater the risk associated with an erroneous authentication, the higher the Level of Assurance recommended. There are four Levels of Assurance (LoA) 1) Level of Assurance 1 (not supported by Mobile Connect) 2) Level of Assurance 2 (Requires a simple key press) 3) Level of Assurance 3 (Requires a simple key press) 4) Level of Assurance 4 (not supported by Mobile Connect) for more details view Level of Assurance (LoA)
Each and every operator, should implement at least one type of authenticator per LoA. MNO's define authenticators in order to confirm that the user is who he/she claims to be. Following are the mechanisms used by the Mobile Connect API as authentications.
SMS + URL : SMS sent to the user's device with a unique one-time only URL (LoA 2)
USSD : The operator will push a message to the terminal and can require a response (LoA 3)
SIM Applet : A binary SMS will be sent to trigger the SIM applet (LoA 3)
Mobile Connect Endpoints
This is similar to OIDC protocol and it has the main three endpoints mentioned in the OpenID Connect Protocol.
Authentication Endpoint
Whenever the system needs to initiate an Authentication request, it has to call this endpoint. It will return a randomly generated code via a Http Redirect to the given Redirect_URL. If the redirect_url doesn't match the URL provided at the application registration, the endpoint will throw an error. This is to ensure that no one is able to hijack the system implementation.
Token Endpoint
The code received from the "Authentication Endpoint" should be used to access the "Token Endpoint", and in return it will return the tokens (id_token/ access_token) required. Each token has its own purpose.
The id_token contains information known as claims of the authentication/authorization requests. A decoded id_token is given below. To decode id_tokens, use this website. (note: not all claims are mandatory and varies across different operators.)
The access_token is a randomly generated string that can be used to access the "UserInfo Endpoint". This contains the permissions to access the information.
UserInfo Endpoint
This is not officially a part of the Mobile Connect System. This is owned by the "Mobile Network Operator" as they own all the information related to the user having the MSISDN. If the MNO requires, they can provide support so that the userinfo endpoint is supported by the Mobile Connect implementation, for the relevant MNO.
Mobile Connect API Specifications
Authentication Endpoint
Request
Query Parameters
Mandatory Parameters
The "scope" defines what claims needs to be requested from the servers. "openid" is a mandatory value for scope in the Mobile Connect Specification. If you wish to include others scope values, use a space and separate the values you require.
Eg:
"scope" = "openid email address phone offline_access"
The "acr_values" specify the LoA required for this process. Mobile Connect currently supports only 2 and 3. You can specify either one value or even both. If you specify both, the IDP will first try the first value, and if failed, it will move to the next value.
Eg:
"acr_values" = "2 3"
The "state" and "nonce" values should be maintained accordingly to ensure the consistency of the session. Normally, the "sessionID" or the "sessionDataKey" is being passed for these values. These maintain the security of the process.
Optional Parameters
Response
The "code" is the randomly generated string that can be used to access the "Token Endpoint". "state" is the value sent to the authorization endpoint, and the same value is being returned for us to check the consistency of the process.
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
Header Parameters
Mandatory Parameters
Eg: client_id = "key"
client_secret = "secret"
The "client_id" and "client_secret" are the values returned by the "Discovery_API".
base 64 encode of "key:secret" = "a2V5OnNlY3JldA==" (Use this website to encode and decode) Authorization = "Basic a2V5OnNlY3JldA=="
Query Parameters
Mandatory Parameters
"code" is the value which is being returned by the "Authorization Endpoint". That value should be used here to access the "Token Endpoint".
"grant_type" specifies, the type of the "code" that we submit as a query parameter to the "Token Endpoint". This value is always set to "authorization_code" according to the Mobile Connect Specifications.
The "Redirect_URL" is the URL on our side, which will handle the response being sent by the "Token Endpoint". This "Redirect_URL" should be passed as a query parameter to the "Token Endpoint" and the redirect URL should be registered with the service at the registration of the application. Because if you send a different URL from what you used at the application registration, it will send an error message saying "Invalid Redirect URL".
Response
The "Token Endpoint" response looks like this.
The "id_token" is a Base64 encoded value which contains a JSON Payload. To decode the value, use this website.
The "expires_in" value specifies the TTL (Time To Live) for this session before the relevant tokens expire
Mandatory Parameters
Optional Parameters
UserInfo Endpoint
Request
Header Parameters
Mandatory Parameters
"Authorization" - Bearer access token which is being returned by the token endpoint can be used here to access the user information provided by the MNO. The value for should be taken as mentioned below.
get the "token_type" value from the "Token Endpoint" which is always "Bearer" in the case of Mobile Connect. And attach the "access_token" with it, as the authorization header. See following example.
Eg:
Authorization - "token_type" + <space> + "access_token"
Authorization - "Bearer 37bbbc40-35f8-11e5-a6b7-179fcb054c5a"
Response
A JSON object will be returned by the "UserInfo Endpoint" which contains the relevant user information which is allowed by the MNO, and which is requested by the permissions provided by the "access_token". A sample response is given below.
{ 'msisdn' = '94779711788'
}
References