Mobile Connect France – Limited (1.0) API – Getting started

Preliminary

The Authentication France - Limited API allows you to benefit, from the Orange authentication - based on Mobile Connect standard, on your service. Once implemented, your service will benefit from the full power and security of Orange authentication, including its future evolutions.

Use cases:

Federating the IDs
Authenticating the end-user and invoking APIs
Tokens lifecycle / Refresh tokens

Mobile Connect

Overview

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

OpenID Connect combines Authentication and Authorization, and allows you to verify the identity of the end-user while authorizing them.
Mobile Connect is provided by individual mobile network operators and delivered through a standardised technical interface.

Mobile Connect encompasses two principal APIs:

The Discovery API that enables your application to recognise the mobile network being used and whether Mobile Connect is available for that network. It also provides to your application the URL and credentials of the Orange AUthentication API corresponding with the user's network.

The Discovery API is provided by GSMA. Documentation can be found at: https://developer.mobileconnect.io/content/discovery-api.
Onboarding is necessary to be able to call this API from your application. The GSMA onboarding process can be done here: https://developer.mobileconnect.io/getting-ready-to-go-live

The Authentication API (aka Mobile Connect API on GSMA website) allows the users to authenticate themselves using their user Mobile Connect user account.

This API is provided by Orange for Orange user (other MNOs expose the same API for their own users).

NOTE: Orange implementation is compliant with Mobile Connect profile, and OpenID Connect Basic Client Implementer’s Guide with some restrictions:

the acr_values parameter which is optional instead of mandatory ;
the nonce parameter which is optional instead of mandatory ;
the state parameter which is mandatory in our implementation for security reasons (see RFC6819 section-5.3.5) ;
the prompt parameter which only accepts the following values: none, login and consent. The 'select_account' value is not supported ;
the login_hint parameter must contain the encrypted MSISDN (tagged as ENCR_MSISDN:) that is is returned by Discovery API in the form of "subscriber_id".
the id_token_hint parameter is not supported ;
the claims_locales parameter is not supported ;
the dtbs parameter is not supported.

More information about Mobile Connect: please visit the GSMA website

Setting up Mobile Connect

Before we jump straight into details, you should first have a good understanding on the key stages you will go through in order to integrate Mobile Connect within your service/application.

Onboard on GSMA Developer portal:

sign-up, create your application and get back access URL and credentials (key/secret) for sandbox and integration endpoints.
More information is available here

Onboard on Orange Partner Developer portal: sign-up, declare you application and subscribe to the Authentication Spain API.

this step is mandatory in order to be granted access to Orange Spain’s network,
you will receive an email notification from us in two business days, confirming that your service/application has been provisioned on Orange Spain network.

Update your portal login page to integrate the Mobile Connect button

design of the button in multiple size, and brand usage guidelines are provided by GSMA.

Install the Mobile Connect SDK that enables easy implementation of the Discovery API and the Authentication Spain API

SDKs are available for servers (Java only) and for clients (HTML5, native iOS/Android platforms).

On Orange Partner's email notification reception, you can then start using our Authentication API using MNO's client_id/client_secret credentials retrieved thanks to GSMA's Discovery API.

please watch carefully these security guidelines for implementation : https://developer.mobileconnect.io/content/faqs#security.

Run integration tests: this requires an active Orange France SIM card.
Go live: update the Discovery endpoint and Discovery credentials in your service/application with the production values that you received earlier from GSMA team in promote application step

see "My Apps" section of Mobile Connect Developer portal,
you are ready to use Mobile Connect.

OpenID Connect scopes for Identity use cases

scopes	description
openid	requests an ID token and retrieves User Identification for SSO
offline_access	requests a refresh token

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 use the /openidconnect/fr/v1/authorize endpoint and typically load the following URL in a Web Browser or in a toolkit WebView:

curl -X GET \
    "https://api.orange.com/openidconnect/fr/v1/authorize?\
    scope=openid\
    &response_type=code\
    &client_id=6KRHymujF...8SG2g\
    &login_hint=ENCR_MSISDN:<value>\
    &acr_values=2\
    &state=upToYouData\
    &redirect_uri=https%3F%2F%2Fwww.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 to an authentication page, and upon end-user authentication, to a consent page in order to collect end-user consent. Once this is done, the redirect URL is automatically called back with an authorization code :

https://www.myserver.com/?code=OFR-455f386216bd694f9bd695...00947028a&state=upToYouData

Get the tokens

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=OFR-455f386216bd694f9bd695...00947028a\
    &redirect_uri=https%3F%2F%2Fwww.myserver.com" \
    https://api.orange.com/openidconnect/fr/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": "OFR_6KRHymujF...8SG2g_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 separated 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.fr/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.

