9 BRM REST Services Manager Security

Oracle Communications Billing and Revenue Management (BRM) REST Services Manager supports stringent authorization and authentication requirements. Learn how to implement the security capabilities supported by BRM REST Services Manager.

Topics in this document:

• About Authentication and Authorization

• Setting Up OAuth with Oracle Identity Cloud Service

• Setting Up OAuth using Oracle Access Management

• Scopes and Roles for Accessing REST Services Manager

For more information, see REST Services Manager API for Billing and Revenue Management.

About Authentication and Authorization

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

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

To set up authentication and authorization for your client, you can use either Oracle Identity Cloud Service or Oracle Access Management.

Setting Up OAuth with Oracle Identity Cloud Service

You can set up your client application to use two-legged or three-legged OAuth authentication to access the BRM REST Services Manager API. Three-legged OAuth authentication allows the resource owner to give the client application access to the resource server without sharing its credentials. In two-legged authentication, the client application uses the resource owner's credentials to access the resource server.

To set up three-legged OAuth authentication using Oracle Identity Cloud Service, perform all of the following steps. To set up two-legged OAuth authentication, skip steps 2 and 3.

1. Creating Confidential OAuth Applications

2. Assigning Users to Groups (3-Legged OAuth Only)

3. Generating an Authorization Code (3-Legged OAuth Only)

4. Encoding the Client ID and Client Secret in Base64 Format

5. Requesting an OAuth Access Token

If you are using three-legged OAuth authentication, you can refresh your access token after it expires. See "Refreshing OAuth Access Tokens (3-Legged OAuth Only)".

Creating Confidential OAuth Applications

When you create a confidential OAuth application in Identity Cloud Service, it provides you with a client ID and client secret. Your client will need the client ID and client secret to request OAuth access tokens for accessing the BRM REST Services Manager API.

To create a confidential OAuth application in Identity Cloud Service:

1. In the Identity Cloud Service console, expand the Navigation Drawer and then click Applications.

2. Click Add.

3. In the Add Application page, click Confidential Application.

4. In the App Details page, enter a name for your application, such as MyClient, and then click Next.

5. In the Client page, select Configure this application as a client now.

6. In the Authorization section, enter the following information:

   • In the Allowed Grant Types field, select Client Credentials, JWT Assertion, Refresh Token, and Authorization Code.

   • Select the Allow non-HTTPS URLs option.

   • In the Redirect URL field, enter the application URL where the user is redirected after authentication.

   • In the Client Type field, select Confidential.

   • In the Allowed Operations field, select Introspect.

   This figure shows how to set the fields in the Authorization section:

   
   

   
   Description of the illustration idcs_scopes.png

   
   

7. In the Token Issuance Policy section, do the following:

   1. In the Authorized Resources field, select Specific.

   2. Under Grant the client access to Identity Cloud Service Admin APIs, select Add.

   3. In the Add App Role dialog box, select the following:

      • Application Administrator

      • Identity Domain Administrator

      • User Administrator

   4. Click Add.

8. Click Next.

9. In the Resources page, select Configure this application as a resource server now.

10. In the Configure application APIs that need to be OAuth protected section, do the following:

    1. In the Access Token Expiration field, enter how long (in seconds) the access token remains valid. For example, enter 3600 for 1 hour.

    2. Select the Is Refresh Token Allowed option.

    3. In the Refresh Token Expiration field, enter how long (in seconds) the refresh token, which is returned with your access token and is associated with your confidential application, remains valid.

    4. In the Primary Audience field, enter the primary recipient where the access token of your confidential application is processed.

    5. Next to Scopes, click Add.

    6. In the Add Scope dialog box, add these scopes: BillingAgent and BillingViewer.

11. Click Back to return to the Resources page.

12. In the Token Issuance Policy section of the Resources page, do the following:

    1. Under Resources, click Add Scope.

    2. In the Select Scope dialog box, next to the name of your application, select the icon.

    3. Select the BillingAgent and BillingViewer scopes.

    4. Click Add.

13. Click Next to advance to the Resources page.

14. Click Next again to advance to the Authorization page.

15. Click Finish.

