1. Administering Oracle Advanced Authentication and Oracle Adaptive Risk Management
  2. Administering Oracle Advanced Authentication
  3. Configuring Oracle Advanced Authentication
  4. Configuring OAuth JWT for REST APIs

11.13 Configuring OAuth JWT for REST APIs

OAA is configured to use API Key Security for REST API's by default. Administrators can enable OAuth JSON Web Tokens (JWT) to access REST APIs, which provides improved security using short-lived access tokens.

Note:

Administrators should use API Key Security only mode during initial installation. Once the installation is complete and all the use-cases are verified, if you require OAuth JWT security, you should upgrade to API Key Security and OAuth combined mode, and verify the use-cases again. If all the use-cases are successful then, if required, you can upgrade to use OAuth only.
REST API's are used in OAA in the following circumstances:
Administrators can configure OAA to use one of the following modes for REST API's:
  • API Key Security only
  • API Key Security and OAuth combined
  • OAuth only

Note:

If you are using OAA with Oracle Universal Authenticator (OUA) and you want to use OAuth JWT, you must use API Key Security and OAuth combined mode.

API Key Security Only

API Key Security mode is the default configuration and should be used during initial installation. When API Key Security mode is configured, internal communication, OAA Administration console tasks, and external REST API access is performed using API Key Security.

To configure API Key Security only mode, see Configuring API Key Security Only.

When accessing a REST API using an external application, the username and password is passed using Basic Authorization. The example below shows using the OAA Admin API to perform a GET request:
curl -i -X GET -H Authorization:Basic <Base64Encoded(<username>:<password>)> -H <request-header>:<value> <PolicyUrl>/<resource-path>

API Key Security and OAuth combined

When both API Key Security and OAuth is configured, the following is true:
  • Internal communication and OAA Administration console tasks uses API Key Security.
  • External REST API access is available using either API Key Security or OAuth JWT.

To configure API Key Security and OAuth combined mode, see Configuring API Key Security and OAuth combined.

When accessing a REST API using an external application, you can pass an access token for OAuth using Authorization:Bearer <Token>, or for API Key Security pass the username and password using Authorization:Basic <Base64Encoded(<username>:<password>)>.

OAuth Only

When OAuth only mode is used, internal OAA communication, OAA Administration console tasks, and external REST API access is performed using OAuth JWT tokens only.

To configure OAuth only mode, see Configuring OAuth Only.

When accessing a REST API using an external application, the access token for OAuth is passed using Authorization:Bearer <Token>. The example below shows using the OAA Admin API to perform a GET request:
curl -i -X GET -H Authorization:Bearer <Token> -H <request-header>:<value> <PolicyUrl>/<resource-path>

11.13.1 Configuring API Key Security Only

The following steps show how to configure API Key Security only:

Note:

This is the default installation method configured in the installOAA.properties.
  1. Set the following parameters under ##3. OAUTH configuration## in the installOAA.properties file:
    install.global.service.security.basic.enabled=true
install.global.service.security.oauth.enabled=false

For more information on the installOAA.properties file, see Preparing the Properties file for Installation.

11.13.2 Configuring API Key Security and OAuth combined

The following sections show how to configure API Key Security and OAuth combined mode.

Preparing the installOAA.properties File

  1. Set the following parameters under ##3. OAUTH configuration## in the installOAA.properties file:
    install.global.service.security.basic.enabled=true
install.global.service.security.oauth.enabled=true

For more information on the installOAA.properties file, see Preparing the Properties file for Installation.

Updating OAA Using OAA.sh

After updating the installOAA.properties file you must run OAA.sh to update OAA with the configuration:

  1. Connect to the OAA management pod, for example:
    kubectl exec -n oaans -ti oaamgmt-oaa-mgmt-6f4c9cd56f-std6l -- /bin/bash
    This will take you into a bash shell inside the OAA management pod:
    [oracle@oaamgmt-oaa-mgmt-6f4c9cd56f-std6l /]$
  2. Inside the OAA management pod run the following to update OAA with the configuration:
    [oracle@oaamgmt-oaa-mgmt-6f4c9cd56f-std6l /]$ cd ~
