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.
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:
-
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.
-
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. See "Configuring Web Services Manager".
-
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:
-
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.
-
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.
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: 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".
-
-
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>'
-