16. In the Application Added pop-up window, make note of the client ID and client secret. You will provide this to the person who needs to generate the OAuth access token.

17. Click Close.

18. At the top right of the application page, select Activate and then click OK to confirm the activation.

19. Provide the following to the person who needs to generate the OAuth access token:

    • The Identity Cloud Service URLs for generating authorization codes and requesting access tokens. For example:

      https://idcs_hostname/oauth2/v1/authorize

      https://idcs_hostname/oauth2/v1/token

      where idcs_hostname is the hostname of the server of your Identity Cloud Service instance

    • The redirect URL to send authorization codes and access tokens to

    • The client ID and client secret

Assigning Users to Groups (3-Legged OAuth Only)

If your client application is using three-legged OAuth authentication, users are granted access to the BRM REST Services Manager API through Oracle Identity Cloud Service groups. To grant users access, you first create the groups in Identity Cloud Service and then assign users to those groups.

To create the Billing Viewer and Billing Agent groups in Identity Cloud Service:

1. In the Identity Cloud Service console, expand the Navigation Drawer and then click Groups.

2. In the top left, click Add.

3. In the Add Group dialog box, in the Name field, enter Billing Agent.

4. Click Finish.

5. In the top left, click Add again.

6. In the Add Group dialog box, in the Name field, enter Billing Viewer.

7. Click Finish.

To assign users to the appropriate group for accessing the BRM REST Services Manager API:

1. In the Identity Cloud Service console, expand the Navigation Drawer and then click Users.

2. Select a user that needs access to the BRM REST Services Manager API.

3. In the user's page, select Groups at the top left.

4. In the Groups page, click Assign.

5. In the Assign Groups dialog box, select Billing Agent, Billing Viewer, or both. For more information about the groups, see "Scopes and Roles for Accessing REST Services Manager".

6. Click OK.

Generating an Authorization Code (3-Legged OAuth Only)

If you are using three-legged OAuth authentication, you must include an authorization code in your request for an OAuth access token. To generate an authorization code, use a browser to send an HTTP/HTTPS request to the Identity Cloud Service URL:

https://idcs_hostname/oauth2/v1/authorize?client_id=client_id&response_type=code&redirect_uri=redirect_url&scope=BillingAgent BillingView all offline_access

where:

• idcs_hostname is the hostname of your Identity Cloud Service instance.

• client_id is the client ID generated by Identity Cloud Service when you created a confidential application.

• redirect_url is the URL for your application.

The authorization code is returned with the parameter named “code” in the redirect URL. Make a note of the authorization code so it can be used to request OAuth access tokens.

For more information, see "Generate Authorization Code and Identity Token (3-legged OAuth Flow)" in REST API for Oracle Identity Cloud Service.

Encoding the Client ID and Client Secret in Base64 Format

Before you can request an OAuth access code, you must encode your client ID and client secret in Base64 format. Generate a base64-encoded value of your client ID and client secret joined by a single colon (ClientID:ClientSecret).

You pass the base64-encoded value in the header of your HTTP/HTTPS request for an OAuth access code.

Requesting an OAuth Access Token

To request an OAuth access token, use cURL to send an HTTP/HTTPS request to the Identity Cloud Service URL. The cURL syntax you use depends on whether you are using two-legged or three-legged OAuth authentication.

• For two-legged OAuth authentication, use this cURL syntax:

  curl -i
  -H "Authorization: Basic encoded_client"
  -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
  --request POST https://idcs_hostname/oauth2/v1/token
  -d 'grant_type=client_credentials&scope=BillingAgent BillingView all'

• For three-legged OAuth authentication, include the authorization code in your HTTP/HTTPS request:

  curl -i
  -H "Authorization: Basic encoded_client"
  -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
  --request POST https://idcs_hostname/oauth2/v1/token
  -d "redirect_uri=redirect_url&grant_type=authorization_code&code=authorization_code"

where:

• encoded_client is the base64-encoded client ID and client secret that you created in "Encoding the Client ID and Client Secret in Base64 Format".

• idcs_hostname is the hostname of your Identity Cloud Service instance.

• redirect_url is the URL for your application.

