Using OAuth with REST APIs

The REST APIs for Oracle Process Cloud Service support basic auth, JSON Web Token (JWT), and OAuth for authentication. OAuth 2.0 is an authorization framework that enables an application or a service to obtain limited access to a protected HTTP resource. In OAuth, the applications are called clients; they access protected resources by presenting an access token to the HTTP resource.

Oracle Process Cloud Service accepts OAuth tokens as an alternative to basic auth. As an administrator, you configure OAuth resources and clients. Developers can use the client information you provide to obtain access tokens for the clients.

Note:

Shared Identity Management (SIM) users can use either basic auth or OAuth to access the REST APIs for Oracle Process Cloud Service. Federated single sign-on (SSO) users must use an OAuth access token to access the REST APIs.

Configuring OAuth Resources and Clients

As the administrator, you’re responsible for configuring and managing OAuth resources and OAuth clients in Oracle Cloud. You use the OAuth Administration page in the My Services application to register new OAuth resources and clients, grant and revoke client access to Oracle Cloud APIs, and manage the settings of the resources and clients.

A resource is a protected service in Oracle Cloud. When you register a new resource, you define some parameters and these parameters are used in authorizing the client request to those services.

To register an OAuth client for an Oracle Process Cloud Service instance:
  1. Sign in to the My Services application. Be sure to sign in to the correct identity domain.
  2. Click Users.
  3. Click the OAuth Administration tab.
  4. Register your Oracle Process Cloud Service instance as a resource by entering its base URL.
  5. Register an OAuth client and associate your newly created resource.
    Registering your Oracle Process Cloud Service as a resource provides you with two important values for secure access:
    • Client ID

    • Client secret

    Developers can use this information to obtain an access token for the client.

See Managing OAuth Resources and Clients in Administering Oracle Cloud Identity Management.

Obtaining a Client Access Token

The client ID and client secret of the client application are base64 encoded and sent in the header. For example, the authorization header has a value of base64encoded(client_id:client_secret). This value is sent to obtain a client token.

To obtain a client access token:
  1. Obtain a client assertion. You can obtain a client assertion in one of the following ways:
    • By providing the client credentials
    • By providing another self-issued JWT assertion
    • By providing another assertion (from an IDM OAuth-generated client assertion or any other third-party JWT assertion)
    You access the token endpoint of the OAuth server by passing client_id:client_secret as a basic authorization header. The administrator for your Oracle Process Cloud Service can provide you with the client ID and secret for the service instance.

    For example, the following cURL command obtains a client assertion by providing the client credentials. Note that the grant type is client_credentials.

    curl -i -H 'X-USER-IDENTITY-DOMAIN-NAME: OAuthTestTenant125' 
    -u <client_id>:<client_secret> 
    -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8'
    --request POST http://<identity-domain>.<data-center>.oraclecloud.com/oam/oauth2/tokens 
    -d 'grant_type=client_credentials'
    

    See Managing OAuth Resources and Clients in Administering Oracle Cloud Identity Management.

  2. Obtain an access token.
    You can obtain an access token by using different scenarios in the password flow. These scenarios include using the user credentials with either the client credentials or a client assertion.
    For example, the following cURL command obtains an access token by passing the user credentials and a client assertion:
    curl -i -H 'X-USER-IDENTITY-DOMAIN-NAME: OAuthTestTenant125' 
    -u <client_id>:<client_secret> 
    -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8'
    --request POST http://<identity-domain>.<data-center>.oraclecloud.com/oam/oauth2/tokens   
    -d 'grant_type=password
    &username=tenantAdminUser
    &password=Fusionapps1
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
    &client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsIng1dCI6Ild3cmVwdTJkYXNhSXBHUi1BbFZwSGtVQjZK
    ZyIsImtpZCI6Ik9BdXRoVGVzdFRlbmFudDEyNS5jZXJ0In0.eyJvcmFjbGUub2F1dGgudGtfY29udGV4dCI6ImNsaWVudF9hc3Nlc
    nRpb24iLCJleHAiOjE0MjYwMzI4MzgwMDAsInN1YiI6IjMwM2EyNDkyLWQ2NGYtNGUwNC1iNzhmLWI0MzMwMDQ3MzEyYiIsImlzcy
    I6Ik9BdXRoVGVzdFRlbmFudDEyNSIsInBybiI6IjMwM2EyNDkyLWQ2NGYtNGUwNC1iNzhmLWI0MzMwMDQ3MzEyYiIsImp0aSI6IjY
    yNzZhYTI0LTUxNjQtNGEwZC1iYzQxLTlmMzVjMGU1ZjgxZiIsIm9yYWNsZS5vYXV0aC5zdmNfcF9uIjoiT0F1dGhUZXN0VGVuYW50
    MTI1U2VydmljZVByb2ZpbGUiLCJpYXQiOjE0MjU0MjgwMzgwMDAsIm9yYWNsZS5vYXV0aC5pZF9kX2lkIjoiMTM0NjM2NzUxMzgzM
    DI1NjYiLCJ1c2VyLnRlbmFudC5uYW1lIjoiT0F1dGhUZXN0VGVuYW50MTI1Iiwib3JhY2xlLm9hdXRoLnBybi5pZF90eXBlIjoiQ2
    xpZW50SUQifQ.OCHS9FhKJEXpIg3IvE6qWdTz3tRY449LZoBAcc3yDoaMbjS4CZxDDuKx6MUBpHmkmVoHRZSmkrILOzel51sT_kjE
    HfNtzwMCIs2re_JcSfGkvnzv0aCV1r_V5dvmmZulhGaOUTu9nkEFzCq-JNa23eO_dEq8jfP7-Y7H2KGMvuC5lHGGQViw1ega-4mFu
    ZBJlSvzEqDcYIPde0m8gSUF--IFuiovgGTKCe97-0MF34za6SZ0HJv9p3WesvCS8YV1bcWVwTGEXCZ3qA1mA-IOKvaMZNOxM_D9tT
    5KVCub-i-H6r0uHpkovOCzunffcuL4cOg5ptrFv-abn-JP47eNag
    &scope=http://www.example.com UPDATE'
    
    
    See Using REST API Calls for the Password Grant in Administering Oracle Cloud Identity Management.
  3. Confirm that you can access the REST APIs for Oracle Process Cloud Service by using the access token you just obtained.