What is Mobile Connect?

Mobile Connect is a user authentication and identity service based on the OpenID Connect/OAuth2 standards.

Mobile Connect is provided by individual mobile network operators and delivered through a standardised technical interface.

Mobile Connect uses two principal APIs:

• The Discovery API – implemented by GSMA API Exchange platform: it enables your application to recognise the mobile network being used and whether Mobile Connect is available for that network. It also provides your application with the various URLs for the Mobile Connect service corresponding with the user’s network.
• The Mobile Connect API – aka Authentication API, implemented by Orange Mobile Network Operator (MCO), and published through Orange Developer website: it allows the users to authenticate themselves using their Mobile Connect user account.

The Mobile Connect APIs are based on industry standard RESTful API principles.

Each API is provided over HTTPS protocol so that you can incorporate Mobile Connect in your application regardless of the programming language or operating system you are using for development.

What are the difference with OpenID Connect standard?

Globally speaking, the Mobile Connect API is based on the same standards and attributes defined by the OpenID Connect/OAuth 2.0 specifications. See Mobile Connect profile for more information.

The differences are that certain parameters defined by OpenID Connect to be optional have been defined within Mobile Connect as mandatory as they are required to support the security aspects of Mobile Connect necessary to support the different authenticators.

Finally, operators’ implementation of Mobile Connect standard may bring additional restrictions. See Mobile Connect implementation by Orange for further details.

How does Mobile Connect work?

You need first to include the Mobile Connect button in your application.

This will let users know that by using their mobile number they will be able to identify themselves to your application, provided their operator supports Mobile Connect.

When users click on the Mobile Connect button, the GSMA Discovery Service behind the Discovery API will identify the user’s mobile operator. The Discovery Service will try to do this without requiring input from the user, but this is not possible, the user will be brought to the Operator Selection User Interface.

What is a Level of Assurance (LoA)?

A Level of Assurance, as defined by the by ISO/IEC 29115 Standard, describes the degree of confidence in the processes leading up to and including an authentication. It provides assurance that the entity claiming a particular identity, is the entity to which that identity was assigned.

During a Mobile Connect API authentication request, the application declares the degree of confidence (LoA1 to LoA4) that is required in the returned (asserted) identity, using the acr_values parameter (e.g. acr_value=2 for LoA2).

The greater the risk associated with an erroneous authentication, the higher the Level of Assurance recommended.

More information about Level of Assurance is available.

What are 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. The higher the LoA, the more secure the technology applied by operators to perform authentication will be.

Mobile Connect API implementation by Orange

This section is about the level of support of Mobile Connect standard by Orange Spain operator.

Some parameters of Authorization request are optional instead of mandatory. Some of them aren’t supported, and some restrictions exist for others (for example, prompt & acr_values parameters).

Parameter	Mobile Connect	Orange implementation
state	Mandatory	Mandatory for security reasons (see RFC6819)
nonce	Mandatory	Optional
prompt	Recommended	Recommended. Supported values: none, login, consent
max_age	Recommended	Recommended
acr_values	Mandatory	Optional. Supported values: 2, 3
login_hint	Optional	An indication to the IDP/Authorisation Server on what ID to use for login. The login_hint MUST contain the encrypted MSISDN (tagged as ENCR_MSISDN:) that is is returned by Discovery API in the form of “subscriber_id”.
id_token_hint	Optional	Not supported
claims_locales	Optional	Not supported
dtbs	Optional	Not supported

The list of supported authentication methods (amr) is provided below with corresponding Level of Assurance.

Authentication methods (amr)	Level of Assurance (LoA)	Description
SMS OTP	LoA2	Authentication using a code sent to the authentication device and filled by the user on the consumption device.
OK	LoA2	Authentication by challenge sent to the mobile and validated by clicking OK.
SIM_PIN	LoA3	Authentication by challenge sent to the mobile and validated by providing a 4-digits PIN.

Discovery API

Overview

The Discovery Service provides the developer with details of the home operator that serves the user. Once you obtain the details for a specific user you can perform the Mobile Connect API calls to authorise that user.

Every mobile operator has a Mobile Country Code (MCC) and Mobile Network Code (MNC) to identify themselves. The Discovery service will identify the MCC_MNC and return the details, along with the relevant operator’s Mobile Connect API details, to an application. This enables the application to call the relevant Mobile Connect service.

The Discovery service has various methods of obtaining the MCC_MNC information.