• authorization_code is the authorization code returned in "Generating an Authorization Code (3-Legged OAuth Only)".

After you submit the request, Identity Cloud Service returns an OAuth access token.

Identity Cloud Service also returns a refresh token if the following are true:

• You are using three-legged OAuth authentication.

• Your OAuth client allows the Refresh Token grant type.

• You included the offline_access scope in your request for an authorization code.

The OAuth access token and refresh token returned from the request follows this syntax:

{
   "access_token":"access_token",
   "token_type":"Bearer","expires_in":3600,
   "refresh_token":"refresh_token"
}

For more information, see "Generate Access Token and Other OAuth Runtime Tokens to Access the Resource" in REST API for Oracle Identity Cloud Service.

Refreshing OAuth Access Tokens (3-Legged OAuth Only)

If you are using three-legged OAuth authentication, you can refresh your access token. To do so, use cURL to send an HTTP/HTTPS request to the Identity Cloud Service URL:

curl -H 'Authorization: Basic encoded_client' -H "Content-Type:application/x-www-form-urlencoded;charset=UTF-8" 
--request POST https://idcs_hostname/oauth2/v1/token -d 'grant_type=refresh_token&refresh_token=refresh_token

where:

• encoded_client is the base64-encoded client ID and client password that you created in "Encoding the Client ID and Client Secret in Base64 Format".

• idcs_hostname is the hostname of your Identity Cloud Service instance.

• refresh_token is the refresh token that was returned when you requested an access token in "Requesting an OAuth Access Token".

For more information, see "Generate Access Token and Other OAuth Runtime Tokens to Access the Resource" in REST API for Oracle Identity Cloud Service.

Setting Up OAuth using Oracle Access Management

Setting up OAuth using Oracle Access Management involves these high-level steps:

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

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

2. Installing the Oracle Unified Directory software with the HTTP port enabled. For the list of supported versions, see "Additional BRM Software Requirements" in BRM Compatibility Matrix.

   For more information about installing Oracle Unified Directory, see Oracle Fusion Middleware Installing Oracle Unified Directory.

3. Enabling OAuth Services
4. Creating an OAuth Identity Domain
5. Creating a Resource Server
6. Creating an OAuth Client
7. Create an access token using either two-legged or three-legged OAuth authentication:
   • Using Two-Legged OAuth to Create an Access Token
   • Using Three-Legged OAuth to Create an Access Token

Note:

If you use both BRM REST Services Manager and PDC REST Services Manager, you must set up separate OAuth identity domains, resource servers, and clients for each component.

Enabling OAuth Services

To enable OAuth services in Oracle Access Manager:

1. In the Oracle Access Manager Console, click Configuration at the top of the window.

2. Click Available Services.

3. Confirm that the Access Manager service is enabled.

4. In the OAuth Service row, click Enable Service.

5. In the OpenIDConnect Service row, click Enable Service.

For more information, see "Available Services of the Common Configuration Section" in Oracle Fusion Middleware Administering Oracle Access Management.

Creating an OAuth Identity Domain

You create an OAuth identity domain to control the authentication and authorization of users who can sign in to BRM REST 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 --header 'Content-Type: application/json' 
--header 'Authorization:Basic encoded_admin' 
--header 'Cookie: JSESSIONID=Ax_wYZQ2svzaTYpH5Gwz4KTwqfD2toL1tEi2hzkuTSAK8KVuf0aw!642164469'  
--request POST http//:oam_host:oam_port/oam/services/rest/ssa/api/v1/oauthpolicyadmin/oauthidentitydomain 
--data-raw '{"name":"identity_domain","identityProvider":"identity_store","description":"My Identity Domain",
{"tokenType":"AUTHZ_CODE","tokenExpiry":3600,"lifeCycleEnabled":false,"refreshTokenEnabled":false,"refreshTokenExpiry":86400,"refreshTokenLifeCycleEnabled":false}, 
{"tokenType":"SSO_LINK_TOKEN","tokenExpiry":3600,"lifeCycleEnabled":false,"refreshTokenEnabled":false,"refreshTokenExpiry":86400,"refreshTokenLifeCycleEnabled":false}'

