Authentication France
Benefit from the Orange authentication services to manage the sign-in and consent of your users.

Preliminary

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

If you don't have an Orange end-user account, or you need account management help, please refer to the following guides :

Use cases :

OpenID Connect

The Authentication France API is a function provided by the OpenID Connect standard.

OpenID Connect combines Authentication and Authorization, and allows you to verify the identity of the end-user while authorizing them. All information regarding OpenID Connect can be found at http://openid.net/connect.

Orange implementation is inline with the OpenID Connect Basic Client Implementer’s Guide. The only difference is the "state" parameter which is mandatory in our implementation for security reasons (see RFC6819 section-5.3.5).

OpenID Connect scopes in Identity use cases

ScopesDescription
openidrequests an ID token and retrieves User Identification for SSO

More information about OpenId connect and authentication:

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 in OAuth 2.0 and OpenID Connect.

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 endpoint /openidconnect/fr/v1/authorize 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\
     &state=upToYouData\
     &redirect_uri=http%3A%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 :

http://www.myserver.com/?code=**OFR-251f7...716a727f**&state=upToYouData

Using semi-implicit authentication on mobile

In order to benefit from the end-user semi-implicit authentication, you need to authenticate as follows :

curl -X GET \
     "https://api.orange.com/openidconnect/fr/v1/authorize?\
     scope=openid\
     &response_type=code\
     &client_id=6KRHymujF...8SG2g\
     &state=upToYouData\
     &redirect_uri=http%3A%2F%2Fwww.myserver.com\
     &charset=utf8"

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-251f7...716a727f\
     &redirect_uri=http%3A%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 :

{
   "access_token": "OFR_6KRHymujF...8SG2g_948ef...d5de1f4",
   "expires_in": 3600,
   "id_token": "eyJ0eX...8UtIl7mk",
   "token_type": Bearer
}

Decode the token

To decode the id_token, 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 :

{
   "iss": "{Orange Authorization Server}",
   "sub": "PBYJJF-200-DwltrLnXq+7jwTQEkOx9Z9jelg0t0NQrxWFasUgUgEs=",
   "aud": "xxxxxxx",
   "exp": 1397141663,
   "iat": 1397138063,
   "auth_time": 1397138057,
   "acr": 0
}

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.

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 :

  1. Send the Authentication/Authorization request to Orange Authorization server
  2. 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 cloud profile (space-separated list) to get authorization to access cloud and profile APIs :

curl -X GET \
     "https://api.orange.com/openidconnect/fr/v1/authorize?\
     response_type=code\
     &client_id=6KRHymujF...8SG2g\
     &scope=openid%20cloud%20profile\
     &redirect_uri=http%3A%2F%2Fwww.myserver.com\
     &state=uptoyoudata"

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. User Details, Cloud...) as an HTTP Authorization header based on the following syntax :

Authorization: Bearer OFR-cdda38bba6b8eb3860bbd96af250906c98117db259b4500dfb69841383283bd535c560c76103a9daae17124baa5514ff337a1023d1eb01f2beb44cfc1cd0c2b4

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:

  1. Send the Authentication/Authorization request to Orange Authorization server
  2. Get the tokens
curl -X GET \
     "https://api.orange.com/openidconnect/fr/v1/authorize?\
     response_type=code\
     &client_id=6KRHymujF...8SG2g\
     &scope=openid%20cloud%20profile\
     &redirect_uri=http%3A%2F%2Fwww.myserver.com\
     &state=uptoyoudata"

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_cdda38bba6b8eb3860bbd96af250906c98...23d1eb01f2beb44cfc1cd0c2b4",
   "expires_in": 3600,
   "refresh_token": "OFR-ce289cd9eab533b074122a482ee221bbc...f6c9956e72ee700f805576585c536e2",
   "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1Ni...KQY36yfUISfjPL1XRvyBCpZVR8ok"
}

Using the Refresh token

As stated above, the obtained "refresh token" can be used to get a new "access token" 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-ce289cd9eab533b074122a482ee221bbc...f6c9956e72ee700f805576585c536e2\ 
     &redirect_uri=http%3A%2F%2Fwww.myserver.com" \
     https://api.orange.com/oauth/v2/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

{
   "access_token": "OFR_6KRHymujF...8SG2g_cdda38bba6b8eb3860bbd96af2509...9279cec2b91ced71f84",
   "token_type":"Bearer",
   "expires_in": 3600
}