Billing Care REST API Security

8 Billing Care REST API Security

The Oracle Communications Billing Care REST API supports stringent authorization and authentication requirements. Learn how to implement the security capabilities supported by Billing Care REST API.

Topics in this document:

For more information, see REST API Reference for Billing Care.

About Authentication and Authorization

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

Your client must pass this OAuth access token in the header of every HTTP/HTTPS request sent to the Billing Care REST API.

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

Setting Up OAuth with Oracle Identity Cloud Service

You can set up your client application to use OAuth authentication to access the Billing Care REST API. The client application uses the resource owner's credentials to access the resource server.

The high-level steps for setting up OAuth authentication using Oracle Identity Cloud Service (IDCS) includes the following:

Afterwards, you must request an access token for each client application that will submit REST requests to the Billing Care REST API. See "Requesting an OAuth Access Token".

Note:

Authentication is required for production systems only. In test systems, you can submit requests without configuring authentication.

Creating a Confidential OAuth Application for the Resource Server

When you create a confidential OAuth application in Oracle Identity Cloud Service (IDCS), 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 Billing Care REST API.

To create a confidential OAuth application in IDCS:

In the Identity Cloud Service console, expand the Navigation Drawer and then click Applications.
Click Add application.

The Add Application page appears.
Select Confidential Application and then click Launch workflow.

The Add Confidential Application page appears.
In the Name field, enter a name for your application, such as BCREST.
Click Next.
In the Resource server configuration section, do the following:
1. Select the Configure this application as a resource server now option.
2. In the Access token expiration field, enter how long in seconds the access token remains valid.
3. In the Primary audience field, enter the primary recipient where the access token of your confidential application is processed.
4. Select the Add scopes option.
5. In the Scopes table, click Add.
  
  The Add Scope dialog box appears.
6. In the Scope field, enter BillingCare.
7. Click Add.
In the Client configuration section, select the Configure this application as a client now option.
In the Authorization section, do the following:
1. In the Allowed Grant Types field, select the Client credentials option.
2. In the Client Type field, select the Confidential option.
3. In the Allowed Operations field, select the Introspect check box.
Click Next.
Under Web tier policy, select the Skip and do later option.
Click Finish.
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.
Click Activate and then click Activate application to confirm the activation.

Creating a Confidential OAuth Application for Your Client Application

To create a confidential OAuth application in IDCS for your client application:

In the Identity Cloud Service console, expand the Navigation Drawer and then click Applications.
Click Add application.

The Add Application page appears.
Select Confidential Application and then click Launch workflow.

The Add Confidential Application page appears.
In the Name field, enter a name for your application, such as BCRESTClient1.
Click Next.
In the Resource server configuration section, select the Skip for later option.
In the Client configuration section, select the Configure this application as a client now option.
In the Authorization section, do the following:
1. In the Allowed Grant Types field, select the Client credentials option.
2. In the Client Type field, select the Confidential option.
3. Select the Add resources option.
4. In the Resources table, click Add scope.
  
  The Add Scope dialog box appears.
5. In the Resource field, enter ResourceServerBillingCare.
6. Click Add.
Click Next.
Under Web tier policy, select the Skip and do later option.
Click Finish.
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.
Click Activate and then click Activate application to confirm the activation.

Encoding the Client's Credentials in Base64 Format

To request OAuth access tokens for accessing the Billing Care REST API, your client application will need the client ID and client secret encoded 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.

Configuring OAuth Settings Using IDCS

To configure OAuth to connect to your BRM server using IDCS:

Open the User_home/Infranet.properties file in a text editor, where User_home is the domain administrative user's home directory.
Add this entry:
```
idp.vendor=IDCS
idp.url=IDCS_hostname:port
idp.resource_server.scope=ResourceserverScopename
```
where:
- IDCS_hostname:port is the host and port number of the IDCS Server that is running your application.
- ResourceserverScopename is the name of the resource server concatenated with the name of the scope.
  
  Note:
  
  You entered the resource server name in the Primary Audience field of step 6, and you entered the scope name in the Scope field of step 6.
Save and close the file.

Storing the Resource Server's Credentials in the Wallet

IDCS needs your resource server's client credentials to validate OAuth authentication requests. To improve security, store the resource server's client ID and client secret in the Oracle wallet so IDCS can retrieve it when needed.

To store the resource server's client credentials in the Oracle wallet:

Go to the BRM_home/bin directory.
Store the client ID by running this command:
```
java -cp "JarLocationUnderInstallHome/oraclepki.jar:JarLocationUnderInstallHome/osdt_cert.jar:JarLocationUnderInstallHome/osdt_core.jar:JarLocationUnderInstallHome/cet.jar" com.portal.cet.ConfigEditor -setconf -wallet WalletLocation -parameter idp.client.id -value "ClientIdValue"
```
where:
- JarLocationUnderInstallHome is the directory in which Java is installed in your Billing Care REST API installation.
- WalletLocation is the directory in which the Oracle wallet resides.
- ClientIdValue is the client ID.
At the Enter password for the wallet prompt, enter your client wallet password.

Store the client secret by running this command:

java -cp "JarLocationUnderInstallHome/oraclepki.jar:JarLocationUnderInstallHome/osdt_cert.jar:JarLocationUnderInstallHome/osdt_core.jar:JarLocationUnderInstallHome/cet.jar" com.portal.cet.ConfigEditor -setconf -wallet WalletLocation -parameter idp.client.secret [-pwd]

At the Enter password for the wallet prompt, enter your client wallet password.
At the Enter the value prompt, enter the client secret to store in the wallet.

Requesting an OAuth Access Token

To request an OAuth access token, use cURL to send an HTTP/HTTPS request to the Billing Care REST API authorization endpoint. For example:

curl --location --request GET 'http://hostname:port/bcws/webresources/v1.0/authentication/queryAccessToken' \
     --header 'Authorization: Basic credentials'

where:

hostname:port is the IP address or host name and port of the Billing Care REST API server.
credentials is the Base64-encoded value of your IDCS administrator user name and password joined by a single colon (username:password).

If the request is successful, the token type and access token are returned. For example:

{
    "token_type": "Bearer",
    "access_token": "accessToken"
}

Your client must pass this OAuth access token in the header of every HTTP/HTTPS request sent to the Billing Care REST API.

Setting Up OAuth with Oracle Access Management

The Oracle Communications Billing Care REST API uses OAuth 2.0 to authenticate requests from clients. Perform the following one-time tasks to configure OAuth and Oracle WebLogic Server for authentication:

Afterwards, you must request an access token for each client application that will submit REST requests to the Billing Care REST API. See "Requesting an OAuth Access Token".

Note:

Authentication is required for production systems only. In test systems, you can submit requests without configuring authentication.

Configuring OAuth Services

To use OAuth 2.0 for authentication, configure your Billing Care REST API services and then register your client application as a trusted client on Oracle Access Manager.

To configure OAuth services using Oracle Access Manager:

Create an identity domain, which controls the authentication and authorization of your client applications. It also controls which features your client application can access in relation to the service.

To create an identity domain, use cURL to send an HTTP/HTTPS request to the Oracle Access Management URL. For example:
```
curl -i 
     -H "Content-Type: application/json"
     -H "Accept: application/json"
     -H "Authorization:Basic credentials"
     -X POST 
     http(s)://hostname:port/oam/services/rest/ssa/api/v1/oauthpolicyadmin/oauthidentitydomain
     -d '{
         "name": "identityDomain",
         "description": "Description for Billing Care REST API Identity Domain",
         "tokenSettings":[
             {
                 "tokenType": "ACCESS_TOKEN",
                 "tokenExpiry": tokenExpiry
             }
         ]
     }'
```
where:
- credentials is the Base64-encoded value of your Oracle Access Manager administrator user name and password joined by a single colon (username:password).
- hostname:port is the host and port of the Oracle Access Manager Administration Server.
- identityDomain is the name of the Oracle Access Manager identity domain that you want to create.
- tokenExpiry is the number of seconds before the token expires, such as 3600 for one hour.
See "Add a new OAuth Identity Domain" in REST API for OAuth in Oracle Access Manager for more information.

Create a resource server, which hosts protected resources and accepts and responds to protected resource requests using access tokens.

To create and configure your resource server, use cURL to send an HTTP/HTTPS request to the Oracle Access Management URL. For example:

curl -i
     -H "Content-Type: application/json"
     -H "Authorization:Basic credentials"
     -X POST
     http(s)://hostname:port/oam/services/rest/ssa/api/v1/oauthpolicyadmin/application
     -d '{
         "name": "resourceServer",
         "idDomain": "identityDomain",
         "description": "Billing Care REST API Resource Server",
         "scopes":[
             {
                 "scopeName":"scopeName",
                 "description":"All Access"
             }
         ]
     }'

