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.

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.

Roles

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.

Types of tokens

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 ([JWT]).

Scopes

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.

Grant types

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 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 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.

OAuth 2.0 flows

Client Credentials flow

The Client Credentials OAuth flow follows the following steps:

1. As a prerequisite, the developer signs up on the Orange Developer portal, then registers a new client application. He gets 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 sent back by our Orange Authorization Server. A new access token must therefore be requested using the refresh token.

Read 2-Legged OAuth flow step by step with sample requests and error details.

Authorization Code flow

The Authorization Code OAuth flow follows the following steps:

1. As a prerequisite, the developer signs up on the Orange Developer portal, then registers a new client application. He gets 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 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 sent back by our Orange Authorization Server. A new access token must therefore be requested using the refresh token (if always valid).

Read 3-Legged OAuth flow step by step with sample requests and error details.

References

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