11.13 REST API用のOAuth JWTの構成

OAAはデフォルトで、REST APIのAPIキー・セキュリティを使用するよう構成されています。管理者は、OAuth JSON Webトークン(JWT)を有効にしてREST APIにアクセスできるため、有効期間が短いアクセス・トークンを使用してセキュリティを強化できます。

ノート:

初期インストールの際、管理者は、APIキー・セキュリティのみモードを使用する必要があります。インストールが完了し、すべてのユースケースを検証したら、OAuth JWTセキュリティが必要な場合は、APIキー・セキュリティとOAuthの組合せモードにアップグレードして、ユースケースを再度検証する必要があります。すべてのユースケースが成功した場合は、必要に応じて、OAuthのみを使用するようアップグレードできます。

REST APIは、次の場合にOAAで使用されます:

• OAAポッドとサービス間の内部通信。
• OAA管理コンソールでタスクを実行する場合。
• 外部アプリケーションがREST APIを使用してOAAと通信する場合。使用可能なREST APIは次のとおりです:
  • OAA管理API
  • OAAランタイムAPI
  • OARMリスク・サービスAPI
  • OARMカスタマ・ケア・サービスAPI

管理者は、REST APIに次のいずれかのモードを使用するようOAAを構成できます:

• APIキー・セキュリティのみ
• APIキー・セキュリティとOAuthの組合せ
• OAuthのみ

ノート:

Oracle Universal Authenticator (OUA)でOAAを使用していて、OAuth JWTを使用する場合は、APIキー・セキュリティとOAuthの組合せモードを使用する必要があります。

APIキー・セキュリティのみ

APIキー・セキュリティ・モードはデフォルトの構成であり、初期インストール時に使用する必要があります。APIキー・セキュリティ・モードが構成されている場合、内部通信、OAA管理コンソールのタスクおよび外部REST APIアクセスは、APIキー・セキュリティを使用して実行されます。

APIキー・セキュリティのみモードを構成するには、「APIキー・セキュリティのみの構成」を参照してください。

外部アプリケーションを使用してREST APIにアクセスする場合、ユーザー名とパスワードはBasic認証で渡されます。次の例は、OAA管理APIを使用したGETリクエストの実行を示しています:

curl -i -X GET -H Authorization:Basic <Base64Encoded(<username>:<password>)> -H <request-header>:<value> <PolicyUrl>/<resource-path>

APIキー・セキュリティとOAuthの組合せ

APIキー・セキュリティとOAuthの両方が構成されている場合は、次のようになります:

• 内部通信およびOAA管理コンソールのタスクでは、APIキー・セキュリティが使用されます。
• 外部REST APIアクセスは、APIキー・セキュリティまたはOAuth JWTのいずれかを使用して実行できます。

APIキー・セキュリティとOAuthの組合せモードを構成するには、「APIキー・セキュリティとOAuthの組合せの構成」を参照してください。

外部アプリケーションを使用してREST APIにアクセスする場合、OAuthのアクセス・トークンは、Authorization:Bearer <Token>を使用して渡せます。APIキー・セキュリティの場合は、Authorization:Basic <Base64Encoded(<username>:<password>)>を使用して、ユーザー名とパスワードを渡します。

OAuthのみ

OAuthのみモードを使用すると、OAAの内部通信、OAA管理コンソールのタスクおよび外部REST APIアクセスは、OAuth JWTトークンのみを使用して実行されます。

OAuthのみモードを構成するには、「OAuthのみの構成」を参照してください。

外部アプリケーションを使用してREST APIにアクセスする場合、OAuthのアクセス・トークンは、Authorization:Bearer <Token>を使用して渡されます。次の例は、OAA管理APIを使用したGETリクエストの実行を示しています:

curl -i -X GET -H Authorization:Bearer <Token> -H <request-header>:<value> <PolicyUrl>/<resource-path>

11.13.1 APIキー・セキュリティのみの構成

次のステップは、APIキー・セキュリティのみの構成方法を示しています:

ノート:

これは、installOAA.propertiesに構成されているデフォルトのインストール方法です。

1. 次のパラメータを##3.OAUTH configuration## (installOAA.propertiesファイル)の下に設定します:

   install.global.service.security.basic.enabled=true
   install.global.service.security.oauth.enabled=false

installOAA.propertiesファイルの詳細は、「インストール用のプロパティ・ファイルの準備」を参照してください。