where:

• encoded_admin is the base64-encoded format of the Oracle Access Management administrator user name and password.

• oam_host:oam_port is the host name and port for the Oracle Access Management server.

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

• identity_store is set to your Oracle Unified Directory.

The following shows an example cURL command for creating an identity domain named TMF_ID_Domain with the identity store set to OUD:

curl -i --header 'Content-Type: application/json' 
--header 'Authorization: Basic encoded_admin' 
--header 'Cookie: JSESSIONID=Ax_wYZQ2svzaTYpH5Gwz4KTwqfD2toL1tEi2hzkuTSAK8KVuf0aw!642164469'  
--request POST 'http://oam_host:oam_port/oam/services/rest/ssa/api/v1/oauthpolicyadmin/oauthidentitydomain'
--data-raw '{"name":"TMF_ID_Domain","identityProvider":"OUD","description":"My Identity Domain",
"tokenSettings":[{"tokenType":"ACCESS_TOKEN","tokenExpiry":3600,"lifeCycleEnabled":false,"refreshTokenEnabled":false,"refreshTokenExpiry":86400,"refreshTokenLifeCycleEnabled":false},
{"tokenType":"AUTHZ_CODE","tokenExpiry":3600,"lifeCycleEnabled":false,"refreshTokenEnabled":false,"refreshTokenExpiry":86400,"refreshTokenLifeCycleEnabled":false},
{"tokenType":"SSO_LINK_TOKEN","tokenExpiry":3600,"lifeCycleEnabled":false,"refreshTokenEnabled":false,"refreshTokenExpiry":86400,"refreshTokenLifeCycleEnabled":false}],
"errorPageURL":"/oam/pages/servererror.jsp","consentPageURL":"/oam/pages/consent.jsp"}'

If the identity domain was created successfully, you will see a response similar to this:

Sucessfully created entity - OAuthIdentityDomain, detail - OAuth Identity Domain :: Name - TMF_ID_Domain, Id - 19f85bc53b49561ea52f039474c2c4b, Description - My
Identity Domain, TrustStore Identifiers - TMF_ID_Domain,Identity Provider - OUD, TokenSettings -
[{"tokenType":"ACCESS_TOKEN","tokenExpiry":3600,"lifeCycleEnabled":false,"refreshTokenEnabled":false,"refreshTokenExpiry":86400,"refreshTokenLifeCycleEnabled":false},
{"tokenType":"AUTHZ_CODE","tokenExpiry":3600,"lifeCycleEnabled":false,"refreshTokenEnabled":false,"refreshTokenExpiry":86400,"refreshTokenLifeCycleEnabled":false},
{"tokenType":"SSO_LINK_TOKEN","tokenExpiry":3600,"lifeCycleEnabled":false,"refreshTokenEnabled":false,"refreshTokenExpiry":86400,"refreshTokenLifeCycleEnabled":false}],
ConsentPageURL - /oam/pages/consent.jsp, ErrorPageURL -  /oam/pages/servererror.jsp, CustomAttrs - null

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 -k -u wls_admin:password -H 'Content-Type: application/json' 'http://oam_host:oam_port/oam/services/rest/ssa/api/v1/oauthpolicyadmin/application'
-d '{"name":"resource_server","description":"TestResourceServer",
"scopes":[{"scopeName":"scope1","description":"Scope1 description"},{"scopeName":"scope2","description":"Scope2 sescription"},{"scopeName":"scope3","description":"Scope3 description"}],
"tokenAttributes":[{"attrName":"sessionId","attrValue":"$session.id","attrType":"DYNAMIC"},{"attrName":"resSrvAttr","attrValue":"RESOURCECONST","attrType":"STATIC"}],"idDomain":"TestDomain1","audienceClaim":{"subjects":["ab0"]}}' 

where:

• wls_admin:password is the Admin user name and password for WebLogic Server.

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

• scopeN is the name of a scope. After the scopes are defined under the resource server, refer to them as resource_server.scope. For example: TMFResourceServer.BillingAgent. For information about the scopes, see "Scopes and Roles for Accessing REST Services Manager".

