Oracle Management Cloud Common REST API

Authentication

REST API for Oracle Management Cloud uses a certificate authority (CA) certificate, issued by Verisign, to enable clients to connect securely to the server.

You access the Oracle Management Cloud REST resources over HTTPS and must provide the following information for authentication:

An SSL certificate authority (CA) certificate file or bundle to authenticate against the Verisign CA certificate.
Domain ID, user name, and password for your Oracle Management Cloud account.

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.
Pass the user name and password for your Oracle Management Cloud account (for example, <username> and <password>) using the -u cURL option.
Pass the <request-header> custom request header using the -H cURL option.
You will be prompted for your Oracle Management Cloud password if you don't include it in the header.

The following provides an example cURL command:

curl -X GET -u <username> -H <request-header>:<value> https://<subdomain>.<domain>.com:<port>/<resource-path>

Enable OAuth With REST API

OAuth offers enhanced security when interacting with the REST API for Oracle Management Cloud.

Prerequisites

Before you can begin to enable OAuth, you will need the following:

OMC URL
For more information, see Quick Start.
You need to be an Identity Domain administrator to configure this task. For more information, see Add or Remove a User Account from an Administrator Role
IDCS console URL
Your IDCS console URL is found when you are logging in to Oracle Management Cloud. It follows the format:
```
https://<IDCS_DOMAIN_NAME>/ui/v1/adminconsole/?root=users
```

Obtain a Personal Access Token

Login to IDCS using your credentials.
From the main menu, select Oracle Cloud Services, then click OMCEXTERNAL_<INSTANCE_NAME>.
Click Application, then click Generate Access Token.
Select Customized Scopes and Invokes Identity Cloud Service APIs.
Download Token.

Create Client App For OAuth

The creation of a Client App is required to generate your access token password. Note that the name of the client app must end in "_APPID" or it won't be created.

Create a new file called createClientApp.json and copy the following:

{
  "name": "TESTCLIENT1_SERVICEAPI_APPID",
  "displayName": "TESTCLIENT1",
  "description": "Test client for serviceapi",
  "isAliasApp": false,
  "active": true,
  "isOAuthClient": true,
  "clientType": "confidential",
  "allowedGrants": [
    "client_credentials"
  ],
  "allowedScopes": [
    {
      "fqs": "https://<OMC_URL>/serviceapi/"
    }
  ],
  "isOAuthResource": true,
  "accessTokenExpiry": 86400,
  "audience": "https://<OMC_URL>",  Important: Make sure there is no trailing slash '/' at the end of OMC_URL in audience field.
  "scopes": [
    {
      "value": "/serviceapi/"
    }
  ],
  "basedOnTemplate": {
    "value": "OPCAppTemplateId"
  },
  "serviceTypeVersion": "1.0",
  "serviceTypeURN": "OMCEXTERNAL",
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:App"
  ]
}

Run the following command to create a new Client App.

curl -X POST https://<IDCS_DOMAIN>/admin/v1/Apps -H 'Content-Type: application/json' -H "Authorization: Bearer <OAuth_Access_Token>" -d "@createClientApp.json"

Note:

For OAuth_Access_Token, use the app_access_token value from the downloaded token file

From the response, write down the ClientSecret. Your clientID is the same as name.

Grant OMC Admin Role to Client App

Before you run the Grant OMC Admin Role call, you will need the Application IDs of OMCEXTERNAL_<INSTANCE_NAME> and TESTCLIENT1_SERVICEAPI, and the AppRole ID of the OMC Administrator role.

Run the following commands:

GET Application ID for OMCEXTERNAL_<INSTANCE_NAME> and TESTCLIENT1_SERVICEAPI

curl -X GET https://<IDCS_DOMAIN>/admin/v1/Apps

GET Application Role ID for OMC Administrator

curl -X GET https://<IDCS_DOMAIN>/admin/v1/AppRoles

Create a new JSON file called grantAdmin.json and copy the following:

{
  "app": {
    "value": "eb5...597" //Application ID of IDCS application OMCEXTERNAL_<INSTANCE_NAME>
  },
  "entitlement": {
    "attributeName": "appRoles",
    "attributeValue": "1dc...808" //AppRoleId of the "OMC Administrator" role
  },
  "grantMechanism": "ADMINISTRATOR_TO_APP",
  "grantee": {
    "value": "012...9ab", //Application ID of the OAuth client TESTCLIENT1_SERVICEAPI_APPID
    "type": "App"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:Grant"
  ]
}

Run this cURL call to grant the OMC Administrator privilege to the Client App you just created:
curl -X POST https://<IDCS_DOMAIN_NAME>/admin/v1/Grants -H 'Authorization: <OAuth_Access_Token>' -H 'Content-Type: application/json' -d "@grantAdmin.json"

Note:

OMC grants may take up to an hour to reflect due to caching.

Granting the OMC Admin Role from the UI

Alternatively, you can grant the OMC Admin Role to the Client App directly from the UI instead of using cURL.

From the main menu, select Oracle Cloud Services, then click OMCEXTERNAL_<INSTANCE_NAME>.
Click Application Roles.
Select the check box for the application role OMC Administrator.
Click Menu, and then select Assign Applications.
In the Assign Applications window, select the check box for the OAuth client app.
Click OK.

Get Token

Request:

curl https://<IDCS_DOMAIN>/oauth2/v1/token -X POST -u '<CLIENTID>:<CLIENTSECRET>' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' -d 'grant_type=client_credentials&scope=<OMC_URL>/serviceapi/' -i

Response:

{
    "access_token": "eyJ4...xrig",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Use Token

This is a sample command to create a new entity using the access_token. Replace OMC_URL and ACCESS_TOKEN.

Request:

curl 'https://OMC_URL/serviceapi/entityModel/uds/entities' -H "Content-Type:application/json" -d "@example.json" -H 'Authorization: Bearer <OAuth_Access_Token>'