11.13.2 APIキー・セキュリティとOAuthの組合せの構成

次の項では、APIキー・セキュリティとOAuthの組合せモードの構成方法を示します。

installOAA.propertiesファイルの準備

1. 次のパラメータを##3.OAUTH configuration## (installOAA.propertiesファイル)の下に設定します:

   install.global.service.security.basic.enabled=true
   install.global.service.security.oauth.enabled=true

installOAA.propertiesファイルの詳細は、「インストール用のプロパティ・ファイルの準備」を参照してください。

OAA.shを使用したOAAの更新

installOAA.propertiesファイルを更新したら、OAA.shを実行して、OAAをこの構成で更新する必要があります:

1. 次のようにして、OAA管理ポッドに接続します:

   kubectl exec -n oaans -ti oaamgmt-oaa-mgmt-6f4c9cd56f-std6l -- /bin/bash

   これにより、OAA管理ポッド内のBashシェル内に移動します:

   [oracle@oaamgmt-oaa-mgmt-6f4c9cd56f-std6l /]$

2. OAA管理ポッド内で次を実行して、OAAをこの構成で更新します:

   [oracle@oaamgmt-oaa-mgmt-6f4c9cd56f-std6l /]$ cd ~
   [oracle@oaamgmt-oaa-mgmt-6f4c9cd56f-std6l ~]$ ./OAA.sh -f installOAA.properties

   ノート:

   これにより、<NFS_CONFIG_PATH>/installOAA.propertiesファイルが使用されます。

11.13.3 OAuthのみの構成

次の項では、OAuthのみモードの構成方法を示します。

installOAA.propertiesファイルの準備

1. 次のパラメータを##3.OAUTH configuration## (installOAA.propertiesファイル)の下に設定します:

   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>

   説明:
   • oauth.tokenexpiryは、UIトークンの有効期限(秒)です。UIトークンは、OAA管理コンソールを使用してタスクを実行するときに使用されます。デフォルト値は3600秒(1時間)です。
   • api.oauth.tokenexpiryは、API OAuthトークンの有効期限(秒)です。API OAuthトークンは内部通信に使用されます。デフォルト値は3600秒(1時間)です。
   • oauth.adminnameは、OAA-Admin-Roleグループのメンバーである管理ユーザーに設定する必要があります。詳細は、「LDAPストアでのユーザーとグループの作成」を参照してください。
   • oauth.adminpasswordは、oauth.adminnameに定義されたユーザーのbase64でエンコードされたパスワードです。
   • oauth.appusernameには、OAA-App-Userグループのメンバーであるすべてのユーザーを設定する必要があります。詳細は、「LDAPストアでのユーザーとグループの作成」を参照してください。

     ノート:

     このユーザーが、OAA-Admin-RoleグループとOAA-App-Userグループの両方に存在している場合は、oauth.adminnameと同じユーザーでもかまいません。
   • oauth.appuserpasswordは、oauth.appusernameに定義されたユーザーのbase64でエンコードされたパスワードです。
   たとえば:

   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==

installOAA.propertiesファイルの詳細は、「インストール用のプロパティ・ファイルの準備」を参照してください。

OAA.shを使用したOAAの更新

installOAA.propertiesファイルを更新したら、OAA.shを実行して、OAAをこの構成で更新する必要があります:

1. 次のようにして、OAA管理ポッドに接続します:

   kubectl exec -n oaans -ti oaamgmt-oaa-mgmt-6f4c9cd56f-std6l -- /bin/bash

   これにより、OAA管理ポッド内のBashシェル内に移動します:

   [oracle@oaamgmt-oaa-mgmt-6f4c9cd56f-std6l /]$

2. OAA管理ポッド内で次を実行して、OAAをOAuth JWT構成で更新します:

   [oracle@oaamgmt-oaa-mgmt-6f4c9cd56f-std6l /]$ cd ~
   [oracle@oaamgmt-oaa-mgmt-6f4c9cd56f-std6l ~]$ ./OAA.sh -f installOAA.properties

   ノート:

   これにより、<NFS_CONFIG_PATH>/installOAA.propertiesファイルが使用されます。

トークン・リフレッシュCronjobの構成