The following shows an example of creating a resource server named TMFResourceServer with the BillingAgent and BillingViewer scopes, an identity domain named TMF_ID_Domain, and static and dynamic customer attributes:

curl -k -u wls_admin:password -H 'Content-Type: application/json' 'http://oam_host:oam_port/oam/services/rest/ssa/api/v1/oauthpolicyadmin/application'
-d '{"name":"TMFResourceServer","description":"Resource Server",
"scopes":[{"scopeName":"BillingAgent","description":"Scope for CSR with BillingAgent Role"},{"scopeName":"BillingViewer","description":"Scope for CSR with BillingViewer Role"},
"tokenAttributes":[{"attrName":"sessionId","attrValue":"$session.id","attrType":"DYNAMIC"},{"attrName":"resSrvAttr","attrValue":"RESOURCECONST","attrType":"STATIC"}],"idDomain":"TMF_ID_Domain","audienceClaim":{"subjects":["ab0"]}}'

If the resource server is created successfully, you will see a response similar to this:

Sucessfully created entity - OAuthResourceServer, detail - IdentityDomain="TMF_ID_Domain",Name="TMFResourceServer",Description="Resource Server",
resourceServerId="4953a4f4-8c3f-41fd-99b5-837cfa9f9ecb",resourceServerNameSpacePrefix="TMFResourceServer.",audienceClaim="{"subjects":["ab0"]}",
resServerType="CUSTOM_RESOURCE_SERVER",Scopes="[{"scopeName":"BillingAgent","description":"Scope for CSR with BillingAgent Role"},  
{"scopeName":"BillingAgent","description":"Scope for CSR with  BillingAgent Role"}, {"scopeName":"BillingViewer","description":"Scope for CSR with BillingViewer Role"},}]",
tokenAttributes="[{"attrName":"sessionId","attrValue":"$session.id","attrType":DYNAMIC},{"attrName":"resSrvAttr","attrValue":"RESOURCECONST","attrType":STATIC}]

Creating an OAuth Client

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

curl -k -u wls_admin:password -H 'Content-Type: application/json' 'http://oam_host:oam_port/oam/services/rest/ssa/api/v1/oauthpolicyadmin/client' 
-d {"attributes":[{"attrName":"custom_attribute","attrValue":"custom_value","attrType":"static"}],
"secret":"client_secret","id":"clientID","scopes":["resource_server.scope1"],"clientType":"CONFIDENTIAL_CLIENT",
"idDomain":"identity_domain","description":"Client Description","name":"client_name","grantTypes":["PASSWORD","CLIENT_CREDENTIALS","JWT_BEARER","REFRESH_TOKEN","AUTHORIZATION_CODE"],
"defaultScope":"resource_server.scope1","redirectURIs":[{"url":"http://redirect_host:redirect_port/Sample.jsp","isHttps":true}]}

where:

• custom_attribute and custom_value are custom attribute names and values. You can optionally define a set of static and dynamic custom attributes, which will then be added as custom attributes to the OAuth access token.

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

• redirect_host:redirect_port is the URL for your client application.

The following shows an example cURL request for creating a confidential OAuth client named TMFClient with the TMFResourceServer:BillingAgent (default) and TMFResourceServer:BillingViewer scopes, and an identity domain named TMF_ID_Domain.

curl -k -u wls_admin:password -H 'Content-Type: application/json' 'http://oam_host:oam_port/oam/services/rest/ssa/api/v1/oauthpolicyadmin/client'
-d'{"attributes":[{"attrName":"customAttribute1","attrValue":"Custom Value1","attrType":"static"},{"attrName":"customAttribute2","attrValue":"Custom Value2","attrType":"static"}],
"secret":"client_secret","id":"client_id","scopes":["TMFResourceServer.BillingAgent","TMFResourceServer.BillingViewer"],"clientType":"CONFIDENTIAL_CLIENT",
"idDomain":"TMF_ID_Domain","description":"Client entry for identity domain","name":"TMFClient","grantTypes":["PASSWORD","CLIENT_CREDENTIALS","JWT_BEARER","REFRESH_TOKEN","AUTHORIZATION_CODE"],
"defaultScope":"TMFResourceServer.BillingAgent","redirectURIs":[{"url":"http://redirect_host:redirect_port/oauth/callback","isHttps":true}]}'

