Integrate with Oracle Content and Experience Using OAuth

Developer access to Oracle Content and Experience REST APIs is protected by CG/WTSS using OAuth clients.

For content management and sites management REST APIs, you acquire the client ID and secret required to get the access token from Oracle Identity Cloud Service (IDCS). For 2-legged OAuth you use client credentials to acquire the client ID and secret. For 3-legged OAuth, you use an Authorization code to acquire the client ID and secret.

The following sections describe how to use OAuth clients to access Oracle Content and Experience REST APIs:

Access Using 2-Legged OAuth

For access using 2-legged OAuth, you can use client credentials to acquire the client ID and secret required to get an access token from Oracle Identity Cloud Service (IDCS).

The Identity Domain Administrator or Application Administrator of the tenant creates an OAuth client for the developer with the required privileges.

The Identity Domain Administrator performs the following steps to get an access token:

  1. Create an OAuth Client and Acquire a Client ID and Secret
  2. Grant the Required Oracle Content and Experience Roles to the Client
  3. Acquire an Access Token from Oracle Identity Cloud Service (IDCS) for the Required Resource
  4. Use the Access Token to Access the Oracle Content and Experience Resource

Create an OAuth Client and Acquire a Client ID and Secret

Developer access to Oracle Content and Experience REST APIs is protected by CG/WTSS using OAuth clients. You can acquire the client ID and secret required to get the access token from Oracle Identity Cloud Service (IDCS).

The Identity Domain Administrator or an Application Administrator of the tenant creates an OAuth client for the developer with the required privileges. To do this, perform the following steps:

  1. Go to the IDCS administration console:

    https://<IDCS BaseURL>/ui/v1/adminconsole
  2. Click to add a new application in the Applications section.
  3. Select Confidential Application.
  4. Give the application a name and, optionally, a description, and press Enter.
  5. Choose to configure this application as a client.
  6. Select the client credentials grant type on the Authorization screen.
  7. Scroll down to the Token Issuance Policy section and, under Resources, click add scope to give the application access to the required Oracle Content and Experience instance.
  8. Click the right arrow to select the scope.

    The only scope required is the one ending in

    urn:opc:cec:all
  9. Click Next until the end of the train.

    The Resources, Web Tier Policy, and Authorization stops are related to applications that have some resource authenticated or authorized by IDCS; for example, a web application. This isn’t relevant in the case of a simple server-server client, which is discussed here.

  10. Click Finish.
  11. Note the Client ID and Client Secret values because you’ll need those to get a token later.
  12. Check Activate and then click Save to enable the application.

You can decide how to handle the client ID and secret.

Note:

Just as a regular user, an OAuth client with the client credentials requires relevant permission on objects in your Oracle Content and Experience instance to be able to perform actions using REST API for Content Management. For example, it needs to be a repository member with Contributor permission to create assets in it, or a Manager on repository to modify its settings. In Oracle Content and Experience web UI, you can use the Members dialog to find your OAuth client by name and add it to the required object. A newly created OAuth client will appear in search only after the next IDCS user sync is complete. As an alternative, you can use REST API for Content Management (permissionOperations endpoint) to add the OAuth client by ID. For example, the API call below will add OAuth client as a Manager on channel:
POST to https://{{hostname}}/{{management-base}}/permissionOperations?links=none
Body: {"operations":{"share":{"resource":{"id":"<channel GUID>","name":"<channel name>l","type":"channel"},"roles":[{"name":"manager","message":"I added you as a member to channel \"Secure Channel.\" It should appear in your list when you sign in to Oracle Content and Experience.","users":[{"name":"<OAuth client ID>","type":"user"}]}]}}}

Grant the Required Oracle Content and Experience Roles to the Client

You can grant the required roles through the Oracle Identity Cloud Service (IDCS) administration console in the Pool environment or through the CloudPortal endpoint in a production environment.

  1. Log in to the IDCS administration console.
  2. Click Applications.
  3. Select the Oracle Content and Experience service instance for which you need privileges. This instance name would have been provided by your account administrator.
  4. Right-click the burger menu on the right.
  5. Choose Assign Applications.
  6. Click Application Roles.
  7. Click CECRepositoryAdministrator.

  8. Repeat the steps 4 through 7 for the roles CECEnterpriseUser and CECContentAdministrator.
  9. Save the changes.

Acquire an Access Token from Oracle Identity Cloud Service (IDCS) for the Required Resource

Use the client ID and secret obtained earlier from the OAuth client to get an AccessToken for the resource.

A sample curl command to acquire an access token follows:

AccessToken Request

