52.2 Understanding OAuth Services Authorization for Web Clients

In the most common OAuth scenario, the Client accessing the protected resource is issued a different set of credentials than those of the user. (In this case, the user does not disclose their credentials to the client.) Oracle Access Management OAuth Services acts as the intermediary Authorization Server, interacting directly with the Client, the service hosting the user's protected resource (Resource Owner) and the server on which the resource is located (Resource Server).

It issues access tokens to a Client that has (already) successfully authenticated with the Resource Server - in effect, authorizing the client to access private resources or activities on the server. A single Authorization Server instance can issue access tokens accepted by multiple resource servers.

Note:

OAuth does not impose special requirements on the interaction between a Resource Server and an Authorization Server.

The following sections describe web-based scenarios in which OAuth Services works.

The scenarios introduce the concept of OAuth Services endpoints. For detailed information on these endpoints, see Understanding the Authorization and Authentication Endpoints. The scenarios also use terms documented in Understanding the OAuth Services Components including the following:

The Resource Owner refers to the user requesting access to a protected resource.
The Client is the mobile app or Web service through which the Resource Owner is requesting access to a protected resource.
OAuth Services refers to the Authorization Server, Oracle Access Management.
The Resource Server is the machine on which the protected resource is stored. It can be any website or Web service where restricted resources are located; for example, a photo sharing site, a blogging platform and an online bank service control access to private resources and activities. The Resource Server is deployed in a different location from Oracle Access Management and the Client. The Resource Server needs to be capable of accepting and responding to protected resource requests using access tokens. The Resource Server must also validate the access token with OAuth Services as described in Enforcing Access Control.

52.2.1 Understanding 3-Legged Authorization

In 3-legged authorization, the Resource Owner grants access to an OAuth-enabled Client to request access to resources stored on an OAuth protected Resource Server.

Oracle Access Management OAuth Services validates the Resource Owner's identity and presents the owner with a consent form in a Web browser when approval is required. The third leg in this authorization scheme is the step in which the user grants or denies the client access. The following text has more details and Figure 52-1 illustrates the process.

Note:

A WebGate proxy is required to use 3-legged authorization with an external LDAP directory server. See Configuring a WebGate to Protect OAuth Services for details.

The Resource Owner (user) undertakes an action in the user-agent (a browser, for example) that requires the Client web service (or app) to access protected resources belonging to the user on a different site.
The Client initiates the OAuth flow by invoking the OAuth Services authorization endpoint to get a request token. The Client sends its identifier, the requested scope, and a redirection URI to which the Authorization Server will direct the user-agent once access is granted or denied.
OAuth Services redirects the user-agent to request the Resource Owner's password credentials.
Access Manager displays a login page requesting a user name and password from the Resource Owner. OAuth Services supports all authentication schemes provided by Access Manager.
The Resource Owner enters a user name and password.
Access Manager validates the credentials, returns a request token and redirects the user-agent to OAuth Services.
OAuth Services determines that the Resource Server requires the user's consent before the authorization code can be sent to the Client.
OAuth Services displays the user consent form.

Web-based clients require the consent form to be protected by a WebGate.For details, see Configuring a WebGate to Protect OAuth Services.
The user approves the request.
OAuth Services returns an authorization code to the Client using the redirection URI.

Note:

The Authorization Code grant type is required for 3-legged authorization. See Clients - Identity Federation and OAuth Services for details.
The Client sends the authorization code in a POST request (including the redirection URI used to obtain the authorization code for verification) to the token endpoint and requests an OAuth access token. When making the request, the Client authenticates with OAuth Services.
If the client type requires client credentials, the OAuth Services authenticates the client credentials, validates the authorization code, and ensures that the redirection URI received matches the URI previously used to return the authorization code. OAuth Services also validates the requested scope based on the Resource Server's configuration and the user's consent details.
OAuth Services returns an access token to the Client.

A refresh token may also be returned with the access token if the client sends a refresh token request. For more information, see About OAuth Services Tokens.
The Client presents the access token to the Resource Server.
The Resource Server validates the access token by sending a request to the OAuth Services token endpoint and waits for a success or failure response.
OAuth Services validates and sends the token success or failure response back to the Resource Server.
If the token is deemed valid, the Resource Server returns the requested resource to the Client.

Figure 52-1 OAuth 3-Legged Flow Diagram

Description of "Figure 52-1 OAuth 3-Legged Flow Diagram"

52.2.2 Understanding 2-Legged Authorization

In 2-legged authorization, the OAuth Client is pre-approved to access resources; thus, the user consent form step (described in Understanding 3-Legged Authorization) is not required. In this scenario, Access Manager returns a request token to the Client which the client sends to OAuth Services to request an access token. Because the request token is pre-authorized, OAuth token service returns an access token to the Client without displaying the consent form. This arrangement fits a service-to-service model, especially when the requesting service (Client) and the Resource Server are in a close partnership and Resource Owner approval is either assumed or not required.

Note:

The Client Credentials grant type or the Resource Owner Credentials grant type are required for 2-legged authorization. See Configuring Clients for more information.