X

Best Practices from Oracle Development's A‑Team

Implementing OAuth 2 with Oracle Access Manager OAuth Services (Part I)

Introduction

This post will explain the basics of OAuth 2.0 and how it can be used to protect resources by implementing some of the most common OAuth use cases.

OAM provides out of the box OAuth Services, which allows a Client Application to access protected resources that belong to an end-user (that is, the Resource Owner).

Before going further in this post, check out the OAuth2 specification, to understand the basic OAuth concepts, as it won’t be covered in this post.

This post will be divided into 5 parts:

Part I - explains the proposed architecture and how to enable and configure OAM OAuth Services.

Part II - describes a Business to Business use-case (2-legged flow);

Part III  - explains the Customer to Business use-case (3-legged flow), when the client application is running in the application server;

Part IV - describes the Customer to Business use-case (3-legged flow), when the client application runs on the browser, embedded as Javascript code;

Part V  - discuss Access Token and Refresh Token usage/strategy and provides the source code for the use-case examples.

Oracle recommends that customers install the latest bundle patch available for their specific IdM release. Bundle Patches might include important patches for OAuth implementation. You can find information about Bundle Patch History and Releases in the Support document "OAM Bundle Patch Release History (Doc ID 736372.1)". Please visit My Oracle Support (https://support.oracle.com) and search for Doc ID 736372.1.

Before You Proceed...

Read this if you're using OAM R2PS3 (11.1.2.3)

This post was written based on OAM R2PS2 release. Even though most things are still the same on R2PS3 release, there are some subtle differences from one release to the other.
In OAM R2PS3, you need to deploy a webgate in front of your OAM servers in order to use the OAuth 3-legged flow.
The webgate is required to protect the OAuth consent page, otherwise you will get an error when trying to follow the 3-legged OAuth flow.
Review the documentation on how to install a supported webserver and deploy webgate here.

Deploy and register a webserver/webgate and configure the following resources in your application domain:

/ms_oauth/oauth2/oammsui/** - Excluded
/oam/** - Excluded
/ms_oauth/img/* - Excluded
/ms_oauth/style/* - Excluded
/ms_oauth/oauth2/endpoints/** - Excluded
/ms_oauth/oauth2/ui/** - Protected

In your webserver create a new conf file with the following directives

<Location /oam>
SetHandler weblogic-handler
WLProxySSL ON
WLProxySSLPassThrough ON
WLCookieName OAM_JSESSIONID
WebLogicCluster server1:port1, server2:port2
</Location>

<Location /ms_oauth>
SetHandler weblogic-handler
WLProxySSL ON
WLProxySSLPassThrough ON
WLCookieName OAM_JSESSIONID
WebLogicCluster server1:port1, server2:port2
</Location>

Architecture

The picture below represents an overview of the different components and the interaction between them.

Architecture

 

  • Client WebApplication: The applications play the role of OAuth Clients. The applications will request access to resources owned by the end user.
  • ResourceServer: Those are RESTful webservices that represent the protected resources owned by the end user. They require a valid OAuth token in order to serve information back to the ClientWebApp.
  • OAM/OAuth Server: Responsible for authenticating the end user and for issuing and validating OAuth Tokens.

Configuration

The configuration takes place in the OAM Mobile and Social component, in the OAuth Services page.

You need to have access to the OAM Console at http://oam_admin_server:port/oamconsole to perform the required configurations.

Before proceeding, make sure you have enabled OAuth Services by following the steps described here.

Before jumping into the OAuth flow and code examples, we need to register Clients and Resources Serveres with OAM.

For the B2B use-case, presented in part II, we will need to register a 'Business' Resource Server and a 'BusinessClient' Client.

The Business Client will request access to some resources from the Business Resource Server, passing an Access Token, obtained from OAM's OAuth Server.

For the C2B use-cases, we will register one Resource Server: 'Customer Resource Server'. It will be used for both C2B use-cases (app running in the application server and app running as embedded Javascript code).

We will also register the following clients: 'Customer Client' (for the C2B use-case where the app runs in the application server) and the 'Browser Client' (for the C2B use-case where the app runs as embedded Javascript code).

In all cases, the Resource Servers will need to validate the Access Token, before granting access to the protected resources.

To achieve this, there are two different approaches:

1 - Use a 'special' client, we're calling it the 'Service Token Validator', which is just another OAuth client, with no grant types provileges but it is configured to retrieve additional token attributes (useful for token validation). This approach is simple and requires almost no coding since it only required a REST call to the OAuth Server, passing the Access Token. This is the simplest choice but won't be really useful in real world application as it does not scale and performs well;

2 - Export the OAuth Server signing key and implementing a piece of code in the Resource Server that validates the Access Token signature and claims. This approach is a bit more complicated as it involves some 3rd party library, different keys, claims, etc.

Both approaches are explained in part V of this post series, and considerations are discussed in part V regarding the cons/pros of one over another.

Creating a Custom Resource Server

A Resource Server represents a 3rd party Service or Application that your clients are entitled to have access to.

The use-cases proposed here will use 'business' and 'clients' services, so two Resource Servers will be created in OAM: 'Business Service' and 'Client Service'.

The Business Service will be used in the B2B use-case and the Client Service will be used in the C2B use-cases.

To create the Resource Servers, follow these steps:

1. Log in to OAM Console, in the Launch Pad page, open the OAuth Service page.

img1

 

2. Select the Default Domain.

img2

 

3. Open the Resource Servers tab.

img3

 

4. On the Custom Resource Servers table, click ‘create’ and create two Resource Servers according to the information below.

img4

 

 

Business Resource Server

Name: Business

Authorization & Consent Service Plug-in: CoherenceAuthzUserConsentPlugin

Scope Namespace Prefix: Business

Scopes: Info

Decription: Reads Business Information

 

Your Business Resource Server should look like this:

img5

 

Customer Resource Server

Name: Customer

Authorization & Consent Service Plug-in: CoherenceAuthzUserConsentPlugin

Scope Namespace Prefix: Customer

Scopes: Info

Description: Reads Customer Information

 

Your Customer Resource Server should look like this:

img6

 

 

OAuth Client Registration

In OAuth2, clients are "applications making protected resource requests on behalf of the resource owner and with its authorization."

The Services, or Applications, that play the roles of Resource Servers in our use cases, will validate the OAuth token received from the clients when those clients request access to their protected resources.

To do so, our Services will need to be registered as 'special' clients with OAM, with the only purpose of validating OAuth tokens. More on that later.

Four OAuth clients will be registered, one for the Business Use Case (B2B), one for the C2B Use Case - server side application, one for the C2B Use Case - application embedded as Javascript code, and one additional client for our Resource Server applications to validate the Access Tokens.

 

Access the OAM Console,  and execute the following steps:

1. On the Launch Pad page, in the Mobile and Social section, click on OAuth Service link. The OAuth Identity Domains tab appears.

2. Click on  the Defaul Domain, and open the OAuth Clients tab.

img7

3. Click on the Create button and enter the appropriate data to create the clients (execute this step 4 times for each client with the data below).

 

Business Client

The Business Client represents the business client application in the B2B use case.

This application will make calls to the Resource Server represented by a RESTful web service that will provide business information based on the client ID.

Set the following properties for the Business Client:

Client ID: businessClient

Client Secret: 3WFLudTFyBk

Bypass User Consent: checked

Allowed Scopes: Business.Info

Grant Types: Client Credentials

 

Your Business Client should look like this:

img8

 

Customer Client

The Customer Client represents the customer client application, in the C2B use case, where the application runs on the server side.

This application will make calls to the Resource Server represented by a RESTful web service that will provide information based on the end user authenticated with OAM.

Set the following properties for the Customer Client:

Client ID: customerClient

Client Secret: zRpJbl73iE8X

HTTP Redirect URIs: https://oxygen.mycompany.com:7502/ClientWebApp/CustomerClient

(This is the URI of the client application that will receive the Authorization Token, after the user successfully authenticates. See the provided source code for more details).

Allowed Scopes: Customer.Info, UserProfile.me

Grant Types: Authorization Code

 

Your Customer Client should look like this:

img9

 

Browser Client

The Browser Client represents the customer client application, in the C2B use case, where the application runs on the browser itself.

This application will make calls to the Resource Server represented by a RESTful web service that will provide information based on the end user authenticated with OAM.

Client ID: browserClient

Client Secret: g8aGglZDrPDl7e

HTTP Redirect URIs: https://oxygen.mycompany.com:7502/ClientWebApp/index.html

(This is the URI of your client application that will receive the Authorization Token, after the user successfully authenticates).

Allowed Scopes: Customer.Info, UserProfile.me

Grant Types: Authorization Code

 

Your Browser Client should look like this:

img10

 

 

Service Token Validator

The Service Token Validator is a 'special' client; it actually runs on the Resource Server side, and will only be used by the Resource Server to validate the incoming OAuth Access Tokens.

Client ID: ServiceTokenValidator

Allow Token Attributes Retrieval: Checked.

(This will allow our client to obtain detailed information about the Access Token along with its validation status.)

Client Secret: A3nqKocV6I0GJB

No other information is required for this client.

 

Your Service Token Validator Client should look like this:

 

img11

 

 

That's it for now, in the following post we will cover the Business to Business Use case.

Join the discussion

Comments ( 2 )
  • Edwin Segura Wednesday, May 29, 2019
    The fact to use scope as "Info" in both Resource Servers Client and Business generates an error when starting the Oauth authentication.

    Error in the Browser:
    "error":"server_error","error_description":"oracle.security.idaas.oauth.common.provider.exception.OAuthMisconfigurationException: Invalid Consent Management Request"}

    oam_server1 logs:
    Invalid Consent Management Request[[java.lang.RuntimeException: Duplicated scope across different reserver server: Info

    I had to change for Business Info by Info_Bus and then the error disappear.
  • Jonatan Mora Wednesday, June 12, 2019
    Hello,

    Is very interesting the five documents that you describe, but I want to login with oauth and mobile. But the path is diferent in some parts.

    Do you know a good manual or document reference for oauth-mobile?
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha