Use OAuth 2.0 Access Token Based Authentication

In addition to basic auth (using a user name and password), Oracle Blockchain Platform supports OAuth access token based authorization. The OAuth 2.0 token service provided by Oracle Identity Cloud Service (IDCS) and Identity and Access Management (IAM) are mechanisms that enables you to use a secured token to access Oracle Blockchain Platform REST endpoints. To use this, you need to get an OAuth access token from IDCS or IAM, and use the OAuth access token to call the blockchain REST proxy APIs.

If you're using IDCS, you have two options to generate a token:

• Get an OAuth Access Token from the IDCS Authorization Server
• Create an IDCS Confidential Application

If you're using IAM identity domains to generate a token:

• Get an OAuth Access Token from IAM

Once you have your token, you can use it to perform REST API requests:

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

Get an OAuth Access Token from the IDCS Authorization Server

The REST proxy doesn't provide an interface for generating access tokens; you need get an access token using the IDCS REST API. See Generate Access Token and Other OAuth Runtime Tokens to Access the Resource .

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.

Resource Owner Password Credentials Grant Type

When a Blockchain Platform instance is created, an IDCS application is automatically created and associated with the Blockchain Platform instance. This IDCS application will be called the Blockchain Platform instance application in this topic. This 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 the format of <OBP_instance_name>-<uuid>.
3. You can now generate an OAuth access token either using the web console or via REST API.

   Web console:

   In the IDCS application, on the Details tab, click Generate Access Token. In the dialog select Available Scopes, and click Download Token. The value of field app_access_token in the downloaded token file is an OAuth access token, in which the sub (subject) claim is the name of the current IDCS user who is logged into IDCS admin console.

   REST API:

   In the IDCS application, on the Configuration tab, retrieve the following information:

   • Under General Information, get Client ID and Client Secret.
   • Under Resources, get Primary Audience.

   Invoke the IDCS REST API 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"

   Where:

   • <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 primary audience 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.

   For 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.oraclecloud.com:7443/restproxy"

   The contents of the response body in JSON format will be similar to:

   {"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.

Note:

Instead of using the Blockchain Platform instance application, you can also choose to create a new IDCS Confidential Application and use its client ID and client secret to generate an OAuth access token. See Create an IDCS Confidential Application.

JWT Assertion Grant Type

The following article provides a step-by-step walkthrough of how to use an assertion grant authorization flow for API calls and can be used as a reference: Authentication and User Propagation for API Calls.

When using this authorization flow, note the following:

• Since the Blockchain Platform instance application is read-only, you're not able to import certificate for user assertion. You need to create a new IDCS confidential application as described in the guide. Refer to Create an IDCS Confidential Application for how to add scope for an Blockchain Platform instance
• The aud (audience) claim in the user assertion must include the IDCS audience https://identity.oraclecloud.com/:

  "aud": [
   "https://identity.oraclecloud.com/"
  ],

Create an IDCS Confidential Application

Optionally, you can 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 select Applications.
3. Click Add and select Confidential Application.
4. Enter a name for the application and 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.

Get an OAuth Access Token from IAM

The REST proxy doesn't provide an interface for generating access tokens; 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"

Where:

• OAuth_access_token is the OAuth access token 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 application role based. The user who accesses the REST proxy must be assigned the REST_CLIENT application role in the 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.