Oracle® Retail Bulk Data Integration Cloud Service Implementation Guide Release 19.0.000 F25615-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.
IDCS 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.
BDI/JOS uses OAuth 2-legged flow i.e. business to business flow. IDCS 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.
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.
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-19.0.000.jar
oauth2-service-provider-api-19.0.000.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 IDCS server using client id, client secret, and scope.
Adds "Authorization Bearer <token>" HTTP header.
Adds "Scope" header with configured scope.
Calls the service.
Download OAuth2ServiceConsumer19.0.000ForAll19.0.000Apps_eng_ga.zip.
Unzip the downloaded archive. The "oauth2-consumer-home" directory will be created under the current directory.
Unzip OAuth2ServiceConsumer19.0.000ForAll19.0.000Apps_eng_ga.zip
This command extracts the archive. The directories for the installation are shown.
/conf/oauth2-service-consumer-config.properties
./lib/oauth2-common-19.0.000.jar
./lib/oauth2-service-consumer-api-19.0.000.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 10-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-19.0.000.jar
oauth2-service-consumer-api-19.0.000.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
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
IDCS
If TAS Service Manager Payload is available, run the script create-property-file-from-service-manager-payload.sh service-manager-payload-file.json
If TAS Service Manager Payload is not available, update conf/idcs-tools.properties manually
e.g.,
TenantId=tenantId
ClientID=RGBURICSApp-APPID
ClientSecret=secret
IdcsUrl=https://idcs.com
Change the email-id in input/rics-users.csv add-users.sh rics.
add-groups.sh rics
add-app.sh rics prod
update-idcs-web-tier-policy-json.sh rics prod
Add cloudgate to App Roles in IDCS (Currently a manual step, until a solution is figured out)
App --> Configuration --> Client Configuration --> +Add (Grant the client access to Identity Cloud Service Admin APIs)
Select "Cloud Gate" --> Save
WTSS
Generate routes.config for WTSS generate-wtss-to-app-routes-info-json.sh service-name environment-label wtssserver-hostname appserver-hostname appserver-port
For example,
generate-wtss-to-app-routes-info-json.sh rics prod <wtsserver-hostname> <appserver-hostname> 80
Generate IDCS connection info json
generate-wtss-to-idcs-connection-info-json.sh rics prod
Run docker image with the generated files
For example, docker run --name wtss -v <path>/rics-prod-wtss-to-idcs-connection-info.json:/config/wtss-config.json -v <path>/rics-prod-wtss-to-app-routes-info.json:/config/routes.json -p 80:9999 -d wtss.docker.com/oracle/wtss
WebLogic
Add to each managed server startup : -Dweblogic.security.SSL.hostnameVerifier=weblogic.security.utils.SSLWLSWildcardHostnameVerifie
Configure IDCS Integrator
Security Realms --> myrealm --> Providers
- Delete OAM and OID providers (if exists)
- Change Control Flag to "SUFFICIENT" or "OPTIONAL" for DefaultAuthenticator
- Add new service provider for IDCS
New -->
Name: IDCSIntegrator
Type: OracleIdentityCloudIntegrator
Click OK
Click on the created provider
Control Flag: SUFFICIENT
Active Types:
Add "Authorization" to "Chosen:"
Save
Click "Provider Specific"
Host: identity.c9dev1.oc9qadev.com
Port: 443
Check SSL Enabled
Tenant: TenantId (from Step #1)
Client Id: (from conf/rics-prod.properties created after Step #4)
Client Secret (from conf/rics-prod.properties created after Step #4)
Confirm Client Secret
Save
Reorder so that IDCS provider is ahead of default provider
OAuth2 (with IDCS) Support in BDI/JOS
For an application service URL call to work with IDCS OAuth2, need to configure following properties oauth2AuthorizationServerUrl, ClientId, ClientSecret, UserId, UserPassword.
oauth2AuthorizationServerUrl is configured in BDI System Options table. It needs to point to IDCS URL from where we can get the token. E.g. https://<hostname>/oauth2/v1/token.
ClientId, ClientSecret are stored in the wallet using the RICS application alias name "ric-sOauth2ApplicationClientAlias". For different oauth applications like MFCS and RPAS we store their ClientId Cli-entSecret under the alias names "mfcsOauth2ApplicationClientAlias", "rpasOauth2ApplicationClientAlias" respec-tively.
ProcessFlow application may call app services that reside in different cloud services(RICS, MFCS, RPAS). Each app service URL that ProcessFlow can call is configured in the BDI System Options table using a "<some name>Url" key naming pattern.
OAuth2 is enabled or disabled for url "<some name>Url" based on the existence of the OAuth2 alias "<some name>UrlOAuth2ApplicationClientAlias". This "<some name>UrlOAuth2ApplicationClientAlias" must point to the alias name of the ClientId, ClientSecret i.e. "*ricsOauth2ApplicationClientAlias" or "*mfcsOauth2ApplicationClientAlias". The * in the alias name is an indicator that this alias actually points to the shared alias ricsOauth2ApplicationClientAlias or mfcsOauth2ApplicationClientAlias. With this setup we do not have to duplicate the ClientId, ClientSecret for every app service url.
The BDI install script is modified to ask for OAuth2 specific questions if it detects OAuth2 provider section (CentralAuthenticationSystem/IdcsAuthenticationProvider) is configured.
The bdi-process-flow-admin-deployment-env-info.json file now has new OAuth2 sections (CentralAuthentica-tionSystem/IdcsAuthenticationProvider). In a typical deployment, only the value of oauth2AuthorizationServerUrl needs to get changed. All the other configuration is required by the system but the default out of the box values are pre-configured correctly so the person doing the install does not have to change anything. Following is a snippet of the json.
Below is the json snippet of OAuth2
"CentralAuthenticationSystem":{ "IdcsAuthenticationProvider":{ "oauth2AuthorizationServerUrl":"<hostname>/oauth2/v1/token", "oauth2Application":[ { "oauth2ApplicationName" : "RICS", "oauth2ApplicationScopeOfAccess" : {"name":"oauth2.default.scopeOfAccess.*", "value":"urn:opc:idm:__myscopes__"}, "oauth2ApplicationClientAlias" : "ricsOauth2ApplicationClientAlias", "oauth2ApplicationClientId" : "GET_FROM_WALLET", "oauth2ApplicationClientSecret" : "GET_FROM_WALLET" }, { "oauth2ApplicationName" : "MFCS", "oauth2ApplicationScopeOfAccess" : {"name":"oauth2.default.scopeOfAccess.*", "value":"urn:opc:idm:__myscopes__"}, "oauth2ApplicationClientAlias" : "mfcsOauth2ApplicationClientAlias", "oauth2ApplicationClientId" : "GET_FROM_WALLET", "oauth2ApplicationClientSecret" : "GET_FROM_WALLET" }, { "oauth2ApplicationName" : "RPAS", "oauth2ApplicationScopeOfAccess" : {"name":"oauth2.default.scopeOfAccess.*", "value":"urn:opc:idm:__myscopes__"}, "oauth2ApplicationClientAlias" : "rpasOauth2ApplicationClientAlias", "oauth2ApplicationClientId" : "GET_FROM_WALLET", "oauth2ApplicationClientSecret" : "GET_FROM_WALLET" } ] }, "OamAuthenticationProvider":{ }