If the client is created successfully, the response will be similar to this:

Sucessfully created entity - OAuthClient, detail - OAuth Client - uid = 4b37dd63-08dd-45b5-b5a5-c1e788cb2ff2, name = TMFClient, id =  TMFClientId,
identityDomain = TMF_ID_Domain, description = Client  entry for TMF OAuth Domain,secret = TMFPassword, clientType = CONFIDENTIAL_CLIENT, grantTypes = [PASSWORD,
CLIENT_CREDENTIALS, JWT_BEARER, REFRESH_TOKEN, AUTHORIZATION_CODE], attributes =
[{"attrName":"customAttribute1","attrValue":"Custom  Value1","attrType":STATIC},{"attrName":"customAttribute2","attrValue":"Custom  Value2","attrType":STATIC},
{"attrName":"sessionId","attrValue":"session.id","attrType":DYNAMIC},{"attrName":"resSrvAttr","attrValue":"RESOURCECONST","attrType":STATIC}],  scopes =
[TMFResourceServer.BillingAgent, TMFResourceServer.BillingViewer], defaultScope = TMFResourceServer.BillingAgent, redirectURIs = [{"url":"http://redirect_host:redirect_port/oauth/callback","isHttps":true}]

Using Two-Legged OAuth to Create an Access Token

You create an access token for two-legged OAuth authentication by using the Oracle Access Management OAuth REST API. You submit a request by using its Create Access Token Flow endpoint. For more information, see REST API for OAuth in Oracle Access Manager.

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

curl -i --header 'Authorization: Basic encoded_admin' \
        --header "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
        --header "X-OAUTH-IDENTITY-DOMAIN-NAME: identity_domain" \
        --request POST http://oam_host:oam_port/oauth2/rest/token \
        --data-urlencode "grant_type=CLIENT_CREDENTIALS&scope=resource_server.scope"

The following shows an example cURL request for creating a creating OAuth access token for the TMF_ID_Domain identity domain, TMFResourceServer resource server, and BillingAgent scope:

curl --location --header 'Authorization: Basic encoded_admin' \
     --header "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
     --header "X-OAUTH-IDENTITY-DOMAIN-NAME: TMF_ID_Domain" \
     --request POST http://oam_host:oam_port/oauth2/rest/token \
     --data-urlencode "grant_type=CLIENT_CREDENTIALS&scope=TMFResourceServer.BillingAgent"

If the request is successful, Oracle Access Management returns something similar to this:

{
   "access_token":"access_token",
   "token_type":"Bearer",
   "expires_in":3600
}

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

Using Three-Legged OAuth to Create an Access Token

You create an access token for three-legged OAuth authentication by doing the following:

1. Creating protected resources in the Oracle Access Management server. See "Creating Resources in the Oracle Access Management Server".

2. Modifying the WebGate mod_wl_ohs.conf file so the Oracle HTTP server can connect to the WebLogic Server. See "Configuring the Oracle HTTP Server".

3. Generating an OAuth access token. See "Generating the OAuth Access Token".

Creating Resources in the Oracle Access Management Server

In three-legged OAuth authentication, you must create resources in the Oracle Access Management server for protecting the consent page and approval page. If you customize the consent page, it must be protected by a Webgate.

To create resources on your Oracle Access Management server:

1. In the Oracle Access Management Console, click Application Security.

2. In the Application Security console, click Application Domains.

3. Search for and open your application domain.

4. Click the Resources tab.

5. Create a protected resource named /oauth2/rest/approval. This has to be protected by WebGate.

   Click Create, do the following in the Create Resource screen, and then click Apply:

   • Resource URL: Enter /oauth2/rest/approval.

   • Operations Available: Select POST.

   • Protection Level: Select Protected.

   • Authentication Policy: Select Protected HigherLevel Policy.

   • Authorization Policy: Select Protected Resource Policy.

