Understanding OAuth Services

34.1 About Oracle Access Management OAuth Services

OAuth is an open standard authorization protocol that provides authentication and access control between a Client (such as Web services) and a Resource Owner (or Service Provider) on the Web.

Oracle Access Management OAuth Services is based on this standard and designed:

To address enterprise-level extranet use cases.
To provide secure access to APIs.
To leverage built-in Oracle Access Management features (including authentication schemes, strong authentication, fraud detection, session management and federated authentication).
To secure confidential clients with a high level of security.

Oracle Access Management OAuth Services are available for Web clients. OAuth Services for Web clients implement the standard OAuth 2.0 use cases. In this case, the clients rely on a Client ID/Client Password (or secret) to secure itself. For an example, see http://tools.ietf.org/html/rfc6749#page-4.

34.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. The scenarios also use the following terms:

The Resource Owner is an entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user.
The Client is an application making protected resource requests on behalf of the resource owner and with its authorization.
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.

34.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 34-1 illustrates the process.

Note:

A WebGate proxy is required to use 3-legged authorization with an external LDAP directory server.

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.
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 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 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 34-1 OAuth 3-Legged Flow Diagram

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

34.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 an access token to the Client based on the requested grant type and the client credentials. Since the client is already registered to request for specific scopes, OAuth Server 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 Creating a Client for more information.

34.3 Understanding the OAuth Services Components

The following sections contain information about the Identity Domains configuration options. See Configuring OAuth Services in 12c for details on configuring these components.

34.3.1 Identity Domains

Identity Domains are entities that contain all artifacts required to provide standard OAuth Services .

Each Identity Domain is an independent entity. One of the primary use cases of the Identity Domain is for multi tenants deployments. Each Identity Domain will correspond to a tenant. This can apply to different departments in an organization if there is a need for independence. This will also be useful for cloud deployments where each Identity Domain can correspond to a separate tenant or entity. The following artifacts are just some of the components configured within an OAuth Services Identity Domain.

One or more Clients
One or more Resource Servers

For information on configuring Identity Domains, See Creating an Identity Domain.

34.3.2 Clients

The Client initiates the OAuth protocol by invoking the OAuth Services.

Client profiles must be created before the protocol can be initiated. At a minimum, client profiles include the application name, a client ID, and one or more URIs to which OAuth Services will redirect the user-agent once access is granted or denied. Clients may be public or confidential.

Web clients are a type of confidential client, assigned with a client ID and secret. These clients can interact with the OAuth Services server by sending the client ID and secret as part of an authorization header. It is up to each individual client to determine how the secret issued to them is securely stored.
Public clients are assigned with a client ID but no secret. Typically these profiles pertain to browser based applications like Javascript or can be mobile based apps.

The client ID and secret are explained in the following bullet points.

The Client ID is a unique string that represents the registration information and is required for each client. You can create a unique client ID or have OAuth Services generate one. OAuth Services compares the defined Client ID with the value the client sends over HTTPS or HTTP as part of an authorization request. If the values do not match, the request is rejected. Client IDs are Base64 encoded when they are sent as authorization header.
The Client secret is the client password. You can create a unique client secret or have OAuth Services generate one. Web clients are required to have a Client ID and a Client secret. Public clients, on the other hand, do not have a client secret and are given only a Client ID.

To request an access token, the client obtains authorization from the resource owner. The authorization is expressed in the form of an authorization grant, which the client uses to request the access token.The OAuth 2.0 specification provides authorization grant types for different security use cases. OAuth Services has implemented some of these grant types. Web and Public Clients can access the various OAuth Services grant types that are appropriate to them. The following grant types are supported by OAuth Services.

Note:

