3-Legged OAuth

Before starting

In order to call our API, you will need credentials for your client application: they are used by the back-end platform to identify your client application and allow it to make calls to the APIs. You will receive these credentials when you register your client 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 back-end server to identify your client 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)

This information is available on your application’s page when you are logged-in on the Orange Developer portal.

The Authorization Code and Refresh Token OAuth flows follow the following steps:

WARNING: OAuth 2.0 authorization protocol requires the use of HTTPS for exchanges between the client and the Orange Authorization Server due to the sensitivity of the data (for instance, app’s credentials – i.e. client_id, client_secret, ID token, access token, refresh token, authorization code).

Authorization by code

The Authorization Code grant type is used by a client application when the final user of the service is requested to give their consent in order to authorize this client application to access their resources.

This authentication process is based on OpenID Connect (OIDC), a simple identity layer on top of the OAuth 2.0 standard. You do not need to have specific knowledge about OIDC standard, but you can find out further details via these official pages or via this tutorial.

Step 1: Request the OAuth authorization code from the user

This is the first step in your client application. You need to let the user authenticate himself/herself in order to be able to access his/her data. Once done, your client application will be able to make calls to our APIs.

To authenticate the end-user and obtain his/her consent, a GET request must be sent to the authorization endpoint by adding the following mandatory parameters:

scope (required): the API scope your client application needs. It tells the Authorization endpoint what kind of permissions to ask for when displaying the consent form to the end-user. Use space as separator if more than one value.

redirect_uri (required): the callback URL you provided for your client application during registration. Note that it is mandatory for security reasons.

state (required): a free parameter you can use to set some data. This field will be sent back in the state query-string parameter when redirecting to your callback URL.

Additional optional parameters can be added to the Authorization request:

prompt (optional): you can set this parameter in case you want to force the login and/or the consent page display. It can be useful if for example, your terms have changed and you want the end-user to revalidate the consent page. Multiple values must be separated by a url-encoded space (%20). Possible values:

none: no UI will be displayed. If the end-user is already authenticated and consent has been accepted, the redirection to your callback URL is done with a valid code parameter. If the end-user is not authenticated, or consent is needed, the redirection to your callback URL is done with a login_required error. It can be useful to silently check existing authentication or consent.

login: force the connection page display. If the end-user is already authenticated, a page will ask him to confirm the use of his identity to proceed further.

consent: force the consent page display. If the end-user is not already authenticated, the login form is displayed first.

display (optional): string value to specify the user interface display for the Authentication and Consent flow. The values can be:

page: default value, if the display parameter is not added. The UI should be consistent with a full page view of the User-Agent.

popup: the popup window should be 450px X 500px [wide X tall].

touch: the Authorisation Server should display the UI consistent with a ‘touch’ based interface.

wap: The UI should be consistent with a ‘feature-phone’ device display.

nonce (optional): String value used to associate a client session with the ID Token. It is passed unmodified from Authorisation request to ID Token. The value should be unique per session to mitigate replay attacks.

ui_locales (optional): space separated list of user preferred languages and scripts for the UI as per RFC5646.

login_hint (optional): an indication to the IDP/Authorisation Server on what ID to use for login, e.g. emailid, MSISDN (phone_number), etc.

acr_values (optional): Authentication Context class Reference. The acr_values are an indication of the authentication method to be used by the Identity provider (IDP). The authentication methods to be used are linked to the LOA (Level Of Assurance) value passed in the acr_values. The IDP configures the authentication method selection logic based on the acr_values. Space separated string that specifies the LOA values to be used during authentication processing. The values appear in order of preference. The recommended values are the LOAs as specified in ISO/IEC 29115 Clause 6.

At the end, you need to access the following URL in a Web browser or in a toolkit WebView:

NOTE: When using end-user’s semi-implicit authentication on mobile, you need to request the following Authorization endpoint using HTTP protocol. As an example:

http://openid.orange.fr/oidc/authorize?scope=openid\

&response_type=code\

&client_id=6KRHymujFP8s...j2k1Ee6a8SG2g\

&state=upToYouData\

&redirect_uri=https%3A%2F%2Fwww.myserver.com\

&charset=utf8

NOTE: Remember that you need to specify the client_id and redirect_uri values you got or provided during the registration process.
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”)

