Introduction to OAuth 2.0 protocol

OAuth 2.0 defines a protocol for securing application access to protected resources, which are accessed through REST APIs. OAuth 2.0 relies on access tokens presented by client applications (on behalf of end-users or not) when requesting access to protected resources via APIs. These tokens must be obtained before the client application can get access to these resources.

Generally speaking, an access token contains a set of attributes and policies that relate to both the client application and the end-user, and these attributes are used for making authorization decisions at runtime.

The OAuth 2.0 protocol supports several grant types for different use cases.

This informational guide provides an overview of OAuth 2.0 roles, authorization grant types and flows.

The OAuth 2.0 protocol defines the following 4 distinct roles:

• `Resource Owner`: the holder of the data (usually the end-user).
• `Resource Server`: the resource server providing access to the protected data.
• `Client Application`: the client application requesting data towards the resource server (i.e. your web or mobile application for example).
• `Authorization Server`: the authorization server, which delivers to the client application, depending on grant type, the token(s) that are required to access a protected resource.

The tokens are strings generated by the authorization server, and issued when the client application requests it.

There are 3 types of tokens:

• `Access Token`: the access token allows a client application to get access to data managed by the resource server (within the context of a specific user or not). This bearer token is sent by the client application in the request (header part) to the resource server.
• `Refresh Token`: the refresh token is issued simultaneously with the access token (for Authorization Code grant type only). It is sent to the authorization server when the access token has expired.
• `ID Token`: in case OpenID Connect is used (i.e. the ‘openid’ scope is present in the authorization request), the server response to the authorization request includes an additional parameter: `id_token`. This parameter represents a secure identification token that contains information about the authentication of the end-user. It is formatted as a JSON Web Token.

Scopes provide a mechanism for grouping attributes, making these attribute groupings available for client applications to fulfil a particular purpose – for instance, Form Fill for a user registration to a service, and providing a simple mechanism for the end-user to consent for the group of attributes to be shared,

The scope limits the rights of the access token. The list of all available scopes is maintained at the Orange Authorization Server level. As an example:

• `openid`: grants access to ID token with end-user’s identifier for Single-Sign-On (SSO).
• `profile`: grants read access to user profile data (i.e. the display name).
• `cloud`: grants read and write access to end-user’s Cloud (limited to the application’s folder).

> **NOTE:** The scope value `openid` is mandatory to indicate that the request is an OpenID Connect request. The `profile` scope value is related to the UserInfo request.

Your application will be granted with the scopes allowed by the APIs you’ve subscribed to. All or part of these scope(s) can be used when making an authorization request. In any case, the end-user will keep control and give consent or not to all or part of the requested scope(s). This is referred to as validated scope(s).

See [OAUTH] (section 3.3) for further details.

The OAuth 2.0 protocol supports several “grant types” for different use cases.

The four grant types defined are:

• `Client credentials` (aka “two-legged OAuth”): this grant type is used to obtain access tokens for application-only authentication. See [Client Credentials flow](#client-credentials-flow) for further details.
• `Authorization code` (aka “three-legged OAuth”): this grant type is used to obtain both access tokens and refresh tokens and is optimized for confidential client applications. Since this is a redirection-based flow, the client application must be capable of interacting with the resource owner’s user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the authorization server. See [Authorization Code flow](#authorization-code-flow) for further details.
• `Implicit`: the implicit grant type is used to obtain access tokens (it does not support the issuance of refresh tokens) and is optimized for public clients known to operate a particular redirection URI. These clients are typically implemented in a browser using a scripting language such as JavaScript.
  NOTE: this grant type is currently not supported by our Orange Authorization Server.
• `Resource Owner Password Credentials`: The resource owner password credentials grant type is suitable in cases where the resource owner has a trust relationship with the client, such as the device operating system or a highly privileged application. The authorization server should take special care when enabling this grant type and only allow it when other flows are not viable. This grant type is suitable for clients capable of obtaining the resource owner’s credentials (username and password, typically using an interactive form).
  NOTE: this grant type is currently not supported by our Orange Authorization Server.

On Orange Developer, the access to APIs is protected using OAuth 2.0 protocols: when requesting an API on its consumption URL endpoint, you need to present a valid OAuth 2.0 access token. These tokens are to be negotiated on a specific /oauth resource path (see below) on the same URL (FQDN) of the API you want to access.

The list below presents some real-life curl requests, highlighting examples of OAuth 2.0 token negotiation for APIs published on the api.orange.com FQDN. Be aware that these requests are only examples – the API you subscribed to may be published on a different FQDN. Check the documentation applicable to your specific API offer to find out the proper FQDN to be used in your case.

• Default access:
  1-way https://api.orange.com
  OB(*): https://ope-obs.apibackbone.orange.com
• Available on some APIs that offer mutual authentication
  2-way https://api-ma.orange.com
  OB(*): https://ope-obs-ma.apibackbone.orange.com

(*): specific FQDNs for some APIs provided by Orange Business (OB)

The Client Credentials OAuth flow consists of the following steps:

1. As a prerequisite, developers sign up on the Orange Developer portal, then register a new client application. They get back a Client ID and a Client secret.
2. The client application makes a POST request to the token endpoint to exchange these credentials for an OAuth bearer token.
3. When requesting an API, the client application must provide the bearer token that will be validated by our Orange Authorization Server. If the access token expires, a specific error will be returned by our Orange Authorization Server. A new access token must therefore be requested using the refresh token.

Read OAuth M2M in a nutshell provided with sample codes.

The Authorization Code OAuth flow follows the following steps:

1. As a prerequisite, the developers sign up on the Orange Developer portal, then register a new client application. They get back a Client ID and a Client secret.
2. The client application makes a GET request to the authorize endpoint in order to authenticate the end-user and obtain its consent.
3. If not already authenticated, this end-user is redirected to a login page of the Orange Identity provider. The end-user is then requested to give its consent to the client application for the requested scope.
4. When requesting an API, the client application must provide the bearer token that will be validated by our Orange Authorization Server.
5. If the access token is expired, a specific error will be returned by our Orange Authorization Server. A new access token must therefore be requested using the refresh token.

Read OAuth U2M in a nutshell provided with code samples.

[OAUTH] D. Hardt, “The OAuth 2.0 Authorization Framework” RFC 6749, October 2012.

[JWT] Wikipedia, “JSON Web Token”