11 OAuth 2.0

OAuth 2.0 is the industry-standard protocol for authorization. The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.

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).

OAuth 2.0 Architecture Diagram

Figure 11-1 OAuth 2.0 Architecture Diagram

OAuth 2.0 Concepts

Business to Business (2-legged flow)

It usually represents an application that calls another application or service without end user intervention.
A client (Business Client application) will make a call to a service, business service (in OAuth spec, a resource server), and request some business information, passing the access token.
Since there is no end user intervention, the client is pre-authorized to have access to the resource.

OAuth 2.0 Use Case Flow

Figure 11-2 OAuth 2.0 Use Case Flow

OAuth 2.0 Terms

Resource Server – The server hosting the protected resource.
Resource Owner – An entity capable of granting access to a protected resource.
Client – An application making protected resource requests on behalf of the resource owner. It can be a server-based, mobile or a desktop application.
Authorization Server – The server issuing access tokens to the clients after successfully authenticating the resource owner and obtaining authorization.

JOS OAuth 2.0 Architecture

JOS uses OAuth 2-legged flow i.e. business to business flow. OAM provides OAuth services. OHS is Oracle HTTP server that acts as a listener to incoming requests and route them to appropriate service.

Figure 11-3 JOS OAuth 2.0 Architecture

OAuth 2 Service Provider

BDI/JOS services can be accessed using OAuth 2.0. Use the information provided in Service Consumer section on how to access BDI/JOS services using OAuth 2.0.

Service providers that want to expose services using OAuth 2.0 has to go through the below steps.

Service Provider Configuration

Service provider needs an OAuth identity domain to register resource server information and client profile information so that clients can access the services using OAuth 2.0 protocol.

OAuth 2.0 Service provider distribution includes a configuration file "oauth-configuration-env-info.properties" and install script "oauth-config.sh" to create identity domain, register resource server and client profile information.

Use OAuth 2 Installation Guide to configure a service provider in OAM.

Scopes

Scopes allow certain service endpoints to be restricted to clients.

Here are the available scopes.

AdminAccessScope
OperatorAccessScope
MonitorAccessScope

Configuration of scopes for service provider

Service provider needs to configure scope of access for all resource servers in "oauth-configuration-env-info.properties" file.

Here is a sample configuration for scope in service provider. With this configuration, clients can access only BDI Process Flow end points permitted for operator. Multiple scopes can be specified as a comma separated list for a resource server.

oauth-configuration-env-info.oauth-resource-server-interface.resourceServerName=bdi-process-flow,jos-rms-batch-job-admin

oauth-configuration-env-info.oauth-resource-server-interface.bdi-process-flow.scopeName=OperatorAccessScope

oauth-configuration-env-info.oauth-resource-server-interface.jos-rms-batch-job-admin.scopeName=OperatorAccessScope,MonitorAccessScope

OHS Configuration

In cloud environment, all external HTTP requests are routed through OHS (Oracle HTTP Server). OHS needs to be configured to add "oauth2" in the URL after root context and forward the request to appropriate service if the request contains the HTTP header "Authorization: Bearer <token>". This header indicates that the service is protected by OAuth 2.0.

Use the OAuth 2.0 Installation Guide to configure OHS.

OAuth Server Public Certificate

Service provider uses OAuth server public certificate to validate the token provided in the HTTP request.

Use instructions provided in the OAuth 2.0 Installation Guide to import OAuth server public certificate into service provider.

OAuth 2.0 Servlet Filter

Service Provider needs to include "OAuth2ServletFilter" class in "web.xml" to intercept HTTP requests that contain "oauth2" in the path of the URL. The following jars need to be included in the classpath of service provider. The servlet filter validates the token provided in the "Authorization" header and forwards to the service if token is valid.

oauth2-common-16.0.027.jar
oauth2-service-provider-api-16.0.027.jar

Add the following in "web.xml" of service provider.

<filter>
<filter-name>OAuth2ServletFilter</filter-name>        <filter-class>com.oracle.retail.integration.oauth2.provider.OAuth2ServletFilter</filter-class>
       <init-param>
<param-name>oauth2.serviceProviderConfigClassName</param-name>                <param-value>com.oracle.retail.bdi.common.util.OAuth2ConfigProvider</param-value>
       </init-param>
</filter>
 
