45 Understanding the OAuth Service

This chapter describes the purpose and capabilities of the OAuth Service. It includes the following topics.

• Introducing the OAuth Service

• Understanding the OAuth Service

• Understanding the OAuth Service Processes

45.1 Introducing the OAuth Service

The OAuth Service allows organizations to implement the open standard OAuth 2.0 Web authorization protocol in an Access Manager environment. OAuth enables a client to access Access Manager protected resources that belong to another user (that is, the resource owner).

45.2 Understanding the OAuth Service

The OAuth Service allows organizations to implement OAuth 2.0 in a new or existing Access Manager environment so that OAuth clients can use OAuth 2.0 flows to access resources protected by Access Manager. An OAuth client can be an application or service created and controlled by your organization, or it can be an application or service created and controlled by another organization that requires access to resources protected by Access Manager.

Note:

For information about using OAuth flows to allow users to log in to a protected resource using their credentials from cloud-based identity services, see Section 41.6.3, "Using OAuth For Access Token Retrieval."

The following sections contain more detailed information regarding the OAuth Service:

• Understanding OAuth 2.0 Roles

• Understanding the OAuth Service Components

• Understanding the OAuth Service Supported Features

• The Mobile OAuth Authorization Flow

• Understanding the OAuth Service Authorization and Authentication Endpoints

• Understanding Refresh Tokens

• Understanding the Mobile OAuth Client UI Form Factor Options

• Understanding Mobile OAuth Single Sign-on (SSO)

45.2.1 Understanding OAuth 2.0 Roles

OAuth is an open standard Web authorization protocol that has become the preferred method of providing tokenized authentication and access control between any type of client (including mobile apps and other services) and another service on the Web. The Oracle Access Management OAuth Service implements the OAuth 2.0 specification developed by the IETF OAuth Working Group.OAuth enables a client to access resources on a remote server that belong to another user (the resource owner). In the most common OAuth authorization flow, the client is issued a different set of credentials than those of the user. An intermediary authorization service interacts directly with the client and the service hosting the user's resources so the user does not disclose their credentials to the client.

The OAuth specification defines four roles:

• resource owner – A person or entity capable of granting access to a protected resource.

• resource server – The server hosting the protected resources. The resource server must be capable of accepting and responding to protected resource requests using access tokens.

• client - An application making protected resource requests on behalf of the resource owner and with the resource owner's authorization.

• authorization server – The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization. A single authorization server instance can issue access tokens accepted by multiple resource servers.

The OAuth specification does not impose any special requirements on the interaction between the resource server and the authorization server. The resource server only needs to be capable of accepting and responding to protected resource requests using access tokens.

45.2.2 Understanding the OAuth Service Components

The OAuth Service consists of the following components:

• A server component that you administer as part of Oracle Access Management. The server component, together with Access Manager, provides authorization services and the OAuth token service. The server interacts with the client, the resource owner, and the resource server. The server component is where you register clients and resource servers and manage token life-cycle management.

• A User Profile Service that supports OAuth 2.0 authorization and allows clients to interact with a back-end directory server and perform User Profile REST operations on Person, Group, and Relationship entities.

• A Consent Management Service that stores and tracks OAuth user consent responses.

45.2.3 Understanding the OAuth Service Supported Features

The OAuth Service supports 3-legged OAuth, 2-legged OAuth, and enhanced security support if the OAuth client resides on a mobile device.

3-Legged OAuth Authorization

In OAuth 3-legged authorization, the resource owner grants access to the OAuth-enabled client (the requesting site) to access resources stored on an OAuth resource server. The Oracle Access Management authorization server validates the resource owner's identity and presents the owner a consent form when approval is required. The third leg in this authentication scheme is the step in which the user grants or denies the client access.

2-Legged OAuth Authorization

In OAuth 2-legged authorization, the OAuth client is pre-approved to access resources. This arrangement fits a service-to-service model, especially when the requesting service and the resource service are in a close partnership and the resource owner approval is either assumed or not required.

Mobile OAuth

The Oracle Access Management OAuth Service provides enhanced security support if the OAuth client resides on a mobile device. This enhanced security support is in addition to the baseline security measures defined in the OAuth 2.0 specification. On a mobile device, the OAuth client must obtain a client verification code before the authorization endpoint on the OAM server will interact with the mobile app. Further, the OAM server component can restrict token delivery to a specific app installed on a specific device by sending part of a token through HTTPS, and sending the other part through push notification using either the Apple Push Notification Service (APNS) or Google Cloud Messaging (GCM). Mobile OAuth single sign-on allows multiple mobile apps on a device to share the same user session, which resides on the server, not the client.