(For general information about the OAuth specification grant types, see http://tools.ietf.org/html/rfc6749#section-1.3.

Authorization Code - The Resource Owner logs in using Oracle Access Management. The token endpoint exchanges the authorization code along with client credentials for an access token. The Authorization Code grant type is required for 3-legged flows.
Resource Owner Credentials - The Resource Owner provides the client with a user name and password. This is only suitable for highly trusted client applications because the client could abuse the password, or the password could unintentionally be disclosed to an attacker. Per the OAuth 2.0 specification, the authorization server and client should minimize use of this grant type and utilize other grant types whenever possible. The Resource Owner Credentials grant type is required for 2-legged authorization scenarios.
Client Credentials – The client requests an access token using only its client credentials (or another supported means of authentication). This is suitable if the client is requesting access to protected resources under its control, or those of another resource owner when previously arranged with the authorization server. The Client Credentials grant type is required for 2-legged authorization scenarios.
Refresh Token - Select this option to return a refresh token together with an access token in the token response. See About OAuth Tokens for more information.
JWT Bearer - Allows a JWT assertion to be used to request an OAuth Services access token.

Allowed Scopes can also be configured on a client by client basis. OAuth Services allows for the configuration of scopes to bypass the need for user consent. For information on configuring Clients, see Creating a Client.

34.4 About OAuth Tokens

OAuth generates two types of tokens namely, Access Tokens and Refresh tokens.

Access tokens carry the necessary information to access a resource directly. In other words, when a client passes an access token to a server managing a resource, that server can use the information contained in the token to decide whether the client is authorized or not. Access tokens usually have an expiration date and are short-lived.

Refresh tokens carry the information necessary to get a new access token. In other words, whenever an access token is required to access a specific resource, a client may use a refresh token to get a new access token issued by the authentication server. Common use cases include getting new access tokens after old ones have expired, or getting access to a new resource for the first time. Refresh tokens can also expire but are rather long-lived.. The following sections contain additional details.

34.4.1 OAuth Access Tokens

Before the user accesses the protected resource, the client service provider authenticates with OAuth Services and requests the Token Endpoint for an OAuth Access Token.

If OAuth Services determines that a user must consent to the request for access to a protected resource, a consent form is displayed. After the user consents, OAuth Services returns an authorization code to the Client service provider. The Client then sends the authorization code to the Token Endpoint and requests an OAuth Services Access Token. (When making the request, the Client authenticates with OAuth Services.) If received, the Access Token allows access to the protected resources.

Oracle Access Management can embed custom attributes in Access Tokens. Custom attributes are configured as part of the Client Profile or the Custom Resource Server. They are defined as static or dynamic.

Static Attributes - Attribute name and value pairs where the value is fixed at the time that you define the attribute. For example, name1=value1.

Dynamic Attributes - User-profile specific attributes. For example:

 $session.id, 
{"attrName":"sessionId",
"attrValue":"$session.id",
"attrType":"DYNAMIC"
}

Creating a Resource and Creating a Client contain more information. Keep the following guidelines in mind when configuring custom attributes:

Do not use the same name for a static and dynamic attribute.
Avoid using the same name when adding custom attributes to the service profile configuration and the scope configuration. If you define the same attribute name in both locations, the scope-based attribute value takes precedence.

Custom attributes appear as claims in access tokens. JWT-based access tokens contain standard JWT claims along with OAuth Services specific ones. For example:

Standard

"exp":1357596398000,
"iat":1357589198000,
"aud":"oam_server1",
"iss":"OAuthServiceProfile",
"prn":null,
"jti":"340c8324-e49f-43cb-ba95-837eb419e068",

OAuth Services Specific

"oracle.oauth.user_origin_id":"john101",
"oracle.oauth.user_origin_id_type":"LDAP_UID",
"oracle:idm:claims:client:macaddress":"1C:AB:A7:A5:F0:DC",
"oracle.oauth.scope":"brokerage",
"oracle.oauth.client_origin_id":"oauthssoapp1id",
"oracle.oauth.grant_type":"oracle-idm:/oauth/grant-type/resource-access-token/jwt"

These claims are available as part of the access token generated by OAuth Services. Because the custom attributes appear as claims in a JWT-based access token, the following naming restrictions apply:

Avoid JWT standard claim names.
Avoid names with an "Oracle" prefix (as shown above)

34.4.2 OAuth Refresh Tokens

OAuth Services can be configured to allow the Client to use a refresh token to obtain additional access tokens with identical or narrower scope.

The refresh token is used when the access token is no longer valid. The purpose of a refresh token is to improve security. Access tokens are short-lived, so if stolen, they are only useful for a limited period. Refresh tokens are longer-lived, but are less frequently sent to the server, thus reducing the likelihood that they will be stolen.

Refresh tokens are generated only for Resource Owner Credentials and Authorization code flow. This is also controlled by the tokenSettings configuration in the IdentityDomain.