<filter-mapping>
       <filter-name>OAuth2ServletFilter</filter-name>
       <url-pattern>/oauth2/*</url-pattern>
</filter-mapping>
 
Add the below security-constraint as the last security constraint in "web.xml".
 
<security-constraint>
       <web-resource-collection>
               <web-resource-name>OAuth2Paths</web-resource-name>
               <url-pattern>/oauth2/*</url-pattern>
       </web-resource-collection>
</security-constraint>

OAuth 2.0 Service Consumer

A client can access services protected by OAuth 2.0 using the following methods:

Use OAuth 2.0 Consumer API
Use Curl

Access Services using OAuth 2.0 Consumer API

OAuth 2.0 consumer API simplifies access of services protected by OAuth 2.0. The consumer API executes the following steps:

Gets the token from OAM server using client id, client secret, and scope.
Adds "Authorization Bearer <token>" HTTP header.
Adds "Scope" header with configured scope.
Calls the service.

Consumer Configuration

Download OAuth2ServiceConsumer16.0.027ForAll16.0.027Apps_eng_ga.zip.
Unzip the downloaded archive. The "oauth2-consumer-home" directory will be created under the current directory.
```
Unzip OAuth2ServiceConsumer16.0.027ForAll16.0.027Apps_eng_ga.zip
```
This command extracts the archive. The directories for the installation are shown.
- ./conf/oauth2-service-consumer-config.properties
- ./lib/oauth2-common-16.0.027.jar
- ./lib/oauth2-service-consumer-api-16.0.027.jar
- ./README.txt
Edit the oauth-service-consumer-config.properties file to create oauth2 domain environment.
```
vi  oauth-service-consumer-config.properties
```

Provide the following values in the properties file.

Table 11-1 Configuration Property File Values

Configuration Property	Description
oauth2.default.authorizationServerUrl	URL of OAuth server that issues tokens for default server
oauth2.default.scopeOfAccess.*	Scope of access - *.<scope> for default server (scope - AdminAccessScope, OperatorAccessScope, MonitorAccessScope)
oauth2.default.scopeOfAccess.headers	headers.<scope> for default server (scope - AdminAccessScope, OperatorAccessScope, MonitorAccessScope)
oauth2.default.scopeOfAccess.jos-rms-batch-job-admin	<Root Context>.<scope> for default server
oauth2.srv1.authorizationServerUrl	URL of OAuth server that issues tokens for server "srv1"

OAuth 2.0 Client Sample Code

The following sample code calls discover service of BDI Process Flow application. Make sure that following jars are included in the classpath.

oauth2-common-16.0.027.jar
oauth2-service-consumer-api-16.0.027.jar

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.WebTarget;
Import com.oracle.retail.integration.oauth2.consumer.OAuth2RestServiceConsumerTokenAppender;
import com.oracle.retail.integration.oauth2.consumer.OAuth2ClientBuilder;
import com.oracle.retail.integration.oauth2.consumer.OAuth2Client;
 
// Code that calls service protected by OAuth 2
void callService() {
       Client client = ClientBuilder.newClient().register(new OAuth2RestServiceConsumerTokenAppender("JosClientID", "JosClientID1", "srv1"));
       WebTarget target = client.target("https://host:port/bdi-process-flow/resources/discover");
       String out = target.request().get().readEntity(String.class);
       System.out.println("out=" + out);
}

Access Services using Curl

Curl can be used to call a service. There are two steps for calling a service. First issue a curl command to get the token from the authorization server and the second curl command calls the service using the token.

Request Access Token

The following curl command can be used to request access token.

Curl -X POST -H "Authorization: <Base64 encoded credentials for Authorization Server>" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" - H "Accept-Charset: UTF-8" -H "Connection: keep-alive" -H "Content-Length: <length>" -d "grant_type=client_credentials&scope=<scope>" <url>

Sample Scope:

bdi-process-flow.OperatorAccessScope

See "Consumer Configuration" to find various scopes of accesses.

Sample Authorization Server URL for JosDomain:

http://host:port/ms_oauth/oauth2/endpoints/JosDomainserviceprofile/tokens

Call Service

Curl -X GET -H "Authorization: Bearer <token>" - H "Scope: <scope>" <url>

Token: Token obtained using the above curl command

Scope: Scope used to obtain the token

Sample URL: http://host:port/bdi-process-flow/oauth2/resources/discover