1. A user is accessing your service from a web browser/tablet where you cannot get the MCC/MNC directly
   • To obtain the user’s MCC/MNC, forward the user to the Operator Selection User Interface. This allows the user to enter their MSISDN and the correct MCC/MNC will be identified and returned to you. With this information you will be able to invoke the Discovery API to obtain the details required to perform the Mobile Connect authorisation process.
2. A user accessing your service from a Smartphone Mobile Application where your application is able to retrieve the MCC_MNC from the SIM card
   • After obtaining the MCC/MNC from the SIM, you can invoke the Discovery API to obtain the details required to perform the Mobile Connect authorisation process.
3. A user accessing your service from a web browser/tablet where you know their MSISDN number
   • Invoke Discovery API with the MSISDN to obtain the details required to perform the Mobile Connect authorisation process.

Where possible, this is done in the background, but in some situations the mobile number is required from the user. Here, the Discovery service will present an “Operator Selection User Interface” prompting the user to enter their MSISDN.

Operator Selection UI

The Operator Selection User Interface, is a web-based application service provided by the Discovery API that determines the home operator of your user.

The Operator Selection User Interface URL is obtained via the Discovery API request. The URL is protected with a unique session_id. If an invalid session_id is provided, an error will be displayed instead of the Operator Selection User Interface.

Here the user will be asked to enter their mobile phone number (MSISDN). The Discovery Service will use this to determine the user’s home operator.

TIPS: Please note that the Operator Selection User Interface is also able to automatically recognise the serving operator if the user is accessing your service via a Mobile Data Network. This functionality is only available when an operator has implemented this feature.

Upon a successful lookup, the operator’s Mobile Country Code and Mobile Network Code (in MNC_MCC format) will be redirected to your Redirect_URL. As an example:

HTTP/1.1 302 Moved Temporarily
Location: http://www.myserver.com?mcc_mnc=901_01

If the mobile phone number can’t be resolved (in case of bad MSISDN for instance), the user will be requested to change the number or to choose a mobile network (shown in figure below).

On ‘Choose mobile network’ button click, the user selects the region (e.g. south europe), then the country (e.g. spain) and finally the operator (shown in figure below).

API Reference

Prerequisites

In order to call the Discovery API, you will need credentials for your application: they are used by the GSMA API Exchange platform to identify your application and allow it to make calls to the Discovery API. You will receive these credentials when you create your application on the Mobile Connect Developer portal.

At the end of this registration process, you will be provided with:

• a client_id: a unique ID provided by the GSMA API Exchange to identify your application,
• a client_secret: it is used to sign/encrypt the requests and must be shared by the client and server,

The client_id and client_secret are used to specify the authorization_header.
Its value is composed of the keyword “Basic”, followed by a space and the base64 encoding of the concatenation of your client_id, “:” and your client_secret.

In Javascript, the authorization_header will look something like:

authorization_header = "Basic " + btoa(client_id + ":" + client_secret)

See Mobile Connect developer portal (My Apps) to get access to these credentials.

Discovery API features

Both GET and POST methods are supported for the Discovery request.

The Authorization header is mandatory, as well as the Redirect_URL parameter.

curl -X GET 
   -H "Authorization: {authorization_header}" 
   http://discovery.mobileconnect.io/v2/discovery?Redirect_URL=http://www.myserver.com

curl -X POST 
-H "Authorization: {authorization_header}" 
   -d "Redirect_URL=http://www.myserver.com" 
   http://discovery.mobileconnect.io/v2/discovery

See Mobile Connect developer website for further details.

Software Development Kit (SDKs)

Software Development Kits (SDKs) are available to help incorporate the Mobile Connect API into your applications/ services. These are available for web applications using Java server side, HTML5 and the Android and iOS operating systems.

For other operating systems the Mobile Connect API can be used directly via the HTTP / RESTful APIs which can be invoked from any other environment such as PHP, Ruby, Python or Java servers.

A combined package of all the Mobile Connect SDKs can be downloaded from Github website.

Environments

Several environments are made available by GSMA for its API Exchange platform (see table below).

environment	Discovery API endpoint (URL)
sandbox	http://discovery.sandbox2.mobileconnect.io/v2/discovery
production	https://discover.mobileconnect.io/gsma/v2/discovery

Discovery API usage (sandbox environment)

Step 1: operator selection UI

The Operator Selection User Interface URL (multi-language support) is obtained from the Discovery API request.

As an example:

curl -X GET 
   -H "Authorization: Basic MjU1NTU1MzUtYTE1My00...U3NTY1Nw=="
   http://discovery.sandbox2.mobileconnect.io/v2/discovery?Redirect_URL=http://www.myserver.com