SDK Support

SDKs for OAuth Service application development are not available in this release. This includes SDKs for Android and iOS devices, and for Java Virtual Machines (JVMs).

45.2.4 The Mobile OAuth Authorization Flow

Apps that go through a browser for mobile security use the Mobile OAuth authorization flow. In this flow the user session is created on the server and maintained in the browser with cookies. Except for access tokens, the server does not send security material, such as OAAM device and session handles and user tokens to the mobile device, but stores it in the Server-Side Device Store. Access tokens are both sent to the client and stored in the Server-Side Device Store to provide for validation and life cycle management.

Client apps that use the mobile OAuth authorization flow must be registered with the OAuth service in the OAuth identity domain that your organization uses to manage mobile OAuth clients. This flow also requires the client to obtain a pre-authorization client verification code before the server's authorization endpoint will interact with the mobile app. If enabled, the server can further ensure that it is communicating with a specific app installed on a specific device by sending part of an additional client verification code through HTTPS, and sending the other part through push notification using either the Apple Push Notification Service (APNS) or Google Cloud Messaging (GCM).

This flow supports user consent management. If consent management is enabled, the client app prompts the user to accept or decline the app's request to register with Access Manager.

Note:

Register browser-based apps that use the Mobile OAuth authorization flow under OAuth Services in the OAM console.

For a diagram that describes the Mobile OAuth authorization flow in detail, see Section 45.3.3, "Understanding Mobile OAuth Authorization."

45.2.5 Understanding the OAuth Service Authorization and Authentication Endpoints

The OAuth Service has three authentication endpoints that receive and respond to HTTPS requests: the authorization endpoint, the token endpoint, and the push endpoint. Each endpoint is an URL that clients use to make OAuth authentication requests.

• Authorization Endpoint – The client uses the authorization endpoint to get authorization from the resource owner to access the requested resources. The endpoint redirects the user agent and prompts the resource owner to log in and consent to the access request. The client application initiates the authorization endpoint request. This endpoint accepts the HTTPS request, validates the input parameters and headers (if any), appends the authorization code to the redirect URI, and finally redirects the client to the URL. The URI for this endpoint always ends in authorize. For example:

  http(s)://<host>:<port>/ms_oauth/oauth2/endpoints/<yourOauthServiceName>/authorize

• Token Endpoint – The client application interacts with the token endpoint to exchange an authorization grant or refresh token for an access token. The client uses a Refresh token to obtain a new access token. The URI for this endpoint always ends in token. For example:

  http(s)://<host>:<port>/ms_oauth/oauth2/endpoints/<yourOauthServiceName>/token

• Push Endpoint  – Mobile OAuth client apps interact with the push endpoint to obtain (depending on configuration) part of the authorization codes, and/or part of the client tokens, access tokens, and refresh tokens that are sent through either the Apple Push Notification Service (APNS) or the Google Cloud Messaging (GCM) service.

• User Consent Revocation Endpoint - Resource owners (end-users), who authenticate and authorize client applications using the browser-based authorization endpoint flow, use this endpoint to revoke their consent to client applications. For example:

  http(s)://<host>:<port>/ms_oauth/oauth2/ui/<yourOauthServiceName>/showrevokeconsent

When configuring the OAuth server, you also need to provide at least one client redirect URI where the server can return authorization credentials to the client.

• Client Redirect URIs – The OAuth server returns authorization credentials to the client using the URI specified in the request provided that it exactly matches a URI configured in the client profile.

45.2.6 Understanding Refresh Tokens

The OAuth Service can be configured to allow the client to use a refresh token to obtain additional access tokens with identical or narrower scope. The offline scope is the scope that issues an access token for a refresh token if the client is offline. The server issues a refresh token if the client requests the offline scope defined in the resource server configuration. See Section 46.4.5.3, "Understanding the OAuth Resource Servers Configuration Page" for details.

The client must also be configured to use refresh token. See Section 46.4.2.3, "Understanding the OAuth Service Profile Configuration Page" and Section 46.4.3.3, "Understanding the OAuth Web Clients Configuration Page" for information about refresh token settings.

45.2.7 Understanding the Mobile OAuth Client UI Form Factor Options

Developers in your organization can implement mobile security in a client app using an external browser or an embedded browser. This section briefly discusses the different approaches.

The External Browser Approach

In this approach the client app switches to an external browser, which executes the logic for user authentication and user consent management. A shared browser cookie maintains the user session and can be used to provide single sign-on across multiple apps. The external browser uses a typical Web single sign-on mechanism, including OAM SSO user authentication and third-party SSO user authentication. One drawback of using an external browser is the screen ”flickering” that occurs when the application context switches between the browser and the application.