OAuth JWTアクセス・トークンは、有効期限が短いため、失効する前に更新する必要があります。OAAには、OAMからのトークン・リフレッシュを自動化するKubernetes cronjobが用意されています。管理者は必要に応じて、このcronjobを使用せずに、独自の自動化を記述することが可能です。cronjobを有効にするには、次のステップを実行します:

1. OAA管理ポッド内で次のスクリプトを実行して、トークンを自動的に更新するcronjobを作成します:

   [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>"

   ここで、<Your_Cronjob_Schedule>は、CronJobで定義された形式です。
   たとえば、次のcronjobスケジュールでは、45分ごとにトークンが更新されます:

   ./tokenRefresh.sh -f /u01/oracle/scripts/settings/installOAA.properties -c "*/45 * * * *"

   ノート:

   トークンがapi.oauth.tokenexpiryの前に余裕を持って更新されるようにトークンの更新間隔を設定し、停止時間が発生しないようにする必要があります。

cronjob実行のステータスを表示するには:

kubectl get cronjob -n oaans

出力は次のようになります:

NAME       SCHEDULE      SUSPEND   ACTIVE   LAST SCHEDULE   AGE
oaamgmt-oaa-mgmt-r   */45 * * * *   False     0        3m48s           1h

ノート:

リタイアする必要があるトークンは、適切なOAM APIを起動して失効させる必要があります。詳細は、「トークンの取消しRESTエンドポイント」を参照してください。

トークン・リフレッシュCronjobのトラブルシューティング

• cronjobは、本番の次のような条件で失敗します:
  • OAuthがOAAで有効になっていない場合(例: install.global.service.security.oauth.enabled=false)
  • ジョブがOAMサーバーからトークンを取得できない場合

  上の条件により、cronjobポッドのステータスがエラーになります。cronjobポッドがエラーになると、バックオフ間隔が長くなり、構成可能な回数分ジョブが再試行されます。再試行は、backoffLimitに達すると停止されます。ジョブがエラーで停止した場合は、失敗したジョブを削除すると、cronjobが再開されます。「Pod backoff failure policy」を参照してください。

• cronjobのジョブおよびポッドのステータスを表示するには、次のコマンドを実行します:
  1. 管理コンテナ内でcronjobの名前を取得します:

     kubectl get cronjob -n oaans

     出力は次のようになります:

     NAME       SCHEDULE      SUSPEND   ACTIVE   LAST SCHEDULE   AGE
     oaamgmt-oaa-mgmt-r   */45 * * * *   False     0        3m48s           1h

  2. 次のコマンドを実行して、cronjobに関連付けられたジョブのリストを取得します:

     kubectl get jobs -l cronjob=oaamgmt-oaa-mgmt-r

     出力は次のようになります:

     NAME                          COMPLETIONS   DURATION   AGE
     oaamgmt-oaa-mgmt-r-28646612   1/1           5s         3m9s

  3. 次のコマンドを実行して、ジョブに関連付けられたポッドの名前を取得します:

     kubectl get pods -l cronjob=oaamgmt-oaa-mgmt-r

     ジョブ・ポッドが正常に完了すると、出力は次のようになります:

     NAME                                READY   STATUS      RESTARTS   AGE
     oaamgmt-oaa-mgmt-r-28646620-brnk5   0/1     Completed   0          2m42s

     ジョブ・ポッドに問題がある場合は、次のように、Errorステータスが表示されます:

     
     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. ポッドのステータスがErrorの場合、実行された最新のポッドのログを表示することで問題を診断できます。たとえば:

     kubectl logs oaamgmt-oaa-mgmt-r-28646620-ftndp

OAuth JWTを使用したOAMからREST APIへのアクセス

次の手順が関連するのは、REST APIを使用してOAAと通信する外部アプリケーションのみです。

ノート:

内部通信やOAA管理コンソールで実行されるタスクでは、OAAで構成されたトークンが使用され、cronjobによってリフレッシュされます。

1. REST APIをOAuth JWTで使用するには、2レッグ・フローまたは3レッグ・フローを使用して、OAMからアクセス・トークンを取得する必要があります。OAuth 12cのランタイムREST APIに関する項を参照してください。
2. このアクセス・トークンは、Authorization:Bearer <Token>を使用して渡す必要があります。次の例は、OAA管理APIを使用したGETリクエストの実行を示しています:

   curl -i -X GET -H Authorization:Bearer <Token> -H <request-header>:<value> <PolicyUrl>/<resource-path>