Securing Web Services Manager with OAuth 2.0

5 Securing Web Services Manager with OAuth 2.0

Learn how to secure Oracle Communications Billing and Revenue Management (BRM) Web Services Manager with the OAuth 2.0 authorization framework.

Topics in this document:

About the OAuth 2.0 Authorization Framework

Web Services Manager uses the OAuth 2.0 protocol to authenticate a client application's identity and to authorize the client application to access BRM web services. It does this by validating an OAuth access token that is passed in the header of the client's HTTP/HTTPS request to Web Services Manager.

Your client must pass this OAuth access token in the header of every HTTP/HTTPS request sent to Web Services Manager.

Setting Up Web Services Manager with OAuth 2.0

To set up your client application to use OAuth 2.0 authentication to access BRM web services:

(For deployments using Tomcat only) Download commons-io-2.18.0.jar and copy the file to Tomcat_home/lib.
Install the Oracle Access Management software. For the list of supported versions, see BRM Compatibility Matrix.

For information about installing the Oracle Access Management software, see Oracle Fusion Middleware Installing and Configuring Oracle Identity and Access Management.
Create an identity domain in Oracle Access Management. See "Creating an OAuth Identity Domain".
Create a resource server in your identity domain. See "Creating a Resource Server".
Create an OAuth client in your identity domain. See "Creating an OAuth Client".
Validate that OAuth 2.0 is set up properly in Web Services Manager. See "Validating Your OAuth Setup".
Configure Web Services Manager to protect BRM web services through Oracle Access Management:
- For web services running on standalone on-premises systems, see "Configuring Standalone Web Services Manager (On-Premises Systems)".
- For web services running on standalone cloud native systems, see "Configuring Standalone Web Services Manager (Cloud Native Systems)".
- For web services running on WebLogic Server, see "Configuring Web Services Manager for WebLogic Server".

Creating an OAuth Identity Domain

You create an OAuth identity domain to control the authentication and authorization of users who can sign in to Web Services Manager, and what features they can access. You create all artifacts, such as the resource server and OAuth client, under the identity domain.

To create an identity domain, submit a request to the Add a new OAuth Identity Domain operation in the Oracle Access Management OAuth REST API. For example:

curl -i -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "Authorization:Basic encodedAdmin" \
     -X POST http://oamAdminHost:oamAdminPort/oam/services/rest/ssa/api/v1/oauthpolicyadmin/oauthidentitydomain \
     -d '{"name": "identityDomain", "description": "Description", "tokenSettings":[ { "tokenType": "ACCESS_TOKEN", "tokenExpiry": 3600 } ] }'

where:

encodedAdmin is the Base64-encoded format of the client ID and client secret separated by a colon (clientId:clientSecret).
oamAdminHost:oamAdminPort is the host name and port for the Oracle Access Management administration server.
identityDomain is the name of the Oracle Access Management identity domain that you want to create.

For more information, see "Add a new OAuth Identity Domain" in REST API for OAuth in Oracle Access Manager.

Creating a Resource Server

A resource server hosts the protected resources. It must be capable of accepting and responding to resource requests using OAuth access tokens.

To create a resource server, submit a request to the Add a new Resource Server operation in the Oracle Access Management OAuth REST API. For example:

curl -i -H "Authorization:Basic encodedAdmin" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -X POST http://oamAdmitHost:oamAdminPort/oam/services/rest/ssa/api/v1/oauthpolicyadmin/application \
     -d '{ "name": "resourceServer", "idDomain": "identityDomain", "description": "Description", "scopes":[ { "scopeName":"OAUTH1", "description":"All Access" } ] }'

where resourceServer is the name of the resource server that you want to create.

For more information, see "Add a new Resource Server" in REST API for OAuth in Oracle Access Manager.

Creating an OAuth Client

To create an OAuth client, submit a request to the Add a new OAuth Client operation in the Oracle Access Management OAuth REST API. For example:

curl -i -H "Authorization:Basic encodedAdmin" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -X POST http://oamAdminHost:oamAdminPort/oam/services/rest/ssa/api/v1/oauthpolicyadmin/client \
     -d '{ "secret": "clientSecret", "id": "clientId", "name": "clientName", "scopes": [ "BrmWebServices.OAUTH1" ], \
           "clientType": "CONFIDENTIAL_CLIENT", "idDomain": "identityDomain", "description": "Description", "grantTypes":[ "CLIENT_CREDENTIALS" ], "defaultScope": "BrmWebServices.OAUTH1", \
           "redirectURIs": [ { "url":"http://wsmHost:wsmPort/BrmWebServices", "isHttps": false } ] }'

where:

clientId and clientSecret are the client ID and client secret.
clientName is the name of the OAuth client that you want to create.
wsmHost:wsmPort is the host name and port number of the Web Services Manager server.

For more information, see "Add a new OAuth Client" in REST API for OAuth in Oracle Access Manager.

Validating Your OAuth Setup

To validate that Web Services Manager has been successfully secured with OAuth 2.0:

Generate an OAuth access token by submitting a request to the Create Access Token Flow operation in the Oracle Access Management OAuth REST API. For example:
```
curl -i -H 'Authorization: Basic encodedAdmin' \
     -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
     -H "X-OAUTH-IDENTITY-DOMAIN-NAME: identityDomain" \
     --request POST http://oamManagedServerHost:oamManagedServerPort/oauth2/rest/token \
     -d 'grant_type=CLIENT_CREDENTIALS&scope=BrmWebServices.OAUTH1'
```
where oamManagedServerHost and oamManagedServerPort port is the host name and port for the Oracle Access Management server.

If successful, the response code 200 is returned with the access token and its expiration time in the response payload.

For more information, see "Create Access Token Flow" in REST API for OAuth in Oracle Access Manager.
Validate the access token by submitting a GET request to the Validate Access Token Flow operation in the Oracle Access Management OAuth REST API. For example:
```
curl -i -H "X-OAUTH-IDENTITY-DOMAIN-NAME: identityDomain" \
     --request GET "http://oamManagedServerHost:oamManagedServerPort/oauth2/rest/token/info?access_token=accessToken"
```
where accessToken is the access token returned from step 1.

If successful, the response code 200 is returned with details about the access token in the response payload.

For more information, see "Validate Access Token Flow" in REST API for OAuth in Oracle Access Manager.

Configuring Standalone Web Services Manager (On-Premises Systems)

Configure Web Services Manager to protect BRM web services through Oracle Access Management.

Extract the certificate from the OAuth server and put it in a directory to which the Web Services Manager has access.
Open the BRM_home/apps/brm_wsm/config/Infranet.properties file in a text editor and edit the following parameters:
```
infranet.isOAuth=false
infranet.certificatePath=certPath/certFile
```
where:
- certPath is the directory to which you copied the OAuth certificate.
- certFile is the name of the certificate file.

Configuring Standalone Web Services Manager (Cloud Native Systems)

On cloud native systems, you configure standalone Web Services Manager to protect BRM web services through Oracle Access Management by doing the following:

Retrieve the identity domain's certificate by submitting a request to the Fetch the public certificate of a given Identity Domain operation in the Oracle Access Management OAuth REST API. For example:
```
curl -X GET http://oamManagedServerHost:oamManagedServerPort/oauth2/rest/security \
     -H 'authorization: Basic encodedAdmin' \
     -H 'cache-control: no-cache' \
     -H 'x-oauth-identity-domain-name: identityDomain'
```
For more information, see "Fetch the public certificate of a given Identity Domain" in REST API for OAuth in Oracle Access Manager.
In the oc-cn-helm-chart/keystores/wsm_helidon_oam_oauth.pem file, add the identity domain's public certificate:
```
-----BEGIN CERTIFICATE-----
publicCertificateValueString
-----END CERTIFICATE-----
```
where publicCertificateValueString is the certificate value returned in the keys.xc5 parameter from step 1.
In your override-values.yaml file for oc-cn-helm-chart, set the following keys:
- ocbrm.wsm.soap.configEnv.isOauthEnabled: Set this to true.
- ocbrm.wsm.soap.configEnv.oauthCertificateName: Set this to wsm_helidon_oam_oauth.pem.
Redeploy BRM Web Services Manager:
```
helm upgrade BrmReleaseName oc-cn-helm-chart --values OverrideValuesFile --namespace BrmNameSpace
```
where:
- BrmReleaseName is the release name for oc-cn-helm-chart and is used to track this installation instance.
- OverrideValuesFile is the file name and path to your override-values.yaml file.
- BrmNameSpace is the namespace in which to create BRM Kubernetes objects for the BRM Helm chart.
Generate an OAuth access token by submitting a request to the Create Access Token Flow operation in the Oracle Access Management OAuth REST API. For example:
```
curl --location 'http://oamManagedServerHost:oamManagedServerPort/oauth2/rest/token' \ 
     --header 'Authorization: Basic encodedAdmin' \ 
     --header 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' \ 
     --header 'X-OAUTH-IDENTITY-DOMAIN-NAME: identityDomain' \ 
     --data 'grant_type=CLIENT_CREDENTIALS&scope=BrmWebServices.OAUTHTEST'
```
If successful, the response code 200 is returned with the access token and its expiration time in the response payload.

Include this access token in all SOAP requests you submit to BRM Web Services Manager.

Configuring Web Services Manager for WebLogic Server

Configure Web Services Manager to protect BRM web services through Oracle Access Management and enable OAuth validation.

To configure Web Services Manager for WebLogic Server:

Copy the BRM_home/deploy/web_services/Infranet.properties file to the BRM_home/apps/brm_wsm/config/ directory.
Open the copied Infranet.properties file in a text editor.

Edit the following parameters:

infranet.OAuthOldOAM=false
infranet.OAuthAccessTokenUrl:http://oamManagedServerHost:oamManagedServerPort/oauth2/rest/token/info
infranet.OAuthDomainName:identityDomain

Save and close the file.
Restart Web Services Manager.

When you restart the WebLogic Server, ensure that the libportal.so BRM library is set in LD_LIBRARY_PATH. For JRE on 64-bit environments, rename libportal64.so to libportal.so.
Go to the BRM_home/deploy/web_services directory and then extract the contents of the BrmWebServices.war file to a local directory (localDir):
```
jar -xvf BrmWebServices.war
```
Open the localDir/WEB-INF/web.xml file in a text editor.

Uncomment these filter and filter-mapping tags:

<filter>
      <filter-name>OAuthTokenValidationFilter</filter-name>
      <filter-class>com.portal.jax.OAuthTokenValidationFilter</filter-class>