The Embedded Browser Approach

This approach uses an embedded browser, which eliminates the screen flickering that occurs when the application context switches between the application and the external browser. The browser cookie, however, cannot be shared across multiple apps so the typical Web single sign-on mechanism cannot be used. Instead, OAM uses its own Web user authentication for single sign-on.

45.2.8 Understanding Mobile OAuth Single Sign-on (SSO)

Understanding OAM and Third-Party SSO User Authentication

Mobile OAuth client apps can use either OAM SSO user authentication or third-party SSO user authentication provided that the participating client apps are implemented using an external browser. Because the external browser can share its security cookie, this allows multiple mobile and Web clients to use either OAM or third-party SSO at the same time.

Understanding JWT SSO User Authentication

Embedded browsers cannot use OAM or third-party SSO user authentication if the user needs to log in to multiple apps on the same mobile device. Instead, a JWT user session token is used and single sign-on is established using device identification together with the user session. (If the ability to use multiple apps on the same mobile device is not a requirement, then either OAM SSO or third-party SSO is sufficient.)

Oracle Access Management generates a JWT user session token upon user authentication, and this token forms the basis of the single sign-on user session. The JWT user session is stored and maintained in the server-side device store, so multiple mobile client apps running on the same device can share the JWT user session token.

45.3 Understanding the OAuth Service Processes

This section details the OAuth Service concepts and transaction flows.

• Understanding OAuth 3-Legged Authorization

• Understanding OAuth 2-Legged Authorization

• Understanding Mobile OAuth Authorization

45.3.1 Understanding OAuth 3-Legged Authorization

In OAuth 3-legged authorization, the resource owner grants the client permission to access resources stored on a resource server. The authorization server validates the resource owner's identity and presents a consent form when approval is required. Figure 45-1 following the text illustrates the process.

1. The resource owner (user) undertakes an action in the user-agent (a browser, for example) that requires the client app to access protected resources on a different site that belong to the resource owner.

2. The client app initiates the OAuth flow by invoking the authorization server's authorization endpoint. The client app sends its client identifier, the requested scope, and the redirection URI to which the authorization server will direct the user-agent once access is granted or denied (see step 10).

3. Because the OAuth authorization service requires the resource owners credentials, the authorization service redirects the user-agent to request the resource owner's password credentials.

4. Access Manager displays the user login UI and asks the resource owner for a user name and password. The authorization server supports all authentication schemes provided by Access Manager.

5. The resource owner enters a user name and password.

6. Access Manager validates the login and redirects the user-agent to the authorization service.

7. The authorization service determines that the resource server requires the user's consent before the authorization code can be sent to the client.

8. The authorization service displays the user consent form.

9. The user approves the request.

10. The authorization service returns an authorization code to the client using the redirection URI from step 2.

11. The client sends the authorization code in a POST request to the token endpoint and requests an OAuth access token. When making the request, the client authenticates with the authorization server. The client includes the redirection URI used to obtain the authorization code for verification.

12. If the client type requires client credentials, the OAuth Service authenticates the client credentials, validates the authorization code, and ensures that the redirection URI received matches the URI used to redirect the client in step 10.

    The OAuth Service then validates the requested scope based on the resource server's configuration and the user's consent details.

13. The OAuth Service returns an access token to the client for the following grant types:

    • Authorization code

    • Resource owner credentials

    • Client credentials

    • Extension Grant type to support JWT tokens

    A refresh token may also be returned with the access token if the client sends a refresh token request. For more information, see Section 45.2.6, "Understanding Refresh Tokens."

14. The client presents the access token to the resource server.

15. The resource server validates the access token by sending a request to the authorization server's token endpoint. The resource can also validate the token itself because the access token is a standard JWT token.

16. The access service sends the token validation response back to the resource server.

17. The resource server returns the requested resources to the client.

Figure 45-1 OAuth 3-Legged Flow Diagram

45.3.2 Understanding OAuth 2-Legged Authorization

In OAuth 2-legged authorization, the user consent step is not required. The authorization server returns a request token to the client, which the client then uses to request an access token. Because the request token is pre-authorized, the authorization server's token service returns an access token to the client.

45.3.3 Understanding Mobile OAuth Authorization

The Oracle Access Management OAuth Service provides enhanced security support if the OAuth client resides on a mobile device. Mobile applications need to register with OAM prior to using the OAuth Service and each registration is specific to one app on the device. Following registration, an OAuth client on a mobile device must obtain a client verification code before the OAM authorization endpoint will interact with the mobile app. As an added precaution, the OAM server component can restrict token delivery to one specific app installed on one specific device by sending part of a token through HTTPS or HTTP, and sending the other part through push notification using either the Apple Push Notification Service (APNS) or Google Cloud Messaging (GCM).

