OAuth 2.0

SaaS On-premises 2.0
OAuth 2.0 framework provides different authorization grant types that are specifically tailored for different scenarios and application types. It enables a 3rd party application to obtain limited access to a resource, either on behalf of a resource owner or its own behalf.

At 3scale we support the following OAuth 2.0 flows for:

  • Client Credentials
  • Resource Owner Password
  • Client-Side Web Applications (AKA Implicit)
  • Server-Side Web Application (AKA Authorization Code)

These flows typically (though not always) have a number of players involved:

  • Resource Server (provider/API)
  • Client (buyer/developer/application)
  • Resource Owner (end user)
  • Auth Server (NGINX + 3scale cloud Service and/or API Provider's own Auth Server)

There are typically 2 actions that need to be done when accessing an OAuth protected API endpoint

  1. Requesting an access token from the Authorization Server
  2. Using the access token to access the API endpoint

Depending on the longevity of the access token, the first step might only need to be done once (for non-expiring tokens.)

How these access token is requested can vary based on the OAuth 2.0 flow and its implementation. We will outline the different flows below and the basic implementation for these at 3scale.

For instructions on how to set these up in NGINX, please visit the OAuth with APIcast section in the API Configuration Page. To set up ActiveDocs with OAuth, please visit ActiveDocs and OAuth section in the API Configuration Page.

Client Credentials Flow

The Client Credentials flow is the simplest of the flows. It is used to grant authorization in the case where the protected resources are already under the control of the client or when access to the resource has already been previously granted through some other means. The main players involved in the access token request step would therefore be the Client and the Authorization Server.

Once an access_token is issued, the Client will call the API using this access token instead of their credentials (client_id and client_secret.)

Regarding Resource Owner Authentication

For the next few workflows, when there is a Resource Owner/End User involved, there will be an extra player involved in the grant workflows. As the NGINX API Gateway does not hold any user details, it will need to delegate user authentication whilst still generating and managing the access tokens for a Client.

This means that in effect there are 2 Auth Servers: NGINX API Gateway to Authorize and Authenticate the Client and API Authentication Server for the Resource Owner.

Resource Owner Password Credentials Flow

The Resource Owner flow is the next step up from the client credentials flow in terms of simplicity. It allows the application to exchange the resource owner's username and password for an access token. As such, the user's password is accessible to the Client and therefore it should only be used when the Client is highly trusted by the resource owner e.g the Twitter mobile app accessing the Twitter API.

Since 3scale does not hold and/or store the end user credentials, these will need to be checked against another Authorization Server or the Resource Server itself. In this case there are 2 sets of validations performed:

  • Are the Client credentials to request the access token valid?
  • Are the Resource Owner credentials to access the Resource Server valid?
In this case, the Resource Owner and Resource Server are both involved in the access token request as they need to provide (in the case of the RO) and validate (in the case of the RS) the credentials sent to the Client for exchange with the Authorization Server. Additionally, the Resource Server will need to validate the RO credentials are valid and either generate the access token or prompt the Authorization Server to do so.

These are the typical steps involved in this flow:

  1. Resource Owner provides username and password to Client
  2. Client requests access token by calling Authorization Server with Resource Owner's username and password as well as its own client_id
  3. Authorization Server (NGINX) calls 3scale cloud Authorization Server to check client_id is valid
  4. If Client credentials are valid, NGINX requests validation of Resource Owner credentials with the Resource/Auth Server.
  5. If Resource Owner credentials are valid, Authorization Server generates and returns access_token to NGINX.
  6. NGINX sends access_token on to Client and to 3scale cloud Authorization Service for storage. This will allow subsequent requests using the access token to be associated with the correct Client without the need to send client_id and/or client_secret.

Client-Side Web Applications / Implicit Grant Flow

The Implicit Grant flow is designed for use by Clients running within a browser. It is a simplified version of the Server-Side Web Applications Flow which is optimized for efficiency of the Client by reducing the number of round trips to the Authorization server to receive an access token. As the Client runs within a browser, the access token may be available to the Resource Owner as well as any other applications that have access to the browser. Therefore this flow should be used when:

  • The browser is strongly trusted and/or there's little danger that the access token will be exposed to untrusted users/applications
  • The Resource Owner is typically logged in to the Resource Server
  • Access to the required resource is only needed temporarily
These are the typical steps involved in this flow when using NGINX/3scale to manage token storage and generation:
  1. Client requests access_token by calling API Gateway (NGINX) with credentials (client_id) and redirect uri.
  2. The API Gateway then calls 3scale Cloud Authorization Server to check credentials are valid.
  3. If credentials are valid and redirect uri matches value stored in 3scale, API Gateway redirects to OAuth login URL hosted on Authorization Server.
  4. If Resource Owner is prompted to log in (if not already done so) and asked to grant access to the Client.
  5. If Resource Owner grants access, Authorization Server calls API Gateway with the access token.
  6. API Gateway forwards on access token to Client redirect url.

Server-Side Web Applications / Authorization Code Grant Flow

This last grant type is used in the case where the Client is a web application server. It allows for an access_token for a user to be issued directly to the client, without exposing it to the user's browser and potentially other parties. Additionally as the Resource Owner is authenticated by an authorization server, her credentials are never exposed to the Client. These two features combined make this the most secure (albeit the most complicated) of all the flows.

These are the typical steps involved in this flow when using NGINX/3scale to manage token storage and generation:

  1. Client requests access_token by calling API Gateway (NGINX) with credentials (client_id) and redirect uri.
  2. The API Gateway then calls 3scale Cloud Authorization Server to check credentials are valid.
  3. If credentials are valid and redirect uri matches value stored in 3scale, API Gateway redirects to OAuth login URL hosted on Authorization Server.
  4. Resource Owner is prompted to log in (if not already done so) and asked to grant access to the Client.
  5. If Resource Owner grants access, Authorization Server calls API Gateway to inform access has been granted.
  6. API Gateway generates a temporary authorization code and forwards it on to Client redirect url.
  7. Client calls API Gateway OAuth Token endpoint with credentials and authorization code.
  8. If authorization code is valid, API Gateway generates and returns access token to Client redirect url.