On request reception, the Discovery service performs a 302 redirect to the Operator Selection User Interface URL. As an example:

http://discovery.sandbox2.mobileconnect.io/v2/discovery/users/operator-selection?session_id=eyJ0eXAiOiJKV1QiLCJhbGciOiJI...pm-uA_1lFqeTk

The Operator Selection UI URL is protected with a unique session_id.

• If an invalid session_id is provided, an error will be displayed,
• If an valid session_id is provided, the Operator Selection Web UI is displayed.

On success, the user fill the form with its mobile phone number, then click on ‘next’ button.

a/ Successful response

Upon a successful lookup, the MNO’s Mobile Country Code and Mobile Network Code (in MNC_MCC format) will be sent back to your redirect URL using the mcc_mnc query-string parameter.

HTTP/1.1 302 Moved Temporarily
Location: http://www.myserver.com?mcc_mnc=901_01

In case where the mobile number (MSISDN) was provided through the Operator Selection UI, the MSISDN (encoded value with RSA certificate) will be redirected to your redirect URL using the subscriber_id query-string parameter.

HTTP/1.1 302 Moved Temporarily
http://www.myserver.com?mcc_mnc=901_01&subscriber_id=4a0fdbc68507cecb4914...1c1713b356

b/ Error response

If the request fails due to a missing/invalid token (HTTP Basic Authentication), an error response is returned by the Discovery with a 401 Unauthorized HTTP status code.

As an exeample:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Content-Length: 115

{
   "error":"Unauthorized_Access",
   "description":"Your request needs a valid session or valid credentials"
}

---

Step 2 : Mobile Connect API’s endpoints retrieval

To obtain the details required to perform the Mobile Connect authorisation process, you must redo a Discovery request with the MNO’s Mobile Country Code and Mobile Network Code you previously received with your redirect URL, using the Select-MCC and Select-MNC query-string parameters.

As an example:

curl -X GET 
   -H "Authorization: Basic MjU1NTU1MzUtYTE1My00...U3NTY1Nw=="
   http://discovery.sandbox2.mobileconnect.io/v2/discovery?Selected-MCC=901&Selected-MNC=01&Redirect_URL=http://www.myserver.com

a/ Successful response

The details required to perform the Mobile Connect authorisation process are returned by the Discovery service.

The operatorid JSON element contains a link array that provides the list of MNO’s endpoints allowing your application to:

• make the authorization request and obtain the user consent from the requested scope,
• get the ID token, the access token, and optionally the refresh token.

The credentials to be used to access MNO’s endpoints are provided also. See client_id and client_secret elements.

As an example:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 861

{
  "ttl": 1460530586045,
  "response": {
    "serving_operator": "Example Operator A",
    "country": "US",
    "currency": "USD",
    "apis": {
      "operatorid": {
        "link": [
          {
            "href": "http://operator_a.sandbox2.mobileconnect.io/oidc/authorize",
            "rel": "authorization"
          },
          {
            "href": "http://operator_a.sandbox2.mobileconnect.io/oidc/accesstoken",
            "rel": "token"
          },
          {
            "href": "http://operator_a.sandbox2.mobileconnect.io/oidc/userinfo",
            "rel": "userinfo"
          },
          {
            "href": "openid profile email",
            "rel": "scope"
          }
        ]
      }
    },
    "client_id": "25555535-a153-4c39-af5d-658d180485c4",
    "client_secret": "da437bfe-2c7d-4b36-a9bf-7f8dfde75657"
  }
}

TIPS: using the Sandbox environment, the client_id/client_secret credentials are the same than those provided by Mobile Connect Developer website for your application.
When going live with Orange operator, the credentials sent back in the Discovery response will be different, and consistent with those allocated to the application your created through Orange Developer website during the onboarding process.

b/ Error response

If the request fails due to the missing ‘Redirect_URL’ parameter, an error response is returned by the Discovery with a 400 Bad Request HTTP status code.

HTTP/1.1 400 Bad request
Content-Type: application/json
Content-Length: 64

{
   "error": "Invalid_Request",
   "description": "Redirect_URL missing"
}

Discovery API usage (production environment)

By now, you should have successfully integrated and tested your application with GSMA API Exchange’s sandbox platform. To go live, you need to:

• update your discovery endpoint and credentials from sandbox to production,
• establish a commercial agreement with Orange operator (with specific Terms and Conditions validation), and this for each country you are intending to launch your service.

TIPS: Without this commercial agreement, you will not be authorized to retrieve Mobile Connect API endpoints for the Orange operator the user is belonging to.