curl -X POST  \
https://<idcs tenantname that is protecting this service>/oauth2/v1/token \
-H 'Authorization: Basic <Base64 encoded clientID:clientSecret>'  \
-H 'Host: <IDCS BaseURL>'  \
-d 
'grant_type=client_credentials&scope=https://<ServiceInstanceBaseURL>:443/urn:opc:cec:all'

IDCS returns the key and value for an access token:

{"access_token":"<access-token-value>}"

Copy the access token value.

Use the Access Token to Access the Oracle Content and Experience Resource

Once the access token is acquired, call the Oracle Content and Experience endpoint to access the resource.

A sample curl command follows.

curl -X GET <Oracle-Content-and-Experience-URL>/sites/management/api/v1/sites \
-H 'Authorization: Bearer <Access Token acquired from previous step>'\
-H 'Content-Type: application/json'

Access Using 3-Legged OAuth Flow

For access using 3-legged OAuth, you acquire the client ID and secret required to get the access token from Oracle Identity Cloud Service (IDCS).

This requires that the Identity Domain Administrator or Application Administrator of the tenant creates an OAuth client for the developer with the required privileges. The Identity Domain Administrator performs the following steps to create an OAuth client.

For 3-legged OAuth, you use an Authorization code grant type.

The Identity Domain Administrator performs the following steps to get an access token:

  1. Create an OAuth Client and Acquire a Client ID and Secret
  2. Grant the Required Oracle Content and Experience Roles to the Client
  3. Acquire an Access Token from Oracle Identity Cloud Service (IDCS) for the Required Resource
  4. Use the Access Token to Access the Oracle Content and Experience Resource

Create an OAuth Client and Acquire a Client ID and Secret

Developer access to Oracle Content and Experience REST APIs is protected by CG/WTSS using OAuth clients. You can acquire acquire the client ID and secret required to get the access token from Oracle Identity Cloud Service (IDCS).

The Identity Domain Administrator or an Application Administrator of the tenant creates an OAuth client for the developer with the required privileges. To do this, perform the following steps:

  1. Go to the IDCS administration console:

    https://<IDCS BaseURL>/ui/v1/adminconsole
  2. Click to add a new application in the Applications section.
  3. Select Confidential Application.
  4. Give the application a name and, optionally, a description, and press Enter.
  5. Choose to configure this application as a client.
  6. Select the Authorization code grant type on the Authorization screen.
  7. Enter a redirect URL value to point to the URL where the user needs to be redirected after authorization.
  8. Enter a Post logout URL value to point to the Oracle Content and Experience service administration console.
  9. Scroll down to the Token Issuance Policy section and, under Resources, click add scope to give the application access to the required Oracle Content and Experience instance.
  10. Click the right arrow to select the scope.

    The only scope required is the one ending in

    urn:opc:cec:all
  11. Click Next until the end of the train.

    The Resources, Web Tier Policy, and Authorization stops are related to applications that have some resource authenticated or authorized by IDCS; for example, a web application. This isn’t relevant in the case of a simple server-server client, which is discussed here.

  12. Click Finish.
  13. Note the Client ID and Client Secret values because you’ll need those to get a token later.
  14. Check Activate and then click Save to enable the application.

The client can store the Client ID and Client Secret values securely in a credential store.

Grant the Required Oracle Content and Experience Roles to the Client

You can grant the required roles through the Oracle Identity Cloud Service (IDCS) administration console in the Pool environment or through the CloudPortal endpoint in a production environment.

  1. Log in to the IDCS administration console.
  2. Click Applications.
  3. Select the Oracle Content and Experience service instance for which you need privileges. This instance name would have been provided by your account administrator.
  4. Right-click the burger menu on the right.Description of access-rest-apis.png follows
    Description of the illustration access-rest-apis.png
  5. Choose Assign Applications.
  6. Click Application Roles.
  7. Click CECRepositoryAdministrator.
  8. Repeat the steps 5 through 7 for the roles CECEnterpriseUser and CECContentAdministrator.
  9. Save the changes.

Acquire an Access Token from Oracle Identity Cloud Service (IDCS) for the Required Resource

You can get an access token from IDCS for a resource.

Acquisition of the access token consists of multiple steps:

  1. Request the authorization code.

    Authorization code request:

    curl  -i
    --request GET https://<IDCS-service-instance>/oauth2/v1/authorize?client_id=<client-id>&response_type=code&redirect_uri=<client-redirect-uri>&scope=fullyqualified&nonce=<nonce-value>&state=1234

    Note:

    For a fully qualified URL, go to the Client Configuration section of the application that you have created and copy the URL from the Resources scope, for example, https://example.com:443/urn:opc:cec:all.
  2. Provide log-in credentials to IDCS. If you are not already logged in, IDCS will challenge you to authenticate. IDCS checks your credentials.
  3. Acquire an authorization code.

    If the login is successful, IDCS redirects the browser to the client application with an authorization code.

    If you do not authenticate, an error is returned rather than the authorization code.

  4. Use the authorization code to acquire an access token.

    Access token request:

    curl -i
    -H 'Authorization: Basic <base64-clientid-secret>'
    -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' 
    --request POST <tenant-base-url>/oauth2/v1/token -d 'grant_type=authorization_code&code=<authz-code>&redirect_uri=<client-redirect-uri>'

    IDCS returns the key and value for an access token:

    {"access_token":"<access-token-value>"}

    Copy the access token value.

Use the Access Token to Access the Oracle Content and Experience Resource

Once the access token is acquired, call the Oracle Content and Experience endpoint to access the resource.

A sample curl command follows.

curl -X GET <Oracle-Content-and-Experience-URL>/content/management/api/v1.1/channels \
-H 'Authorization: Bearer <Access Token acquired from previous step>'\
-H 'Content-Type: application/json'

Integrate Using OAuth As a Resource Owner

A Resource Owner can generate OAuth tokens for other users. You can use Identity Cloud Service (IDCS) to configure a confidential application to authorize a Resource Owner grant for requesting tokens.

To configure a confidential application to authorize a Resource Owner grant:

  1. Go to the IDCS admin console: https://<IDCS BaseURL>/ui/v1/adminconsole
  2. Click to add a new application in the Applications section.
  3. Select Confidential Application.
  4. Give the application a name and, optionally, a description, and press Enter.
  5. Choose to configure this application as a client.
  6. Select the Resource Owner grant type on the Authorization screen.
  7. Scroll down to the Token Issuance Policy section and, under Resources, click Add Scope to give the application access to the Oracle Content and Experience instance required.
  8. Select the correct instance.
  9. Click the right arrow to select the scope. The one ending in urn:opc:cec:all is the only scope required.
  10. Click Next until the end of the train. The Resources, Web Tier Policy, and Authorization stops are related to applications that have some resource authenticated or authorized by IDCS; for example, a web application. In the case of a simple server-server client, which is discussed here, this isn’t relevant.
  11. Click Finish.
  12. Note the Client ID and Client Secret values because you’ll need those to get a token later.
  13. Check Activate and then click Save to enable the application.

To request a token:

  1. Make a form post to <IDCS BaseURL>/oauth2/v1/token.
  2. Authentication is HTTP basic, where the user name is the client ID and the password is the client secret. The HTTP authorization header must specify Basic authentication.
  3. The following table describes the fields.
    Field Value
    grant_type password
    scope A scope you added previously, in step 9; for example: https:// 1DF8AB52D0FF48F6992EEA3A5715B66F.cec.dev.ocp.octest. com:443/urn:opc:cec:all
    username The user name to generate the token for.
    password The password for the user name in the preceding field.
    POST /oauth2/v1/token HTTP/1.1
    Host: <idcs-host>
    Authorization: Basic
    NTZkZWJjY2EzYjc0NDRlMWFhNjg4OGQ0ZTYzY2Y1M2Y6NDYxYzM5YjctMzJiZC00NGE0LTk4NTc
    tN
    WM1NzAyMWMzNDg4
    Accept: */*
    Content-Type: application/x-www-form-urlencoded
    Content-Length: 162
    grant_type=password&scope=https%3A%2F
    %2F1DF8AB52D0FF48F6992EEA3A5715B66F.cec.
    dev.ocp.octest.
    com%3A443%2Furn%3Aopc%3Acec%3Aall&username=<user-name>&password=<password>
    This results in JSON text where the token is the value of the access_token field:
    {
    "access_token":
    "eyJ4NXQjUzI1NiI6IkhoRktIMFFGeHR1UDkxLWg3QlJKSUFDMU50V2R...HUQmto_oELyjRaBp
    qh
    I75hQJYLWRKm6ozPS57tR1EYHmWABgYw_XALMT1kMuIuRxpGB2ozngpajzNNBBu2qtKg10-
    RzBTulKaxD25vKK1rznQ3p_XAOLK4CUUM-uG_PUOk49-
    JDgJjuSI74hLC1kagIlM93A2jUG3g3gdUpUCZPg",
    "token_type": "Bearer",
    "expires_in": 604800
    }

    The token expiration time is given in seconds, and is typically 7 days.

  4. To use the token and access REST API endpoints, use the Bearer Authorization header; for example:
    curl -i -H 'Authorization: Bearer token' --request GET
    
    https://Oracle-Content-and-Experience-URL/sites/management/api/v1/sites
    Authorization header format is Basic [Base64[client_id:client_secret]]. The access token value needs to be a base64 UTF-8 encoded value of the client ID and client secret concatenated using a colon as a separator; for example, clientID:clientSecret.