[oracle@oaamgmt-oaa-mgmt-6f4c9cd56f-std6l ~]$ ./OAA.sh -f installOAA.properties

    Note:

    This will use the <NFS_CONFIG_PATH>/installOAA.properties file.

11.13.3 Configuring OAuth Only

The following sections show how to configure OAuth only mode.

Preparing the installOAA.properties File

  1. Set the following parameters under ##3. OAUTH configuration## in the installOAA.properties file:
    install.global.service.security.basic.enabled=false
install.global.service.security.oauth.enabled=true
oauth.tokenexpiry=3600
api.oauth.tokenexpiry=3600
oauth.adminname=<adminuser>
oauth.adminpassword=<adminuserpwd>
oauth.appusername=<appuser>
oauth.appuserpassword=<appuserpwd>
    where:
    • oauth.tokenexpiry is the expiry time for the UI token in seconds. The UI token is used when tasks are performed using the OAA Administration Console. The default value is 3600 seconds (1 hour).
    • api.oauth.tokenexpiry is the expiry time for the API OAuth token in seconds. The API OAuth token is used for internal communications. The default value is 3600 seconds (1 hour).
    • oauth.adminname should be set to an Administration user that is a member of the OAA-Admin-Role group. For more information, see Creating Users and Groups in the LDAP Store.
    • oauth.adminpassword is the base64 encoded password for the user defined in oauth.adminname.
    • oauth.appusername should be set any user that is a member of the OAA-App-User group. For more information, see Creating Users and Groups in the LDAP Store.

      Note:

      This user can be the same user as oauth.adminname as long as that user exists in both the OAA-Admin-Role and OAA-App-User groups.
    • oauth.appuserpassword is the base64 encoded password for the user defined in oauth.appusername.
    For example:
    install.global.service.security.basic.enabled=false
install.global.service.security.oauth.enabled=true
oauth.tokenexpiry=3600
api.oauth.tokenexpiry=3600
oauth.adminname=oaaadmin
oauth.adminpassword=bXlvYWFhZG1pbnB3ZA==
oauth.appusername=testuser
oauth.appuserpassword=bXl0ZXN0dXNlcnB3ZA==

For more information on the installOAA.properties file, see Preparing the Properties file for Installation.

Updating OAA Using OAA.sh

After updating the installOAA.properties file you must run OAA.sh to update OAA with the configuration:

  1. Connect to the OAA management pod, for example:
    kubectl exec -n oaans -ti oaamgmt-oaa-mgmt-6f4c9cd56f-std6l -- /bin/bash
    This will take you into a bash shell inside the OAA management pod:
    [oracle@oaamgmt-oaa-mgmt-6f4c9cd56f-std6l /]$
  2. Inside the OAA management pod run the following to update OAA with the OAuth JWT configuration:
    [oracle@oaamgmt-oaa-mgmt-6f4c9cd56f-std6l /]$ cd ~
[oracle@oaamgmt-oaa-mgmt-6f4c9cd56f-std6l ~]$ ./OAA.sh -f installOAA.properties

    Note:

    This will use the <NFS_CONFIG_PATH>/installOAA.properties file.

Configuring the Token Refresh Cronjob

OAuth JWT access tokens are short-lived and need to be renewed prior to expiration. OAA provides a Kubernetes cronjob which automates token refresh from OAM. If preferred, Administrators can write their own automation instead of using this cronjob. To enable the cronjob perform the following steps:
  1. Inside the OAA management pod run the following script to create a cronjob to renew the tokens automatically:
    [oracle@oaamgmt-oaa-mgmt-6f4c9cd56f-std6l /]$ cd ~/scripts