Step 1: operator selection UI

The Operator Selection User Interface URL (multi-language support) is obtained via the Discovery API request.

As an example, for Orange Spain customer:

curl -X GET 
   -H "Authorization: Basic YTAwZDA3MWYtNTgzYS00...UwNDE4NA=="
   http://discovery.mobileconnect.io/v2/discovery?Redirect_URL=http://www.myserver.com

The user fills the form with its mobile number (including country code – e.g. +34691439xxx) and click on ‘next’ button.

Upon a successful lookup, the Orange Spain’s MCC/MNC codes (i.e. 214_03) will be sent back to your redirect URL using the mcc_mnc query-string parameter.

HTTP/1.1 302 Moved Temporarily
http://www.myserver.com?mcc_mnc=214_03&subscriber_id=154f34b3e0f003a3a57b...d2ee24738b

---

Step 2 : Mobile Connect API’s endpoints retrieval

To obtain the details required to perform the Mobile Connect authorisation process towards Orange Spain operator, you must redo a Discovery request with the MNO’s Mobile Country Code and Mobile Network Code you previously received with your redirect URL, using the Select-MCC and Select-MNC query-string parameters.

As an example, for Orange Spain customers:

curl -X GET 
   -H "Authorization: Basic YTAwZDA3MWYtNTgzYS00...UwNDE4NA=="
   http://discovery.mobileconnect.io/v2/discovery?Selected-MCC=214&Selected-MNC=03&Redirect_URL=http://www.myserver.com

a/ Successful response

The details required to perform the Mobile Connect authorisation process are returned by the Discovery service.

The operatorid JSON element contains a link array that provides the list of Orange Spain Mobile Connect API’s endpoints allowing your application to:

• make the authorization request and obtain the user consent from the requested scope,
• get the ID token, the access token, and optionally the refresh token.

The credentials to be used to access these endpoints are provided also. See client_id and client_secret elements.

As an example, for Orange Spain customers:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 583

{
  "ttl": 1465731942,
  "response": {
    "client_id": "a00d071f-583...b8f9e47d",
    "client_secret": "e81389cc-7b1...ff504184",
    "serving_operator": "orange_spain",
    "country": "Spain",
    "currency": "EUR",
    "apis": {
      "operatorid": {
        "link": [
          {
            "href": "https://api.orange.com/openidconnect/es/v1/authorize",
            "rel": "authorization"
          },
          {
            "href": "https://api.orange.com/openidconnect/es/v1/token",
            "rel": "token"
          }
        ]
      }
    }
  }
}

---

Mobile Connect API

Prerequisites

In order to call the Mobile Connect API, you will need credentials for your application: they are used by the Orange Developer platform to identify your application and allow it to make calls to the Mobile Connect API. You will receive these credentials when you create your application on the Orange Developer portal.

At the end of this registration process, you will be provided with:

• a client_id: a unique ID provided by the Orange Developer to identify your application,
• a client_secret: it is used to sign/encrypt the requests and must be shared by the client and server,

The client_id and client_secret are used to specify the authorization_header.
Its value is composed of the keyword “Basic”, followed by a space and the base64 encoding of the concatenation of your client_id, “:” and your client_secret.

In Javascript, the authorization_header will look something like:

authorization_header = "Basic " + btoa(client_id + ":" + client_secret)

See Orange Developer portal (My Apps section) to get access to the credentials allocated for your application.

OpenID Connect scopes for Identity use cases

Scopes	Description
openid	Requests an ID token and retrieves User Identification for Single-Sign-On.

Authenticating the end-user and federating the IDs

Send the Authentication/Authorization request to Orange Authorization server

In order to obtain OpenID Connect/OAuth tokens, you first need to request an “authorization code” as defined by OAuth 2.0 and OpenID Connect protocols.

At this stage, the Orange Authorization Server may need to authenticate the end-user and interact with him to get authorizations before releasing the “authorization code”.

You need to send an Authorization request using the Mobile Connect API endpoint (i.e. /authorize). Typically loading the following URL in a Web Browser or in a toolkit WebView:

curl -X GET 
   https://api.orange.com/openidconnect/es/v1/authorize?
   scope=openid
   &response_type=code
   &client_id=6KRHymujF...8SG2g
   &login_hint=ENCR_MSISDN:<value>
   &acr_values=2
   &state=upToYouData
   &redirect_uri=http://www.myserver.com

Remember that you need to specify the client_id and redirect_uri values you were provided during the registration process (enhanced in the above example).