where:

resourceServer is the name of your resource server, such as BillingCare.
scopeName is the name of the scope, such as All.

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

Create a client application that makes protected resource requests on behalf of the resource owner and with the resource owner's authorization. Billing Care REST API clients are web applications with an OAuth 2.0 client type of Confidential Client. Clients must use a grant type of Client Credentials for requesting access to Billing Care REST API resources.

To create a client application, use cURL to send an HTTP/HTTPS request to the Oracle Access Management URL. For example:
```
curl -i
     -H "Content-Type:application/json"
     -H "Authorization:Basic credentials"
     -X POST
     http(s)://hostname:port/oam/services/rest/ssa/api/v1/oauthpolicyadmin/client
     -d '{
         "secret": "client_secret",
         "id": "client_id",
         "name": "clientName",
         "scopes": [
             "resourceServer.scopeName"
         ],
         "clientType": "CONFIDENTIAL_CLIENT",
         "idDomain": "identityDomain",
         "description": "Description of client of Billing Care REST API Server",
         "grantTypes":[
             "CLIENT_CREDENTIALS"
         ],
         "defaultScope": "resourceServer.scopeName",
         "redirectURIs": [
             {
                 "url":"http(s)://BillingCareHost:BillingCarePort/bcws",
                 "isHttps": isHttps
             }
         ]
     }'
```
where:
- client_secret is the password for your client.
- client_id is the client ID for your client. It will be generated automatically if not specified.
- clientName is the name of your client.
- BillingCareHost:BillingCarePort is the host and port of the Billing Care REST API Server.
- isHttps is a Boolean value that specifies whether the URL is accessed over HTTPS (true) or HTTP (false).
See "Add a new OAuth Client" in REST API for OAuth in Oracle Access Manager for more information.

Configuring WebLogic Server to Access LDAP Server

To configure your WebLogic Server to access user details on the LDAP server:

Update your Java policy store configuration for the Billing Care REST API to access the LDAP server.

You deploy Billing Care on a JRF-enabled Oracle WebLogic Server domain configured as an Oracle Platform Security Services (OPSS) client domain. Create a JRF-enabled domain in Oracle WebLogic Server and configure an application domain policy that controls access to the Billing Care application.

For creating the domain and configuring the domain policy, see "Configuring the Oracle Fusion Middleware Infrastructure Domain" in Oracle Fusion Middleware Installing and Configuring the Oracle Fusion Middleware Infrastructure.

In the config.xml file, set this entry to false. This configures WebLogic Server to skip basic authentication.

<domain>
    <security-configuration>
        <!-- Other configurations -->
        <enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-credentials>
    </security-configuration>
</domain>

Configuring OAuth Settings Using Oracle Access Management

To configure OAuth to connect to your BRM server using Oracle Access Management:

Open the User_home/Infranet.properties file in a text editor, where User_home is the domain administrative user's home directory.
Add this entry:
```
idp.vendor=OAM
idp.url=OAM_hostname:port
idp.resource_server.scope=ResourceServer.ScopeName
idp.identity_domain=IdentityDomain
```
where:
- OAM_hostname:port is the host and port number of the Oracle Access Manager Managed Server that is running the oam_server application.
- Resourceserver.Scopename is the name of the resource server followed by the name of the scope.
- IdentityDomain is the name of your identity domain.
Save and close the file.

Requesting an OAuth Access Token

To request an OAuth access token, use cURL to send an HTTP/HTTPS request to the Billing Care REST API authorization endpoint. For example:

curl --location --request GET 'http://hostname:port/bcws/webresources/v1.0/authentication/queryAccessToken' \
     --header 'Authorization: Basic credentials'

where:

hostname:port is the IP address or host name and port of the Billing Care REST API server.
credentials is the Base64-encoded value of your IDCS administrator user name and password joined by a single colon (username:password).

If the request is successful, the token type, expiry time, and access token are returned. For example:

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

The token expires after the number of seconds shown in expires_in. This value is set while setting up the OAuth identity domain as described in "Configuring OAuth Settings Using Oracle Access Management". After the token expires, you must request a new one.

You use the token in the Authorization header for each REST request with the following format:

-H  "Authorization: Bearer accessToken"