The amr/acr values supported by Orange for the Authentication Spain API are the following:

amr	acr	description
`SMS OTP`	2	Authentication using a code sent to the authentication device and filled by the user on the consumption device.
`OK`	2	Authentication by challenge sent to the mobile and validated by clicking OK.
`SIM_PIN`	3	Authentication by challenge sent to the mobile and validated by providing a 4-digits PIN.

More information about JWT (id_token) is available here.

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

Authenticating the end-user and invoking APIs

Authenticating the end-user and getting the authorization to access APIs

To authenticate and get the authorization to invoke APIs, you need to complete the two steps already described above:

Send the Authentication/Authorization request to Orange Authorization server
Get the tokens

To get authorizations on a specific scope of Orange APIs, you must specify that scope in the scope parameter of the Authentication/Authorization request in addition of the openid value.

One or more scope values are defined for each Orange API (see APIs documentation for more details).

In the example below, the scope parameter is set to openid form_filling (space-separated list) to get authorization to access to Form Filling API:

curl -X GET \
    "https://api.orange.com/openidconnect/fr/v1/authorize?\
    scope=openid%20form_filling\
    &response_type=code\
    &client_id=6KRHymujF...8SG2g\
    &login_hint=ENCR_MSISDN:<value>\	 
    &acr_values=2\
    &state=upToYouData\
    &redirect_uri=https%3F%2F%2Fwww.myserver.com"

Invoking the APIs

The obtained access_token gives you the authorization to invoke the APIs corresponding to the requested scopes (provided that it was authorized by the end-user).

To invoke Orange APIs in an authorized manner, you must then provide that access token in each request to the Orange APIs (e.g. Form Filling, Check ID...) as an HTTP Authorization header based on the following syntax:

Authorization: Bearer OFR_6KRHymujF...8SG2g_73411857a0913720e3981d0f9766d...ccd87351613f

Tokens life-cycle / Refresh tokens

Tokens life-cycle

Access tokens have a limited validity period. They must be renewed periodically (see 'expires_in' field – validity period in seconds).

To get new tokens you need to complete the two same steps again:

Send the Authentication/Authorization request to Orange Authorization server
Get the tokens

Another mechanism allows you to renew the access tokens based on a refresh token without involving the end-user. That refresh token can be requested in the first step through the specific offline_access scope:

curl -X GET \
    "https://api.orange.com/openidconnect/fr/v1/authorize?\
    scope=openid%20refresh_token\
    &response_type=code\
    &client_id=6KRHymujF...8SG2g\
    &login_hint=ENCR_MSISDN:<value>\
    &acr_values=2\
    &state=upToYouData\
    &redirect_uri=https%3F%2F%2Fwww.myserver.com"

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=OFR-455f386216bd694f9bd695...00947028a\
     &redirect_uri=https%3F%2F%2Fwww.myserver.com" \
     https://api.orange.com/openidconnect/fr/v1/token

The corresponding response will look like:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store 
Pragma: no-cache

{
  "token_type": "Bearer",
  "access_token": "OFR_6KRHymujF...8SG2g_73411857a0913720e3981d0f9766d...ccd87351613f",
  "expires_in": 3600,
  "refresh_token": "OFR-9f4d17be1982fee2a07e8d788efc...7a3cd09cf980",
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL29wZW5pZC5v...mFtciI6WyJPSyJdfQ.cYQPopPvMvwPbfDddaEII1_qF76ykw2xtQAWDFcQ9rY"
}

Using the Refresh token

As stated above, the obtained refresh_token can be used to get a new access_token in order to invoke APIs on the same initially authorized scopes. You must authenticate by communicating your application/service credentials in the HTTP Authorization header using the HTTP Basic method as usual :

curl -X POST \
     -H "Authorization: Basic NktSSHl...UdnlrT2lOaA==" \
     -d "grant_type=refresh_token\
     &refresh_token=OFR-9f4d17be1982fee2a07e8d788efc...7a3cd09cf980\ 
     &redirect_uri=https%3F%2F%2Fwww.myserver.com" \
     https://api.orange.com/openidconnect/fr/v1/token

You will obtain the following response, along with a new access_token, which will allow you to access the end-user's resources:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store Pragma: no-cache

{
  "token_type": "Bearer",
  "access_token": "OFR_6KRHymujF...8SG2g_eeae3130b661e808edd600b4d89dd...2e9ecab58f7a",
  "expires_in": 3600
}

Mobile Connect France - Limited - Getting started

Experience sign in without login and passwords with Mobile Connect authentication - Limited API - Getting started