For security reasons, you can only use the value specified during the registration process for the redirect_uri parameter.

Note the special encoding for redirect_uri value : it must be url encoded (e.g. “://” has to be replaced by “%3A%2F%2F”)

This URL will redirect the user to an intermediary page informing him/her that the Mobile Connect Authentication process is ongoing.

For Orange Spain (see figure above), the content of this page is the following:

Prove your identity to Mobile Connect ...

You chose accessed using Mobile Connect
Make sure you have your phone close to coverage and to confirm your identity.

Mobile Connect allows you to connect safely and comfortably through the confirmation message sent to your mobile.

The ‘cancel’ button can be used to abort the process. In that case, the authentication process aborts, and an error (i.e. error/error_description fields) will be sent back to your application using the redirection URL.

As an example:

http://www.myserver.com/?error=access_denied&error_description=login%20failed&state=upToYouData

In case of “OK” authentication method, a popup message is displayed on the authentication device. As an example:

This message includes the name of your application (as defined through Orange Developer website – see Display name field) and two buttons: ‘OK’ and ‘Cancel’. Depending on user’s choice:
* if ‘OK’, the authentication process succeeds. the redirect URL is automatically called back by our Orange Authorization server with an authorization code. As an example:

http://www.myserver.com/?code=**OES-455f386216bd694f9bd695...00947028a**&state=upToYouData

• if ‘Cancel’, the authentication process aborts, and an error (i.e. error/error_description fields) will be sent back to your application using the redirection URL. As an example:

http://www.myserver.com/?error=access_denied&error_description=login%20failed&state=upToYouData

Get tokens (id_token, access_token and refresh_token (optionally))

You can now exchange the obtained “authorization code” for tokens.

You must authenticate by communicating your application/service credentials in the HTTP Authorization header using the HTTP Basic method (“Authorization” Header = keyword “Basic”, followed by a space and the base64 encoding of the concatenation of your client_id, “:” and your client secret) :

curl -X POST 
   -H "Authorization: Basic NktSSHl...UdnlrT2lOaA==" 
   -d "grant_type=authorization_code
   &code=OES-455f386216bd694f9bd695...00947028a
   &redirect_uri=http%3F%2F%2Fwww.myserver.com" 
   https://api.orange.com/openidconnect/es/v1/token 

In the body data of the request, be sure to use the authorization code you just received and do not forget to re-set the redirect_uri.

You should receive JSON data similar to :

{
   "token_type": "Bearer",
   "access_token": "OES-73411857a0913720e3981d0f9766d...ccd87351613f",
   "expires_in": 3600,
   "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL29wZW5pZC5v...mFtciI6WyJPSyJdfQ.cYQPopPvMvwPbfDddaEII1_qF76ykw2xtQAWDFcQ9rY"
}

Decode the ID Token

The id_token comes in the form of a JSON Web Token (JWT) that is a compact, URL-safe means of representing claims to be transferred between two parties.
The JWT comes in 3 parts seperated by “.”. Each part is encoded using Base64URL format. This is not the same as Base64. Base64 has some characters which are not URL safe such as “+”, “/” and “=”.

To decode this token and extract the claims, you need to take the second segment of the token (segments are delimited by the “.” character), and base64url decode it to obtain a JSON object containing the following fields :

NOTE Don’t forget to check the signature of the id_token which is the third segment of the token (segments are delimited by the “.” character).
The signature uses an algorithm described in the first segment (for example, base64-decoded : {“typ”:”JWT”,”alg”:”HS256″} which means that HMAC SHA256 is used).

{
   "iss":"https://openid.orange.es/oidc",
   "sub":"ZIIYUW-200-EtK9jMMjilz+vlpAFymc...MN6OW8zoAvcC",
   "aud":["6KRHymujF...8SG2g"],
   "exp":1460104592,
   "iat":1460100992,
   "auth_time":0,
   "nonce":null,
   "acr":"2",
   "amr":["OK"]
}

The sub field contains the User identifier of the authenticated Orange user. As this user ID is persistent and unique for the current user of your service, you can use it in order to store some user-related information (on your server or on the user mobile for example): next time the same user will authenticate, the same call will provide you the same sub value, allowing you to retrieve related data.

As this user ID is persistent and unique for the current user of your service, you can use it in.

More information about JWT (id_token) is available.

More information about the claims that are used within the ID Token is available.

References

• Mobile Connect
• Mobile Connect for developers
• Mobile Connect documentation
• Mobile Connect operators
• OpenID Connect
• OAuth