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

• Setting Up Web Services Manager with OAuth 2.0

• Sending SOAP Requests to BRM Web Services

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:

1. Install the Oracle Access Management software. For the list of supported versions, see "Additional BRM Software Requirements" in BRM Compatibility Matrix.

   For information about installing the Oracle Access Management software, see Oracle Fusion Middleware Installing and Configuring Oracle Identity and Access Management.

2. Create an identity domain in Oracle Access Management. See "Creating an OAuth Identity Domain".

3. Create a resource server in your identity domain. See "Creating a Resource Server".

4. Create an OAuth client in your identity domain. See "Creating an OAuth Client".

5. Validate that OAuth 2.0 is set up properly in Web Services Manager. See "Validating Your OAuth Setup".

6. Configure Web Services Manager to protect BRM Web services through Oracle Access Management. See "Configuring Web Services Manager".

7. Enable OAuth 2.0 validation in Web Services Manager. See "Enabling OAuth Validation for Web Services Manager".

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, use cURL to send an HTTP/HTTPS request to the Oracle Access Management URL:

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

where:

• encoded_admin is the Base64-encoded format of the client ID and client secret separated by a colon (client_id:client_secret).

• oam_adminHost:oam_adminPort is the host name and port for the Oracle Access Management administration server.

• identity_domain is the name of the Oracle Access Management identity domain that you want to create.

For more information about the Oracle Access Management endpoint, 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, use cURL to send an HTTP/HTTPS request to the Oracle Access Management URL:

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

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

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

Creating an OAuth Client

To create an OAuth client, use cURL to send an HTTP/HTTPS request to the Oracle Access Management URL:

curl -i -H "Authorization:Basic encoded_admin" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X POST http://oam_adminHost:oam_adminPort/oam/services/rest/ssa/api/v1/oauthpolicyadmin/client \
-d '{ "secret": "client_secret", "id": "client_id", "name": "client_name", "scopes": [ "BrmWebServices.OAUTH1" ], \
"clientType": "CONFIDENTIAL_CLIENT", "idDomain": "identity_domain", "description": "Description", "grantTypes":[ "CLIENT_CREDENTIALS" ], "defaultScope": "BrmWebServices.OAUTH1", \
"redirectURIs": [ { "url":"http://wsm_host:wsm_port/BrmWebServices", "isHttps": false } ] }'

where:

• client_id and client_secret are the client ID and client secret.

• client_name is the name of the OAuth client that you want to create.

• wsm_host:wsm_port is the hostname and port number of the Web Services Manager server.

For more information about the Oracle Access Management endpoint, 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:

1. Generate an OAuth access token by submitting a POST request to the Create Access Token Flow endpoint in the Oracle Access Management OAuth REST API using cURL:

   curl -i -H 'Authorization: Basic encoded_admin' \
   -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
   -H "X-OAUTH-IDENTITY-DOMAIN-NAME: identity_domain" \
   --request POST http://oam_managedServerHost:oam_managedServerPort/oauth2/rest/token \
   -d 'grant_type=CLIENT_CREDENTIALS&scope=BrmWebServices.OAUTH1'

   where oam_managedServerHost and oam_managedServerPort 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.

2. Validate the access token by submitting a GET request to the Validate Access Token Flow endpoint in the Oracle Access Management OAuth REST API using cURL:

   curl -i -H "X-OAUTH-IDENTITY-DOMAIN-NAME: identity_domain" \
   --request GET "http://oam_managedServerHost:oam_managedServerPort/oauth2/rest/token/info?access_token=access_token"

   where access_token is the access token returned in 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 Web Services Manager

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

To configure Web Services Manager:

1. Copy the BRM_home/deploy/web_services/Infranet.properties file to the directory in which Web Services Manager is installed.

2. Open the copied Infranet.properties file in a text editor.

3. Edit the following parameters:

   infranet.OAuthOldOAM=value
   infranet.OAuthAccessTokenUrl:http://oam_host:oam_port/oauth2/rest/token/info
   infranet.OAuthDomainName:identity_domain

   where value is false for Oracle Access Management 12c, or true for Oracle Access Management 11g or earlier.

4. Save and close the file.
5. Restart your WebLogic Server.

   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.

Enabling OAuth Validation for Web Services Manager

To enable OAuth validation for BRM web services:

1. Go to the BRM_home/deploy/web_services directory and then extract the contents of the BrmWebServices.war file to a local directory (local_dir):

   jar -xvf BrmWebServices.war

2. Open the local_dir/WEB-INF/web.xml file in a text editor.

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

4. Save and close the file.

5. Regenerate the BrmWebServices.war file.

   1. Go to local_dir and delete the existing BRMWebServices.war file:

      cd local_dir
      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:

1. Submit a GET request to the BRM Web service that you want to use:

   curl -i -H "X-OAUTH-IDENTITY-DOMAIN-NAME: identity_domain" \
   -H "Authorization:Bearer access_token" \
   --request GET http://wsm_wlsHost:wsm_wlsPort/BrmWebServices/webServicesName?wsdl

   where:

   • wsm_wlsHost:wsm_wlsPort is the hostname and port number for the WebLogic Server that was deployed from 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".

2. 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://wsm_wlsHost:wsm_wlsPort/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>access_token</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://wsm_wlsHost:wsm_wlsPort/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>'