REST API for Oracle Enterprise Data Management Cloud Service

Authentication with OAuth 2 - Only for OCI (Gen 2) Environments

In EPM Cloud environments on Oracle Cloud Infrastructure (OCI) / Gen 2 architecture, you can use an OAuth 2 access token to issue REST APIs on EPM Cloud to satisfy the requirement of avoiding the use of passwords in your environment.

Setting Up Authentication with OAuth 2

In order to access EPM Cloud REST APIs with OAuth 2, an EPM Cloud Service Administrator has to request the Domain Administrator to set up an OAuth 2 client and provide the Identity Domain Cloud Service (IDCS) URL, application scope, and Client ID.

The Domain Administrator registers the REST API client following the procedure described below.

The first step is to update the service provider configuration to authorize requests from the REST client application. As a security measure, any client application that accesses Oracle Cloud resources must be authorized to do so. A domain administrator provides this authorization by registering a client and providing the appropriate registration information to the client's users.

Clients can be public (outside a data center) or confidential. Public clients are assigned a client_id. Confidential clients also have a client secret in addition to a client_id. Clients are also authorized to access particular scopes. The type of application you select determines the allowed grant types available to request access tokens.

Client applications require an access token in order to access server resources. To obtain an access token, the client implements one of the IDCS supported access grant types as listed here. The choice of access grant type to implement is based on the requirements and desired functionality of the REST API client.

The next section highlights the steps to create a sample public OAuth 2 client that accesses the EPM Cloud Get Daily Maintenance Window REST API.

For details, see the Oracle Identity Cloud Service documentation:

The Identity Cloud Service domain administrator follows the steps in this topic to create a public client in the Identity Cloud Service Administrator console for the Application Scope for the requested client. The domain administrator then shares the Identity Cloud Service application URL, application scope, and client ID with the EPM Cloud Service Administrator.

Identity Cloud Service Administrator tasks to register a REST client:

Log in to the Identity Cloud Service Administrator console as a Domain Administrator.
Configure the token properties for protected OAuth 2 REST APIs:
1. From the Applications drawer, click Oracle Cloud Services, and then choose the Cloud Service.
2. On the Configuration tab, under Resources, select the checkbox for Is Refresh Token Allowed.
3. Optional: Change the Access Token Expiration and Refresh Token Expiration. Oracle recommends 3600 (1 hour) as the value of Access Token Expiration and 604,800 (7 days) as the value of Refresh Token Expiration.
4. Click Save on the upper-right to save changes.
From the Applications drawer, click Add at the top of the page.
In the Add Application dialog box, select Mobile Application.
In the App Details section, enter a name for the REST client.
Optional: Add other details.
Click Next.
In the Authorization section, under Allowed Grant Types, select the checkboxes for Refresh Token and Device Code.
Under Token Issuance Policy section, click Add Scope.
1. On the Select Scope dialog box, choose the Resource (EPM Cloud environment) that this client will access. Note the Scope for this Resource.
2. Click Add to close the pop-up.
3. At the top of the page, click Next.
4. Click Finish.
The Application Added dialog box shows the generated client ID. This information also appears on the Configuration tab in the Details section for the application. Click Close.
Click Activate to activate the client, and then click OK.

For details, see the Oracle Identity Cloud Service documentation:

The Domain Administrator provides the IDCS URL, scope (obtained in Step 9.a.) and client ID (obtained in Step 9.d.) to the EPM Cloud Service Administrator.

After the Domain Administrator has registered the REST client and provided the IDCS URL, scope, and client ID, the EPM Cloud Administrator executes the following steps to get a valid refresh token.

EPM Cloud Service Administrator tasks to get a refresh token:

Issue the following unauthenticated request to the Identity Cloud Service URL:

curl --location --request POST 'https://tenant-base-url/oauth2/v1/device' \
--header 'Content-Type: application/x-www-form-urlencoded;charset=utf-8' \
--data-urlencode 'response_type=device_code' \
--data-urlencode 'scope=urn:opc:serviceInstanceID=507199212urn:opc:resource:consumer::all offline_access' \
--data-urlencode 'client_id=75ce2d27564d4432863927946c6bafc7'

Here, the value of tenant-base-url is the IDCS URL provided by the Domain Administrator. Similarly, the values for scope and client_id are also provided by the Domain Administrator.

The response contains a device code, user code, and verification URI:

{
  "expires_in": 300,
  "device_code": "4d03f7bc-f7a5-4795-819a-5748c4801d35",
  "user_code": "SDFGHJKL",
  "verification_uri": "https://tenant-base-url/ui/v1/device"
}

Note: Steps 2 and 3 are time-sensitive because the user code and device code expire 300 seconds (5 minutes) after creation. If the codes expire before these steps can be completed, restart from Step 1.

Open the verification_uri in a web browser.
1. If prompted for credentials, enter the credentials. This can be the credentials stored in IDCS or in a SAML 2.0-based Identity Provider.
2. When prompted for code, enter the user_code from the response payload.
3. When the Successful message is displayed, close the browser window or tab.

Issue the following request to the Identity Cloud Service URL:

curl --location --request POST 'https://tenant-base-url/oauth2/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded;charset=utf-8' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
--data-urlencode 'device_code=4d03f7bc-f7a5-4795-819a-5748c4801d35' \
--data-urlencode 'client_id=75ce2d27564d4432863927946c6bafc7'

Here the value of tenant-base-url is the IDCS URL provided by the Domain Administrator, the device_code value is obtained in Step 1, and client_id is provided by the Domain Administrator.

The response contains a refresh token:

{
    "access_token": "eyJ4NXQjUzI.........evRJChXTRfzn6WlCw",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "AQIDBAWF1.....RVkxNCB7djF9NCA="
}

Note the client_id and refresh_token because they are required in the next step by the REST client.

Use of OAuth 2 in the REST Client

The REST client uses the refresh token and client id to get access token and uses it for accessing REST APIs. It also makes sure that the refresh token, access token, and client ID are stored securely.

Obtain a Valid Access Token

The REST client should use the refresh token grant type to get a new access token and a new refresh token.

To obtain a valid access token, the REST client issues the following request to the IDCS URL:

curl --location --request POST 'https://tenant-base-url/oauth2/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id=75ce2d27564d4432863927946c6bafc7' \
--data-urlencode 'refresh_token=AQIDBAWF1???.FVkxNCB7djF9NCA='

Here the value of tenant-base-url is the IDCS URL provided by the Domain Administrator, the refresh_token value is obtained from the secure store where it was stored in the previous step, and client_id is provided by the Domain Administrator.

Example response:

{
"access_token": "aQj5M4QjUkI.........abSjZaa86PlseS4lrt7R2",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "AAyyilYBAWD4....FVkxefd8kjoJr6HJPA="
}

The REST client saves the refresh token for future use and uses the access token.

Use the Access Token

In order to access an application (environment), the REST client must provide the access token (obtained in the previous step) in the authorization header as follows:

Authorization: Bearer <access token>

For example, to get the Automated Maintenance Window start time, the client application submits a GET request to this endpoint: /interop/rest/v1/services/dailymaintenance using the access token in the authorization header.

curl --location --request GET 'https://tenant-base-url/interop/rest/v1/services/dailymaintenance' \
--header "Authorization: Bearer "aQj5M4QjUkI.........abSjZaa86PlseS4lrt7R2"

Secure and Protect the Tokens and Client_ID

An access token is used instead of user credentials to access the resources on EPM Cloud. A refresh token and client ID are used to get a new access token and a new refresh token. Thus, to ensure security of EPM Cloud, it is important to securely encrypt and store the client_id and all tokens. The REST client must securely store the access token, refresh token, and client_id.

Frequently Asked Questions

Can the expiry time of a refresh token be modified?

The expiry time of the refresh token is configurable in Identity Cloud Service by the Domain Administrator on a per EPM Cloud environment basis. The client requesting the refresh token cannot modify the expiry time or duration. The client should request a new refresh token before the old one expires, in order to not repeat the initial setup again. The default expiry period is 604800 seconds, which is 7 days.

What error is returned when the refresh token has expired?

Executing a refresh token grant flow with an expired refresh token results in a 400 Bad Request response and the following payload:

{  "error": "invalid_grant",
    "error_description": "Token is expired for client : 75ce2d27564d4432863927946c6bafc7",
    "ecid": "UsbMB0KCV00000000"
}

What error is returned when the refresh token is invalid?

Executing a refresh token grant flow with an invalid refresh token results in a 400 Bad Request response and the following payload:

{  "error": "invalid_grant",
    "error_description": "The given token in the request is invalid",
    "ecid": "UsbMB0KCV00000000"
}

What errors are returned for other issues?

A 400 Bad Request response with the following payloads are returned when there is an error:

Invalid request (for example, not all request parameters are supplied):

{
    "error": "invalid_request",
    "error_description": "The request contains invalid parameters or values"
}

Invalid grant (for example, using a token that has already been used) :

{
    "error": "invalid_grant",
    "error_description": "The token has already been consumed"
}

Invalid scope (for example, providing invalid scope):

{
    "error": "invalid_scope",
    "error_description": "Invalid scope"
}

What error is returned when an invalid or expired access token is provided?

When an invalid or expired access token is provided in a request, the server responds with a 401 Unauthorized response with the following HTML in the payload:

<html>
    <head>,
          <title>401 Authorization Required</title>
    </head>
    <body>
			  <center>
					<h1>401 Authorization Required</h1>
          </center>
		     <hr>
			  <center>nginx/1.16.1</center>
    </body>
</html>

Can a token be requested with multiple scopes?

Multiple scopes across different resources (EPM Cloud environments) are not supported by Identity Cloud Service. Each token request can support only one resource. Requests for multiple scopes within the same resource are supported with space delimited scopes. Requesting multiple scopes across different resources results in a 400 Bad Request response with the following payload:

{
    "error": "invalid_scope",
    "error_description": "Invalid scope"
}

What information is logged in the access log with OAuth?

The access log shows the user name, just as it does with basic authorization. The client ID and access token are not logged.