The user flow detailed in this section describes the additional interactions that Oracle Access Management undertakes when authenticating with a mobile client. The process is shown in the following diagrams.

1. The resource owner opens the mobile OAuth client app.

   An OAM administrator has already registered this client app as a mobile OAuth client.

2. The mobile OAuth client sends the client ID and the device token to the OAuth server and requests a client verification code.

3. The OAuth server returns half of the client verification code over HTTPS or HTTP.

   This behavior can be configured in the Mobile Service Settings section of the OAuth Service Profile configuration page.

   • If the security level is set to Advanced, all codes and tokens are returned using both HTTP and push notification.

   • If the security level is set to Hybrid, registration related codes and tokens are are returned using both HTTP and push notification, whereas access tokens are sent over HTTP only.

   • If the security level is set to Standard mode, all codes and tokens are sent over HTTP only.

4. The mobile OAuth client requests the second half of the client verification code from the OAuth server's push endpoint.

   The push endpoint forwards the request to the Apple Push Notification Service (APNS) or the Google Cloud Messaging (GCM) service depending on if the mobile device is an iOS or Android device.

5. The APNS or GCM service sends the second half of the client verification code to the mobile client app.

   Figure 45-2 Using a Split Request to get a Client Verification Code

   
   

6. The mobile OAuth client requests an authorization code from the OAuth server by sending the client verification code and the device token.

7. The OAuth server redirects to Access Manager.

8. Access Manager sends a login page to the user-agent so that the user can log in.

9. The resource owner enters a user ID and password.

10. Access Manager validates the login and redirects to the OAuth authorization service.

11. The OAuth server is configured to obtain the user's approval to register the device. (The server will not ask for the user's consent prior to registration if the Require User Consent for Client Registration option is disabled on the OAuth Service Profile Configuration page.)

12. The consent page is sent to the resource owner.

13. The resource owner provides (or denies) consent.

14. The OAuth server checks the Oracle Adaptive Access Manager (OAAM) plug-in to determine if additional authentication steps are required.

15. The plug-in determines that an additional challenge question is required.

16. The OAAM challenge question is sent to the resource owner.

17. The resource owner provides the challenge answer, which is forwarded to the OAAM plug-in.

18. The OAAM plug-in validates the challenge answer.

19. The OAuth server uses the mobile redirect URI to return half of the authorization code that the mobile app will need to request a client token.

20. The mobile OAuth client requests the second half of the authorization code from the OAuth server's push endpoint.

    The push endpoint forwards the request to the APNS or GCM service.

21. The mobile client app receives the second half of the authorization code from the APNS or GCM service.

    The mobile client app assembles the authorization code in preparation for requesting a client token.

22. After validating the authorization code, the mobile OAuth client uses the code to request the first half of the client token from the OAuth server's token endpoint.

23. The token endpoint returns the first half of the client token to the mobile client.

24. The mobile client requests the second half of the client token from the OAuth server's push endpoint.

25. The APNS or GCM service sends the second half of the client token to the mobile client app.

    The mobile client assembles the client token as well as a refresh token. The client can use the refresh token to request a new client token.

26. The mobile client prepares to request an access token by completing the following steps:

    • The client requests and receives a client verification code from the OAuth server (as shown in steps 2-5).

    • The client requests and receives the first part of the authorization code from the OAuth server (as shown in step 6, steps 10-13, and step 19).

    • The resource owner does not need to log in (steps 7-9) if the user session is still valid.

    • User consent may be required based on the resource server scope that the client is requesting access to.

    • The OAAM plug-in does not repeat its challenge (steps 14-18).

    • The client requests the second part of the authorization code (as shown in steps 20-21).

27. The APNS or GCM service returns the second half of the authorization code for the access token.

    The client assembles the authorization code in preparation for the access token request.

28. The mobile client requests an access token by sending the client token and the access token authorization code.

29. The token endpoint sends the access token to the client. This behavior depends on whether the Security Level setting in the Mobile Service Settings section of the OAuth Service Profile configuration page is set to Advanced, Hybrid, or Standard.

30. The mobile OAuth client requests access to the protected resources by sending the access token to the resource server.

31. The resource server validates the access token with the OAuth token service. The resource server can also validate the token locally. If the certificates are configured correctly, JWT token signing is verified at the resource server.

32. The OAuth token service sends a response to the resource server.

33. The resource server sends the requested resources to the mobile client.

Figure 45-3 The Complete Mobile App Authorization Request Flow