Use OAuth 2.0 Access Token Based Authentication

Oracle Blockchain Platform supports OAuth access token based authorization, which is superior to basic authorization (using a user name and password). The OAuth 2.0 token services provided by Oracle Identity Cloud Service (IDCS) and Identity and Access Management (IAM) are mechanisms that enable you to use a secured token to access Oracle Blockchain Platform REST endpoints. To use this function, you must get an OAuth access token from IDCS or IAM and then use the OAuth access token to call the blockchain REST proxy APIs.

Previously you could fetch an OAuth access token from IDCS by using the IDCS application associated with the blockchain platform instance and the client credentials information from this application, but this function is no longer supported. If you are using the client credentials from the IDCS application associated with the blockchain platform instance to get OAuth tokens, you must now instead follow the steps at Create an IDCS Confidential Application to generate an OAuth token.

Generate a token using IDCS:
Generate a token using IAM identity domains:
After you generate a token, you can use it in REST API requests:

Note:

After you generate an OAuth token using the IDCS blockchain application, use it only for making calls to blockchain REST APIs. If your OAuth token is used for other IDCS operations, those operations may fail.

Create an IDCS Confidential Application

When an Oracle Blockchain Platform instance is created, an IDCS application is automatically created and associated with the instance. This IDCS application, or instance application, is read-only.

To find the instance application from IDCS admin console:
  1. Expand the Navigation Drawer and then click Oracle Cloud Services.
  2. In the search field, enter the blockchain platform instance name, and then click the search icon. In the results, locate and select the entry. The entry name is in following format: <OBP_instance_name>-<uuid>.

Use the instance application to grant the REST_CLIENT, ADMIN, CA_USER and USER roles as needed for this instance.

Complete the following steps to create a confidential application and use it to generate an access token:

  1. Sign in to the Oracle Identity Cloud Service administrative console.
  2. Open the Navigation Drawer, and then select Applications.
  3. Click Add and then select Confidential Application.
  4. Enter a name for the application and then click Next.
  5. Select Configure this application as a client now, and under Authorization, select one or more supported grant types.
  6. Under Token Issuance Policy, select Add Scope.
  7. In the Select Scope dialog, click the arrow next to your Oracle Blockchain Platform target instance. In the detailed view of that instance, select the /restproxy resource, then click Add.
  8. Click Next through the rest of the wizard.
  9. Click Activate.
You can then use the following IDCS REST API call to generate an OAuth access token:
curl -u '<client_id>:<client_secret>' \
    https://<IDCS-Service-Instance>.identity.oraclecloud.com/oauth2/v1/token \
    -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' \
    -d "grant_type=password&username=<user_name>&password=<user_password>&scope=<primary_audience>/restproxy"

The variables in the syntax have the following values:

  • <client_id> is the client ID.
  • <client_secret> is the client secret.
  • <user_name> is the user name of an IDCS user with the REST_CLIENT role.
  • <user_password> is the password for the user name.
  • <primary_audience> is the instance's REST proxy endpoint URL.
  • <IDCS-Service-Instance> is your identity domain ID. It begins with the characters idcs- and then is followed by a string of numbers and letters, for example, idcs-88c15f1e68604c058062a4220f560123.

See Generate Access Token and Other OAuth Runtime Tokens to Access the Resource for more information.

Example:
curl -u 'myobpinstance-cvirs2oo5e4bpg7pj5kw73oqxcareqrz_APPID:c63b437-1768-4cb6-911e-1e6eg2g3456' \
    https://idcs-88c15f1e68604c058062a4220f560123.identity.oraclecloud.com/oauth2/v1/token \
    -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' \
    -d "grant_type=password&username=obpuser1&password=obppassword1&scope=https://myobpinstance-mytenancy-iad.blockchain.ocp.example.com:7443/restproxy"
The contents of the response body in JSON format will be similar to the following text:
{"access_token":"<access_token>","token_type":"Bearer","expires_in":3600}
The value of access_token is an OAuth access token, in which the sub (subject) claim is the <user_name> you used in the request.

IDCS supports various grant types to get an OAuth token from the Oracle Identity Cloud Service authorization server. For additional information about supported grant types, see: Supported Access Grant Types.

JWT Assertion Grant Type

When using this authorization flow, note the following requirement:
  • The aud (audience) claim in the user assertion must include the IDCS audience https://identity.oraclecloud.com/:
    "aud": [
 "https://identity.oraclecloud.com/"
],

Get an OAuth Access Token from IAM

You need get an access token using the IAM REST API. See Generate Access Token and Other OAuth Runtime Tokens to Access the Resource.

IAM supports various grant types to get an OAuth token from the IAM authorization server. For additional information about supported grant types, see: Supported Access Grant Types.

Use the OAuth Access Token in Oracle Blockchain Platform REST API Requests

The REST client can send requests with Authorization: Bearer <OAuth_access_token> in the request header to call the REST API.
curl -i -X GET -H "Authorization: Bearer OAuth_access_token" "https://primary-audience/rest-endpoint-path"
The variables in the syntax have the following values:
  • OAuth_access_token is the OAuth access token that you obtained.
  • primary-audience is the primary audience URL.
  • rest-endpoint-path is the relative path that defines the Oracle Blockchain Platform REST resource (note that the identity domain ID of Oracle Identity Cloud Service is used in the path).
For example, the following cURL command retrieves the Oracle Blockchain Platform version.
curl -i -X GET -H "Authorization: Bearer <OAuth_access_token>" https://myobpinstance-mytenancy-iad.blockchain.ocp.oraclecloud.com:7443/restproxy/api/version"

Authorization

Oracle Blockchain Platform REST proxy authorization is based on application roles. The user who accesses the REST proxy must be assigned the REST_CLIENT application role in the Oracle Blockchain Platform instance application. When an OAuth access token is used for authentication, the sub (subject) claim in the token is used as the user name.

Note:

When Client Credentials Grant Type is used to get the access token, the client ID is put to the sub (subject) claim in the token. The authorization will fail unless an IDCS or IAM identity domain user with the same name as the client ID is created and assigned to the proper application role.