[oracle@oaamgmt-oaa-mgmt-6f4c9cd56f-std6l ~]$ ./tokenRefresh.sh -f {CONFIG_DIR}/installOAA.properties -c "<Your_Cronjob_Schedule>"
    where "<Your_Cronjob_Schedule> is in the format defined at CronJob.
    For example, the cronjob schedule below will renew tokens every 45 minutes:
    ./tokenRefresh.sh -f /u01/oracle/scripts/settings/installOAA.properties -c "*/45 * * * *"

    Note:

    You should set your token renewal interval such that tokens are renewed well in advance of api.oauth.tokenexpiry to ensure no downtime.
To view the status of the cronjob run:
kubectl get cronjob -n oaans
The output will look similar to the following:
NAME       SCHEDULE      SUSPEND   ACTIVE   LAST SCHEDULE   AGE
oaamgmt-oaa-mgmt-r   */45 * * * *   False     0        3m48s           1h

Note:

Tokens that need to be retired should be revoked by invoking the appropriate OAM API. For more details, see Revoke Tokens REST Endpoints.

Troubleshooting the Token Refresh Cronjob

  • The cronjob will fail under the following product conditions:
    • OAuth is not enabled in OAA, for example install.global.service.security.oauth.enabled=false
    • The job is not able get the token from the OAM Server

    The above conditions will result in cronjob pods moving to Error status. If the cronjob pod errors, the job is retried a configurable number of times with increasing back-off intervals. The retry attempts are stopped once backoffLimit is reached. When the jobs have stopped due to errors, deleting the failed jobs will restart the cronjob. See Pod backoff failure policy .

  • To view the status of the cronjob jobs and pods run the following commands:
    1. Inside the management container get the name of the cronjob:
      kubectl get cronjob -n oaans
      The output will look similar to the following:
      NAME       SCHEDULE      SUSPEND   ACTIVE   LAST SCHEDULE   AGE
oaamgmt-oaa-mgmt-r   */45 * * * *   False     0        3m48s           1h
    2. Run the following command to get the list of jobs associated with the cronjob : 
      kubectl get jobs -l cronjob=oaamgmt-oaa-mgmt-r
      The output will look similar to the following:
      NAME                          COMPLETIONS   DURATION   AGE
oaamgmt-oaa-mgmt-r-28646612   1/1           5s         3m9s
    3. Run the following command to get the name of the pods associated with the job:
      kubectl get pods -l cronjob=oaamgmt-oaa-mgmt-r
      The output will look similar to the following if the job pod(s) completed successfully:
      NAME                                READY   STATUS      RESTARTS   AGE
oaamgmt-oaa-mgmt-r-28646620-brnk5   0/1     Completed   0          2m42s
      If there are problems with the job pod(s) you will see an Error status, for example:
      
NAME                                READY   STATUS      RESTARTS   AGE
oaamgmt-oaa-mgmt-r-28646620-brnk5   0/1     Error       0          2m42s
oaamgmt-oaa-mgmt-r-28646620-5495n   0/1     Error       0          15s
oaamgmt-oaa-mgmt-r-28646620-ftndp   0/1     Error       0          3s
    4. If the pod(s) status is Error you can diagnose the problem by viewing the logs of the most recent pod that ran. For example:
      kubectl logs oaamgmt-oaa-mgmt-r-28646620-ftndp

Accessing REST API's Using OAuth JWT from OAM

The instructions below relate only to external applications that use REST API's to communicate with OAA.

Note:

Internal communications and tasks performed in the OAA Administration console use the tokens configured in OAA and are refreshed by the cronjob.
  1. In order to use REST API's with OAuth JWT, you need to get an access token from OAM using either a 2-legged or 3-legged flow. See Runtime REST APIs for OAuth 12c.
  2. This access token should be passed using Authorization:Bearer <Token>. The example below shows using the OAA Admin API to perform a GET request:
    curl -i -X GET -H Authorization:Bearer <Token> -H <request-header>:<value> <PolicyUrl>/<resource-path>