Oracle® Retail Job Orchestration and Scheduler Oracle® Retail Job Orchestration and Scheduler Release 16.0.027 E94822-01 |
|
Previous |
Next |
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).
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.
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 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.
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 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 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
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.
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.
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>
A client can access services protected by OAuth 2.0 using the following methods:
Use OAuth 2.0 Consumer API
Use Curl
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.
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); }
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