OAuth 2.0
The Open Authorization (OAuth) 2.0 is a flexible authorization framework for securing application access to protected resources of APIs. OAuth 2.0 uses access tokens that are presented by client applications (on behalf of the end users) to access the protected resources.
The OAuth 2.0 authorization framework includes the following terms:
OAuth 2.0 Roles
Resource Owner (or the End User):
This is the holder of the protected resources that the client application needs to access. The resource owner is typically a person (usually the end user), but could also be an application.
Client Application (or the Client):
This is the application that is requesting access to protected resources on behalf of the end user.
Resource Server (or API Gateway):
This is the server that stores the protected resources the application is trying to access. API Gateway acts as a resource server.
Authorization Server (OAuth 2.0):
This is the server that acts as an interface between the client application and end user, authenticates the end user, and issues access tokens after proper authorization. API Gateway can be configured to act as an OAuth 2.0 authorization server. You can configure API Gateway for use with a third-party OAuth 2.0 authorization server, such as PingFederate.
OAuth 2.0 Scopes
OAuth 2.0 scopes are used to limit the amount of access that is granted to a client by the resource owner. Scope defines a single resource or a collection of resources to which a client application may request access to. When an API is created, and defined with one or more scopes, the corresponding OAuth 2.0 scopes are created in API Gateway. When requesting access tokens to access the protected resources in API Gateway, the client should pass the OAuth 2.0 scope in the same request, if required by the OAuth 2.0 provider.
OAuth 2.0 Authorization Grant Types
Authorization Code:
This is the grant type used to obtain access tokens (and optionally refresh tokens) and is optimized for confidential clients.
Implicit:
This is the grant type used to obtain access tokens and is optimized for public clients. It does not support the issuance of refresh tokens.
Client Credentials:
This is the grant type used to obtain access tokens for client-only authentication.
Resource Owner Password Credentials:
This is the grant type used to obtain access tokens when the resource owner has a trust relationship with the client, and clients are capable of obtaining the resource owner's credentials.
Note: The Resource Owner Password Credentials grant type is currently not supported by API Gateway.
OAuth 2.0 Clients
Confidential:
This is a client that supplies a client ID and client secret to the authorization server to obtain access tokens (and optionally refresh tokens). These clients hold a user account on the authorization server. If a client does not have the proper credentials (client ID and secret) for the user account, the authorization server does not grant the client an access token.
Public:
This is a client that uses only a client ID for identification, with no other credentials, to obtain access token. These clients are typically implemented in a browser using a scripting language such as JavaScript.
OAuth 2.0 Endpoints
Authorize Endpoint:
This is the endpoint that allows the client to authenticate with the authorization server. This endpoint is applicable for Authorization Code grant type only.
Token Endpoint:
This is the endpoint that allows the client to get an access token (and optionally refresh token) from the authorization server. Refresh token is applicable for Authorization Code grant type only.
OAuth 2.0 Tokens
Access Token:
This is the token that allows the client to access protected resources on the resource server.
Refresh Token:
This is the token that allows the client to obtain a renewed access token when the existing access token has expired. This token is applicable for Authorization Code grant type only.
OAuth 2.0 Flow
The protected resources are stored on a Resource Server and the owner of the resources, Resource Owner, (usually the End User), grants the Client Application permission to access them. When a resource owner grants permission, the OAuth 2.0 Authorization Server issues an Access Token, depending on grant type, to the Client Application. When the Client Application passes the access token to the Resource Server, the Resource Server communicates with the Authorization Server to validate the token and, and if valid, provides access to the resources. If the access token is expired, the Client Application uses the Refresh Token to request a new access token. The Authorization Server returns a new access token.
Example: OAuth 2.0 Flow
In the example, David is the End User (Resource Owner) who wants to access and print his photos stored on the Online PhotoStorage Album (Resource Server) using the Online PhotoPrint Shop (Client Application). PhotoPrint supplies David with an application that runs on his personal device (for example, phone). David uses that application to initiate the process. PhotoPrint sends a request to the PhotoStorage through the OAuth 2.0 Authorization Server. The OAuth 2.0 Authorization Server requests authorization from David and issues a token to PhotoPrint. PhotoPrint can then access David's photos on PhotoStorage.
An in-depth description of OAuth is beyond the scope of this guide but is available elsewhere.