1. REST API for Oracle EssbaseREST API for Oracle Essbase
  2. Authenticate

Authenticate

You access Oracle Essbase REST resources over HTTPS, using either HTTP Basic authentication, or OAuth 2 authorization (available for cloud deployments).

HTTP Basic Authentication

To use HTTP Basic authentication to validate users, you specify the user name and password for your Essbase account in the Authorization header. The value of the Authorization header should be the base64-encoding of <username>:<password>, specified in the format: 

Basic <base64-encoded-username-colon-password>

Many client applications, such as cURL, provide a method that creates this Authorization header for you.

For example, to authenticate using cURL,

  • Set the cURL environment variable, CURL_CA_BUNDLE, to the location of your local CA certificate bundle. For information about CA certificate verification using cURL, see http://curl.haxx.se/docs/sslcerts.html.
  • Supply the -u option to pass your Essbase account user name and password. cURL adds the Authorization header to the request when you send it.

The following example cURL command uses HTTP Basic authentication to retrieve details about the Essbase instance.

curl -i -X GET -u username:password https://myserver.example.com:9001/essbase/rest/v1/about

OAuth 2 Authorization

If your Essbase instance is deployed as a stack on Oracle Cloud Infrastructure (OCI) via Marketplace, you can use OAuth 2 authorization to access Oracle Essbase REST resources. To do this, first you generate an access token from the OCI Identity domain by issuing a REST API call to the Identity and Access Management (IAM) REST API. Then you make Essbase or Smart View REST API calls using the access token in the Authorization header.

Complete Prerequisites

  1. Review Using OAuth 2 to Access the REST API.

  2. Login to OCI Console.

  3. Ensure that the Essbase REST API user is provisioned, in the confidential/integrated identity domain application's OAuth configuration, with application roles Identity Domain Administrator and Application Administrator.

  4. Find the following fixed values from the identity domain and integrated client confidential application.

    Parameter Value
    Identity Domain URL Domain URL value from the identity domain Overview page.
    Client ID The client identifier for OAuth authorization, found in the integrated confidential identity application.
    Client secret The client secret for OAuth authorization, found in the integrated confidential identity application.
    Primary audience Primary audience defined in the resource server configuration for the integrated confidential application. Can be the same as Identity Domain URL, but with :port included. See Note below.
    Scope Allowed scope you defined in the resource server configuration for the integrated confidential application. See Note below.

    Note:

    If you have no Primary audience or Scope because resource server configuration is not enabled, then you need to configure the confidential application as a resource server.
    1. From the Overview page for your identity domain, copy the Domain URL to your clipboard.
    2. Click Integrated applications, and click the name of your confidential application configured for Essbase.
    3. Click Edit OAuth configuration.
    4. Click Configure this application as a resource server now.
    5. Enter the Identity Domain URL as Primary audience, including the port :443 at the end.
    6. Under Scope, type /essbase, and click the Add button.
    7. Click Save changes.

  5. Base 64 encode the <clientid>:<clientsecret> pair, and copy the encoded string that is returned. You will use it in step 3 below to generate a token.

    Linux Example

    echo -n "clientid:clientsecret" | base64 -w 0

Generate a Token

  1. SSH to the Essbase instance as user opc.

    Example

    ssh -v -i MPOCI_KEY.pem opc@192.0xx.xxx.xxx

  2. Change to user oracle.

    Example

    sudo su oracle

  3. Within an export command (or similar shell command to create an ACCESS_TOKEN variable), embed a cURL statement that calls the the identity domains REST endpoint /oauth2/v1/token to obtain a token. Replace <inputs> with your collected values.

    Syntax

    export ACCESS_TOKEN=`curl -k -i -H "Authorization: Basic <base64encoded_clientID:clientSecret>" -H 'Conset=UTF-8' --request POST <Identity_Domain_URL>/oauth2/v1/token -d 'grant_type=password&username=<OCI_username>&password=<OCI_password>&scope=<Primary_Audience><Scope>'| sed -rn 's/(\{"access_token":")([^"]+)(.*)/\2/p'`

    Note:

    If the OCI user password contains special characters, URL encode it in the REST call. (For example, a_!p@$$w0rD becomes a_%21p%40%24%24w0rD after URL encoding.)

    Example

    export ACCESS_TOKEN=`curl -k -i -H "Authorization: Basic base64EncodedLongAlphanumericString9" -H 'Conset=UTF-8' --request POST https://idcs-0alphanumericstring8.identity.oraclecloud.com/oauth2/v1/token -d 'grant_type=password&username=sampleOCIUserName&password=a_%21p%40%24%24w0rD&scope=https://idcs-0alphanumericstring8.identity.oraclecloud.com:443/essbase'| sed -rn 's/(\{"access_token":")([^"]+)(.*)/\2/p'`

  4. Echo the access token to test that it returns a token. It should return a long string of characters.

    Example

    echo $ACCESS_TOKEN

    The default expiration of the token is 3600 seconds from the time of the request, so you will need to use it for authorization before it expires, or request another token.

Authorize Essbase or Smart View

You can use the OAuth token obtained in the previous section to make Essbase or Smart View REST calls.

Essbase Syntax

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://<essbase_instance_host>/essbase/rest/v1/applications

Smart View Syntax

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://<instance_host>/essbase/smartview