</filter>
<filter-mapping>
   <filter-name>OAuthTokenValidationFilter</filter-name>
   <servlet-name>BrmWebServices</servlet-name>
   <url-pattern>/BrmWebServices/*</url-pattern>
   <url-pattern>/BRMPricingServices_v2/</url-pattern>
   <url-pattern>/BRMBalServices_v2/</url-pattern>
   <url-pattern>/BRMARServices_v2</url-pattern>
   <url-pattern>/BRMBillServices_v2</url-pattern>   
   <url-pattern>/BRMCustServices_v2</url-pattern>
   <url-pattern>/BRMCustcareServices_v2</url-pattern>
   <url-pattern>/BRMInvServices_v2</url-pattern>
   <url-pattern>/BRMPymtServices_v2</url-pattern>
   <url-pattern>/BRMCollectionServices_v2</url-pattern>
   <url-pattern>/BRMReadServices_v2</url-pattern>
   <url-pattern>/BRMActServices_v2</url-pattern>
   <url-pattern>/BRMSubscriptionServices_v2</url-pattern>
   <dispatcher>FORWARD</dispatcher>
   <dispatcher>REQUEST</dispatcher>
</filter-mapping>

Save and close the file.
Regenerate the BrmWebServices.war file.
1. Go to localDir and delete the existing BRMWebServices.war file:
```
cd localDir
rm BrmWebServices.war
```
2. Create a new BrmWebServices.war archive file:
```
jar -cvf BrmWebServices.war .
```

Sending SOAP Requests to BRM Web Services

After you have set up OAuth 2.0 authentication in Web Services Manager, you can start submitting SOAP requests to the BRM web services.

To send a request to a BRM web service:

Submit a GET request to the BRM web service that you want to use:
```
curl -i -H "X-OAUTH-IDENTITY-DOMAIN-NAME: identityDomain" \
     -H "Authorization:Bearer accessToken" \
     --request GET http://wsmHost:wsmPort/BrmWebServices/webServicesName?wsdl
```
where:
- wsmHost:wsmPort is
  - For the standalone server: The host name and port for Web Services Manager. You can find these values at the top of the infranet.properties file.
  - For Web Services Manager deployed in another server (for example, WebLogic Server): the host name and port number for the external server that contains BRM Web Services Manager.
- webServicesName is the name of the web service such as BRMACTServices_v2, BRMCUSTServices_v2, or BRMPYMTServices_v2. For the web service names, see "About WSDL Files and BRM Opcodes".

Submit a request to the target SOAP operation, ensuring that you send the OAuth access token in the header request:

curl -i -H "Content-Type: text/xml;charset=UTF-8" 
     --request POST http://wsmHost:wsmPort/BrmWebServices/webServicesName
     -d '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bus="http://xmlns.oracle.com/BRM/schemas/BusinessOpcodes"> 
     <soapenv:Header>
        <code>accessToken</code>
     </soapenv:Header>
     <soapenv:Body>
        <bus:operationNameRequest>
           <bus:opcode_Request>
              <bus:opcode_inputFlist>
              </bus:opcode_inputFlist>
           </bus:opcode_Request>
        </bus:pcmOpSearchRequest>
     </soapenv:Body>
     </soapenv:Envelope>'

where:

operationName is the name of the SOAP operation to call in the web service interface.
opcode is the name of the BRM opcode to call.

For example, to search for accounts that have purchased a particular package, you would submit this request to the pcmOpSearch operation in the BRMReadServices_v2 interface:

curl -i -H "Content-Type: text/xml;charset=UTF-8" 
     --request POST http://wsmHost:wsmPort/BrmWebServices/BRMReadServices_v2 
     -d '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bus="http://xmlns.oracle.com/BRM/schemas/BusinessOpcodes">
     <soapenv:Header>
        <code>access_token</code>
     </soapenv:Header>
     <soapenv:Body>
        <bus:pcmOpSearchRequest>
           <bus:PCM_OP_SEARCH_Request>
              <bus:flags>0</bus:flags>
              <bus:PCM_OP_SEARCH_inputFlist>
                 <bus:FLAGS>256</bus:FLAGS>
                 <bus:ARGS elem="1">
                    <bus:POID>0.0.0.1 /plan -1 0</bus:POID>
                 </bus:ARGS>
                 <bus:ARGS elem="2">
                    <bus:ACCOUNT_OBJ>0.0.0.1 /account 1 0</bus:ACCOUNT_OBJ>
                 </bus:ARGS>
                 <bus:ARGS elem="3">
                    <bus:NAME>Plan 1 - Measured Web Access with Discounts</bus:NAME>
                 </bus:ARGS>
                 <bus:POID>0.0.0.1 /search/pin 45 0</bus:POID>
                 <bus:RESULTS elem="0"></bus:RESULTS>
                 <bus:TEMPLATE>select X from /plan where F1 like V1 and F2 = V2 and F3 =V3</bus:TEMPLATE>
              </bus:PCM_OP_SEARCH_inputFlist>
           </bus:PCM_OP_SEARCH_Request>
        </bus:pcmOpSearchRequest>
     </soapenv:Body>
     </soapenv:Envelope>'