The access_token is mandatory for API calls to protected resources. Additional tokens may be issued by the Orange Authorization Server if requested using suitable scope. To get these tokens, a POST request must be sent to the token endpoint by adding the following parameters using the “application/x-www-form-urlencoded” format:

NOTE: The access_token is valid for the duration, in seconds, specified by expires_in. Therefore, you do not need to request a new access_token as your client application doesn’t receive an error indicating that your access token expired.

Authorization by refresh token

Refreshing an OAuth access token

If our Authorization server have issued a refresh token to your client application, and if you need a new access_token for your client application, a POST request must be sent to the token endpoint by adding the following parameters using the “application/x-www-form-urlencoded” format:

authorization_header (required): the credentials of your client application (i.e. client_id/client_secret). See Before starting section for further details.

scope (optional): the requested scope (if omitted, it is treated as equal to the scope originally granted when the refresh token was issued ; if included with an invalid scope, the scope that have been originally granted by the end-user is returned).

The end-user removed the authorizations for your client application. As an example:

HTTP/1.1401 Unauthorized

Content-Type: application/json

{

"code": 41,

"message": "Invalid credentials",

"description": "no consent has been found"

}

You cancelled your subscription to the API so that the capability to generate an access_token is no longer allowed. As an example:

HTTP/1.1403 Forbidden

Content-Type: application/json

{

"code": 50,

"message": "Access Denied",

"description": "The application that makes the request is not authorized to access this endpoint (ex: not a subscribed service)."

}

Orange administrators have suspended your access (as a consequence of the non-fulfilment of conditions of use for example).

List of errors

When calling the Authorize endpoint

If an error occurs due to a missing or invalid client identifier or if the redirect URL is invalid, the Orange Authorization Server will display a generic error page (HTML page). As an example:

In any other error cases, the Orange Authorization Server will redirect the end-user back to the provided “redirect_uri” (HTTP 302 redirection) with the following query-string parameters (each parameter value being URL encoded):

error: The error type:

access_denied: the end-user cancelled the consent form.

consent_required: the user has never accepted the Terms Of Service, you have to send the request again without prompt=none so the UI sequence is processed.

invalid_scope: the given scope does not match the known one, or scope value cannot be understood.

invalid_request: a required parameter is missing in the request, or a parameter value is unknown.

login_required: the user is not authenticated; you have to send the request again without prompt=none so the UI sequence is processed.

server_error: an internal server error occurred and the request can not be fulfilled.

temporarily_unavailable: the request could not be currently handled.

error_description: a brief description of the error. Typical example: consent%20denied in the case the end-user did not give their consent to your client application for the required operations (as set in the scope query-string parameter).

state: the value you gave in the Authorization request (state parameter).

The authorization server encountered an unexpected condition that prevented it from fulfilling the request

When calling the Token endpoint

Below is a list of errors (non exhaustive) that your client application can get when calling the token endpoint of the Orange Authorization Server.

The following list of errors fully complies with OAuth 2.0 specification. See [OAUTH] for further details.

HTTP Status

Error (mandatory)

Error description (optional)

400

invalid_request

The URI does not support the requested method

400

invalid_request

The requested URI or the requested resource does not exist

400

invalid_request

One or more required query-string parameters are missing

400

invalid_request

Syntax error

400

invalid_grant

The parameter grant_type is not valid

400

invalid_grant

Invalid authorization code

400

invalid_grant

Invalid redirect_uri

400

invalid_grant

The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client

400

unauthorized_client

The application that makes the request is not authorized to access this endpoint (ex: not a subscribed service)

401

invalid_client

The requested service needs credentials, but none were provided

401

invalid_client

The requested service needs credentials, but the ones provided were invalid

401

invalid_client

The requested service needs credentials, and the ones provided were out-of-date

401

invalid_client

Client not found

As an example:

HTTP/1.1400 Bad Request

Content-Type: application/json

{

"error": "invalid_request",

"error_description": "missing redirect_uri parameter"

}

Common errors

Additional errors may occur when requesting our APIs. For instance, when the rate limit defined for an API is exceeded.

In that case, you should receive JSON payload similar to:

As an example:

HTTP/1.1403 Forbidden

Content-Type: application/json

{

"code": 53,

"message": "Too Many Requests",

"description": "The application has made too many calls and has exceeded the rate limit for this service."