6. Create a protected resource named /oam/pages/consent.jsp. If you are using a custom consent page, it needs to be protected by Webgate and the appropriate resource has to be added here.

   Click Create, do the following in the Create Resource screen, and then click Apply:

   • Resource URL: Enter /oam/pages/consent.jsp.

   • Operations Available: Select GET.

   • Protection Level: Select Protected.

   • Authentication Policy: Select Protected Resource Policy.

   • Authorization Policy: Select Protected Resource Policy.

7. Create an excluded resource named /oauth2/rest/**.

   Click Create, do the following in the Create Resource screen, and then click Apply:

   • Resource URL: Enter /oauth2/rest/**.

   • Protection Level: Select Excluded.

8. Create an excluded resource named /oam/**.

   Click Create, do the following in the Create Resource screen, and then click Apply:

   • Resource URL: Enter /oam/**.

   • Operations Available: Select ALL.

   • Protection Level: Select Excluded.

Configuring the Oracle HTTP Server

To configure the Oracle HTTP Server for WebLogic Server, modify the WebGate mod_wl_ohs.conf file:

1. Open the OHS_home/user_projects/domains/base_domain/config/fmwconfig/components/OHS/OHS_InstanceName/mod_wl_ohs.conf file in a text editor.

   where:

   • OHS_home is the path to the Oracle HTTP Server directory.

   • OHS_InstanceName is the name of your Oracle HTTP Server instance.

2. Add the following entries to the file:

   <Location /oauth2>       
      SetHandler weblogic-handler       
      WebLogicHost  ManagedServerHostName       
      WebLogicPort  ManagedServerPort       
      ErrorPage  http:/WEBLOGIC_HOME:WEBLOGIC_PORT/   
   </Location>   
   
   <Location /oam>       
      SetHandler weblogic-handler       
      WebLogicHost  ManagedServerHostName       
      WebLogicPort  ManagedServerPort       
      ErrorPage  http:/WEBLOGIC_HOME:WEBLOGIC_PORT/  
   </Location>

3. Save and close the file.

Generating the OAuth Access Token

Generating an OAuth access token is a two-step process. First, you retrieve an authorization code from Oracle Access Manager. Then, you include the authorization code in a request to the Oracle Access Manager REST API for an OAuth access token.

To generate an OAuth access token:

1. Open the following URL in a browser:

   http://OHS_host:OHS_port/oauth2/rest/authorize?response_type=code&domain=identity_domain&client_id=client_name&scope=resource_server.BillingAgent&state=code1234&redirect_uri=http://redirect_host:redirect_port/oauth/callback

2. Enter your user credentials in the Oracle Access Manager login screen.

3. Click Allow.

4. Copy the authorization code from the browser URL.

5. Generate the OAuth access token by submitting a cURL request to the Create Access Token Flow endpoint in the Oracle Access Manager OAuth REST API. For example:

   curl --location --request POST 'http://oam_host:oam_port/14100/oauth2/rest/token' \ 
        --header 'X-OAUTH-IDENTITY-DOMAIN-NAME: identity_domain' \
        --header 'Authorization: Basic encoded_admin' \
        --header 'Content-Type: application/x-www-form-urlencoded' \
        --data-urlencode 'grant_type=AUTHORIZATION_CODE' --data-urlencode 'code=authorization_code' \
        --data-urlencode 'redirect_uri=http://redirect_host:redirect_port/oauth/callback'

   For more information, see REST API for OAuth in Oracle Access Manager.

Scopes and Roles for Accessing REST Services Manager

For two-legged OAuth authentication, use the scopes in Table 9-1 to control access to the REST Services Manager API and SDK.

Table 9-1 Scopes for BRM REST Services Manager

Scope Name	Description
BillingAgent	Authorizes access to all BRM REST Services Manager APIs.
BillingViewer	Authorizes only GET requests for all BRM REST Services Manager endpoints.

For three-legged OAuth authentication, use the roles (groups) listed in Table 9-2 to control access to the REST Services Manager API and SDK.

Table 9-2 Roles for BRM REST Services Manager

Role Name	Description
Billing Agent	Authorizes access to all BRM REST Services Manager APIs.
Billing Viewer	Authorizes only GET requests for all BRM REST Services Manager endpoints.