Securing Web Services Manager with OAuth 2.0

4 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 supports OAuth access-token validation for SOAP invocations of its BRM opcode services, for both XML-string and XML-element payloads. Web Services Manager validates tokens locally and does not call a particular authorization server at run time. You can use any authorization server that issues tokens compatible with the Web Services Manager validation requirements.

Web Services Manager accepts a compact JWT signed with RS256. Configure Web Services Manager with a PEM-encoded X.509 certificate containing the RSA public key that corresponds to the private key used to sign the token. Web Services Manager uses the certificate to validate the token signature and validates the token’s validity information.

Include the access token in the HTTP Authorization: Bearer <ACCESS_TOKEN> header of each protected SOAP invocation. For backward compatibility, Web Services Manager also accepts a SOAP header element whose local name is code. The SOAP-header token takes precedence if a request supplies both forms.

Note:

Passing an OAuth access token in the SOAP <code> header is deprecated. Use the HTTP Authorization: Bearer <ACCESS_TOKEN> header instead. Support for the SOAP <code> header may be removed in a future release.

Setting Up Web Services Manager with OAuth 2.0

To set up a client application to use OAuth 2.0 access tokens with Web Services Manager:

Configure a compatible authorization server to issue RS256-signed JWT access tokens to the client.
Obtain the authorization server’s token-signing X.509 certificate in PEM format. See "Obtaining the Token-Signing Certificate".
Make the certificate available to Web Services Manager and enable OAuth validation. See "Configuring Web Services Manager".
Obtain an access token according to the authorization server’s instructions. For service-to-service integrations, the OAuth 2.0 client credentials grant is the typical choice for obtaining the bearer access token.
Submit an authenticated SOAP request and verify Web Services Manager protection. See "Sending SOAP Requests to BRM Web Services".

The examples use HTTPS endpoints and placeholders in italics. Replace each placeholder with your deployment’s value before running a command.

Obtaining the Token-Signing Certificate

Obtain the token-signing certificate from the authorization-server administrator or through the authorization server’s supported administration interface. If the authorization server publishes a JSON Web Key Set (JWKS) containing an x5c value, use the X.509 certificate associated with the token-signing key. The certificate supplied to Web Services Manager must be in PEM format and contain the RSA public key corresponding to the private key used to sign the access tokens.

Whenever the authorization server changes or rotates its token-signing certificate, update the certificate file configured for Web Services Manager before tokens signed with the new key are sent to Web Services Manager. Web Services Manager reloads the certificate when the configured file changes. If the certificate location changes, update the infranet.certificatePath entry in the Infranet.properties file and restart Web Services Manager.

Configuring Web Services Manager

The default Infranet.properties disables OAuth validation. Enable it explicitly. If the infranet.isOAuth entry is absent from the file, the handler uses true as its fallback value.

To configure Web Services Manager to enable OAuth validation:

Save the authorization server’s token-signing X.509 certificate in PEM format in a directory readable by WSM. The certificate must contain the RSA public key corresponding to the private key that signs the access tokens.
Open the BRM_home/apps/brm_wsm/config/Infranet.properties file in a text editor and edit the following parameters:
```
infranet.isOAuth=true
infranet.certificatePath=certPath/certFile.pem
```
where:
- certPath is the directory to which you copied the OAuth certificate.
- certFile is the name of the certificate file.
Save the file and restart Web Services Manager.

Sending SOAP Requests to BRM Web Services

After configuring OAuth validation in Web Services Manager, obtain a compatible access token from the authorization server and include it in each protected Web Services Manager SOAP invocation. See "About WSDL Files and BRM Opcodes" for the service endpoint URLs and SOAP operation request structure.

The following SOAP 1.1 example uses the recommended HTTP Bearer header. Replace soapEndpointURL with the HTTPS service endpoint URL, replace accessToken with the access token, and insert the SOAP operation request in the Body element:

curl -i --request POST \
  'soapEndpointURL' \
  --header 'Content-Type: text/xml;charset=UTF-8' \
  --header 'Authorization: Bearer accessToken' \
  --data '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header/>
  <soapenv:Body>
    <!-- Insert the SOAP operation request. -->
  </soapenv:Body>
</soapenv:Envelope>'

For compatibility with an existing client that cannot yet send the HTTP Bearer header, the following SOAP 1.1 example sends the access token through the deprecated SOAP <code> header. Replace soapEndpointURL with the HTTPS service endpoint URL, replace accessToken with the access token, and insert the SOAP operation request in the Body element.

curl -i --request POST \
  'soapEndpointURL' \
  --header 'Content-Type: text/xml;charset=UTF-8' \
  --data '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bus="http://xmlns.oracle.com/BRM/schemas/BusinessOpcodes">
  <soapenv:Header>
    <bus:code>accessToken</bus:code>
  </soapenv:Header>
  <soapenv:Body>
    <!-- Insert the SOAP operation request. -->
  </soapenv:Body>
</soapenv:Envelope>'