OAuth 2.0
As an authorization server, PingGateway authenticates resource owners and obtains their authorization to return access tokens to clients.
Before you configure OAuth 2.0 in your environment, familiarize yourself with the OAuth 2.0 authorization framework and related standards.
OAuth 2.0 concepts
RFC 6749, the OAuth 2.0 authorization framework lets a third-party application obtain limited access to a resource (usually user data) on behalf of the resource owner or the application itself.
The main actors in the OAuth 2.0 authorization framework are the following:
| Actor | Description |
|---|---|
Resource owner (RO) |
The owner of the resource. For example, a user who stores their photos in a photo-sharing service. The resource owner uses a user-agent, usually a web-browser, to communicate with the client. |
Client |
The third-party application that wants to access the resource. The client makes requests on behalf of the resource owner and with their authorization. For example, a printing service that needs to access the resource owner’s photos to print them. Learn more from PingGateway as an OAuth 2.0 client. |
Authorization server (AS) |
The authorization service that authenticates the resource owner and/or the client, issues access tokens to the client, and tracks their validity. Access tokens prove that the resource owner authorizes the client to act on their behalf over specific resources for a limited period of time. PingOne Advanced Identity Cloud or PingAM can act as an authorization server. |
Resource server (RS) |
The service hosting the protected resources. For example, a photo-sharing service. The resource server must be able to validate the tokens issued by the authorization server. Learn more from PingGateway as an OAuth 2.0 resource server. |
PingGateway as an OAuth 2.0 client
PingGateway as an OAuth 2.0 client supports the OAuth 2.0 filters and flows in the following table:
| Filter | OAuth 2.0 flow | Description |
|---|---|---|
(previously named OAuth2ClientFilter) |
This filter requires the user agent to authorize the request interactively to obtain an access token and optional ID token. The access token is maintained only for the OAuth 2.0 session, and is valid only for the configured scopes. This filter can act as an OpenID Connect relying party or as an OAuth 2.0 client. Use for Web applications running on a server. |
|
According to information in the The OAuth 2.0 Authorization Framework, minimize use of this grant type and use other grant types when possible. This filter supports the transformation of client credentials and user credentials to obtain an access token from the Authorization Server. It injects the access token into the inbound request as a Bearer Authorization header. The access token is valid only for the configured scopes. Use for clients trusted with the resource owner credentials. |
||
This filter is similar to the Resource Owner Password Credentials grant type, but the resource owner is not part of the flow and the client accesses only information relevant to itself. Use when the client is the resource owner, or the client doesn’t act on behalf of the resource owner. |
PingGateway as an OAuth 2.0 resource server
The following image illustrates the steps for a client application to access a user’s protected resources, with AM as the Authorization Server and PingGateway as the resource server:
-
The application obtains an authorization grant, representing the resource owner’s consent. Learn more about the different OAuth 2.0 grant mechanisms supported by AM in the AM documentation on OAuth 2.0 grant flows.
-
The application authenticates to the Authorization Server and requests an access token. The Authorization Server returns an access token to the application.
An OAuth 2.0 access token is an opaque string issued by the authorization server. When the client interacts with the resource server, the client presents the access token in the
Authorizationheader. For example:Authorization: Bearer 7af...da9Access tokens are the credentials to access protected resources. The advantage of access tokens over passwords or other credentials is that access tokens can be granted and revoked without exposing the user’s credentials.
The access token represents the authorization to access protected resources. Because an access token is a bearer token, anyone who has the access token can use it to get the resources. Access tokens must therefore be protected, so that requests involving them go over HTTPS.
In OAuth 2.0, the token scopes are strings that identify the scope of access authorized to the client, but can also be used for other purposes.
-
The application supplies the access token to the resource server, which then resolves and validates the access token by using an access token resolver, as described in Access token resolvers.
If the access token is valid, the resource server permits the client access to the requested resource.
The OAuth2ResourceServerFilter grants access to a resource by using an OAuth 2.0 access token from the HTTP Authorization header of a request.
When auditing is enabled, OAuth 2.0 token tracking IDs can be logged in access audit events for routes that contain an OAuth2ResourceServerFilter. Learn more in Audit the deployment and Audit framework.