PostmanでのOracle Advanced Authentication REST APIの使用

イントロダクション

このチュートリアルでは、Postmanを使用したOracle Advanced AuthenticationへのREST APIコール(通常はREST APIテストに使用されるソフトウェア)について説明します。

目的

Oracle Advanced Authentication REST APIは、Oracle Advanced Authenticationを構成および管理できるように、Oracle Advanced AuthenticationとRESTクライアントを統合する方法を提供します。REST APIエンドポイントの完全なリストは、OAA管理APIを参照してください。

このチュートリアルでは、Oracle Advanced Authentication Postmanコレクションをダウンロードしてインポートし、最も一般的なPostmanリクエストの一部をテストする方法を学習します。

前提条件

このチュートリアルを完了するには、次のものが必要です。

• 実行中のOracle Advanced Authenticationインストール
• モバイル・デバイスにインストールされたOracle Mobile Authenticator
• RESTアーキテクチャ・スタイルの理解
• ネイティブPostmanクライアントv8.0.6以降がインストールされている
• jsonファイルOracle_Advanced_Authentication_REST_API.postman_collection.json、Oracle_Advanced_Authentication_Example_Environment.postman_environment.json

Oracle Advanced Authentication Postman Collectionのインストール

Postmanでの環境パラメータの設定

1. Postmanを開き、「ファイル」→「インポート」を選択します。

2. 「インポート」ダイアログ・ボックスの「ファイル」タブで、「ファイルのアップロード」を選択します。Oracle_Advanced_Authentication_Example_Environment.postman_environment.jsonを選択し、「Open」をクリックします。

3. 左側のメニューで、をクリックします。

4. 表示された環境リストで、「Oracle Advanced Authentication Example Environment」の右側にある省略記号をクリックし、「Duplicate」をクリックします。

   

   図uplicate_env.jpgの説明

5. 元の環境の上に表示されるOracle Advanced Authentication Example Environment Copyで、省略記号をクリックしてOracle Advanced Authentication Environment for REST APIsに名前を変更します。

6. 「初期値」および「現在の値」に次の値を入力して、新しい環境の環境変数を更新します。完了したら、タブで「保存」、「X」の順にクリックして閉じます。

   • oaa-admin: Oracle Advanced Authenticationのホスト名および管理ポート(https://oaa.example.comなど)
   • oaa-policy: Oracle Advanced Authenticationのホスト名およびポリシー・ポート(https://oaa.example.comなど)
   • oaa-runtime: Oracle Advanced Authenticationのホスト名およびランタイム・ポート(https://oaa.example.comなど)
   • RELEASENAME: Oracle Advanced Authentication設定に割り当てられたRELEASENAME (oaainstallなど)。これは、OAAのインストール時にcommon.deployment.nameに渡された値です。
   • oaappolicyapikey: Oracle Advanced Authentication設定のoaapolicyapikey(a5764d4ef6b71129f38a2d8ddc88b6060653d3c8など)。これは、OAAのインストール時にinstall.global.policyapikeyに渡された値です。
   • oaaapikey: Oracle Advanced Authentication設定のoaaapikey(a5764d4ef6b71129f38a2d8ddc88b6060653d3c8など)。これは、OAAのインストール時にinstall.global.uasapikeyに渡された値です。

   ノート: oaa-admin、oaa-policyおよびoaa-runtime (spui)のURLがわからない場合は、OAA Kubernetesクラスタで次を実行します:

   kubectl get pods -n <namespace> | grep 'oaa-admin\|oaa-policy\|spui'
   

   次に、各ポッドに対して次を実行してURLを取得します:

   kubectl exec -it <pod> -n <namespace> -- cat serviceurl.txt
   

   環境は次のようになります。

   

   図Environment.jpgの説明

   ノート:前述の例のURL値は、NodePortを使用したOAAインストールを想定しているため、各ポッドのポート番号がURLに定義されています。OAAインストールでイングレスを使用する場合は、すべてのケースでイングレスURLを使用します。

7. 「環境」ドロップダウン・リストをクリックし、リストから更新された環境を選択します。

   

   図Environment_selection.jpgの説明

Postmanコレクションのインポート

1. Oracle Advanced Authentication REST API Postmanコレクションをインポートするには、Postmanメイン・ページで「ファイル」→「インポート」を選択します。

2. 「インポート」ダイアログ・ボックスの「ファイル」タブで、「ファイルのアップロード」を選択します。ファイルOracle_Advanced_Authentication_REST_API.postman_collection.jsonを選択し、「Open」、「Import」の順にクリックします。

   左側のメニューで「コレクション」をクリックします。コレクションは次のように表示されます。

   

   図collection.jpgの説明

REST APIのテスト

この項では、Oracle Advanced AuthenticationのPostmanコレクション内のいくつかのリクエストを実行します。

ノート: SSL証明書の検証エラーを回避するには、「ファイル」 > 「設定」に移動し、「一般」タブで「SSL証明書の検証」を「オフ」に設定します。

API統合エージェントの作成

この項では、API統合エージェントを作成します。

1. 「コレクション」タブで、「Oracle Advanced Authentication REST API」→「システム・エンティティを定義するREST API」→「agent/v1」にナビゲートします。

2. 「新規API統合エージェントの作成」を選択します。このリクエストは、/oaa-policy/agent/v1エンドポイントへのPOSTリクエストを行い、本文の情報に基づいてAPIAgentというAPI統合エージェントを作成します:

   

   図createapiagent.jpgの説明

3. 「送信」をクリックします。

4. レスポンスで、Status: 200 OKが表示され、作成された統合エージェントに関する詳細がレスポンス本文に表示されることを確認します。次の項で使用するため、返されたagentgidをノートにとります。

   

   図createapiagentsuces.jpgの説明

保証レベルの作成

この項では、作成した統合エージェントの保証レベルを作成します。

1. 「コレクション」タブで、「Oracle Advanced Authentication REST API」→「システム・エンティティを定義するREST API」→「AssuranceLevel/v1」にナビゲートします。

2. 「保証レベルの定義」を選択します。このリクエストは、/oaa-policy/assuranceLevel/v1エンドポイントへのPOSTリクエストを行い、AssuranceLevel1という統合エージェントの保証レベルを作成します。本体で、前に返された値と一致するようにagentidの値を編集します。

   

   図createassurancelvl.jpgの説明

3. 「送信」をクリックします。

4. レスポンスで、Status: 200 OKが表示され、作成された保証レベルの詳細がレスポンス本文に表示されることを確認します。

   

   図createassurancelvlsuccess.jpgの説明

グループの作成

この項では、ファクタのアクション・グループとIPアドレスのグループを作成します。これらのグループは、以前に作成した統合エージェントおよび保証レベルのポリシーおよびルールに後で割り当てられます。

1. 「コレクション」タブで、「Oracle Advanced Authentication REST API」→「システム・エンティティを定義するREST API」→「group/v1」にナビゲートします。

2. 「新規ファクタ・グループの作成」を選択します。このリクエストは、/oaa-policy/group/v1エンドポイントへのPOSTリクエストを行い、FactorRuleGrp1というエージェントのグループを作成します。本文内で、前に返された値と一致するようにagentidの値を編集します。この例では、グループはChallengeEmailとChallengeOMATOTPの2つの要素を設定します。

   

   図createfactorgrp.jpgの説明

3. 「送信」をクリックします。

4. レスポンスで、Status: 200 OKが表示され、作成されたグループの詳細がレスポンス本文に表示されることを確認します。後でこのグループをポリシーに割り当てるために使用するため、groupidをノートにとります。

   

   図createfactorgrpsuces.jpgの説明

5. group/v1の下の現在のコレクションで、「IPタイプの新規グループの作成」を選択します。このリクエストは、/oaa-policy/group/v1エンドポイントへのPOSTリクエストを行い、SecureIPという統合エージェントのグループを作成します。本文内で、前に返された値と一致するようにagentgidの値を編集します。この例では、値セクションでIPの198.51.100.1を198.51.100.3に設定します。

   

   図createipgrp.jpgの説明

6. 「送信」をクリックします。

7. レスポンスで、Status: 200 OKが表示され、作成されたグループの詳細がレスポンス本文に表示されることを確認します。後でこのグループをポリシーに割り当てるために使用するため、groupidをノートにとります。

   

   図createipgrpsuces.jpgの説明

ポリシーの作成

この項では、前に作成した保証レベルと統合エージェントのポリシーを作成します。

1. 「コレクション」タブで、「Oracle Advanced Authentication REST API」→「システム・エンティティを定義するREST API」→「ポリシー/v1」にナビゲートします。

2. 「新規ポリシーの作成」を選択します。このリクエストは、/oaa-policy/policy/v1エンドポイントへのPOSTリクエストを行い、以前に作成した統合エージェントおよびPolicy1という保証レベルのポリシーを作成します。本体で、前に返された値と一致するようにagentgidの値を編集します。

   

   図createpolicy.jpgの説明

3. 「送信」をクリックします。

4. レスポンスで、Status: 200 OKが表示され、作成されたポリシーに関する詳細がレスポンス本文に表示されることを確認します。後でこのポリシーにルールを割り当てるため、policygidをノートにとります。

   

   図createpolicysuces.jpgの説明

ポリシー・ルールの作成

この項では、ポリシーのポリシー・ルールを作成します。

1. 「コレクション」タブで、Oracle Advanced Authentication REST API > REST API for Define System Entities -> policy/v1 -> {policygid} -> rule > {ruleid}に移動します。

2. 「ポリシーの新規ルールの定義」を選択します。このリクエストは、/oaa-policy/policy/v1/:policygid/ruleエンドポイントへのPOSTリクエストを作成します。「パラメータ」タブで、前に返されたポリシーの値と一致するようにpolicygidの値を編集します。本文のconditionMapで、expressionおよびvaluesの下の値を編集し、前に作成したSecureIPグループのgroupIdに設定します。resultsで、前に作成したFactorGroup1グループのgroupIdと一致するようにactionの値を設定します。

   

   図createrule.jpgの説明

   前述のルールでは、認証リクエストを行うエンド・ユーザーのIPアドレスがSecureIPグループで定義されているIPアドレスである場合、認証のファクタをFactorGroup1で定義されているものに設定します。

3. 「送信」をクリックします。

4. レスポンスで、Status: 200 OKが表示され、作成されたルールの詳細がレスポンス本文に表示されることを確認します。後で参照できるように、rulegidをノートにとります。

   

   図createrulesuces.jpgの説明

ユーザー・プリファレンスの作成

この項では、ユーザーuser1を作成し、そのファクタ・プリファレンスを登録します。

1. 「コレクション」タブで、「Oracle Advanced Authentication REST API」→「ユーザー・プリファレンスのREST API」→「プリファレンス/v1」にナビゲートします。

2. 「User Preferences are create/registered」を選択します。このリクエストは、/oaa/runtime/preferences/v1エンドポイントへのPOSTリクエストを作成します。ボディで、作成するuserIdおよび対応するgroupIdを入力します。次の例では、user1がDefaultグループに作成され、電子メールおよびOMATOTP係数のユーザーを登録します。電子メール・アドレスの値を有効な電子メール・アドレスに変更します。OMATOTPのsecret_keyを、Oracle Mobile Authenticatorアプリケーションで使用する任意の値に変更します。

   

   図createuserprefs.jpgの説明

3. 「送信」をクリックします。

4. レスポンスで、Status: 200 OKが表示され、ユーザーとそのプリファレンスが正常に作成され、登録されていることを確認します。

   

   図createuserprefssuces.jpgの説明

ユーザーへのチャレンジ、チャレンジの初期化および検証

この項では、「ポリシー・ルールの作成」で前に作成したルールに対してuser1に対するユーザー・チャレンジをテストします。ルールが検証されると、そのユーザーに登録されたファクタが返されます。認証するファクタを選択すると、初期化リクエストが送信され、そのファクターのOTPの入力を求めるプロンプトが表示されます。有効なファクタOTPが入力され、検証されます。

この項を開始する前に、「ユーザー・プリファレンスの作成」に入力されたsecret_key値にKeyを設定して、Oracle Mobile AuthenticatorにOracleアカウントが追加されていることを確認します。「Oracle Mobile Authenticatorでのアカウントの構成」を参照してください

1. 「コレクション」タブで、「Oracle Advanced Authentication REST API」→「ユーザー・チャレンジ用のREST API」→「チャレンジ・ユーザー」、「チャレンジの初期化」、「チャレンジの検証」にナビゲートします。

2. 「チャレンジ・ユーザー」を選択します。このリクエストは、/oaa/runtime/authn/v1エンドポイントへのPOSTリクエストを作成します。「本文」に、user1のuserIdおよび対応するgroupIdを入力します。次の例では、統合エージェントAPIの作成で前に作成したAPI統合エージェントに対してuser1に対してチャレンジが行われます。このAPIエージェントのclientSecretおよびclientIdの値を入力します。ipAddrに、前に作成したSecureIPグループで定義されたIPを入力します。

   

   図challengeuser.jpgの説明

3. 「送信」をクリックします。

4. レスポンスで、Status: 200 OKが表示されていることを確認します。Authentication Requiredを示すOAA-40001メッセージが返されます。user1 (電子メールおよびOMATOTP)に登録されたファクタは、correlationIdとともに返されます。後続のリクエストで使用するcorrelationIdをノートにとります。

   

   図challengeusersuces.jpgの説明

5. 「チャレンジ・ユーザー」、「チャレンジの初期化」、「チャレンジの検証」で、「チャレンジの初期化」を選択します。これにより、/oaa/runtime/authn/v1エンドポイントへのPUTリクエストが行われます。「本文」に、前のレスポンスで返されたcorrelationIdを入力します。この例では、OMATOTP係数を使用するように選択します。

   

   図initchallenge.jpgの説明

6. 「送信」をクリックします。

7. レスポンスで、Status: 200 OKが表示されていることを確認します。OMATOTPのAuthentication Requiredを示すOAA-40001メッセージが返されます。関連するcorrelationIdのnonce値が返されます。次のリクエストを使用するには、nonce値をノートにとります:

   

   図initchallengesuces.jpgの説明

8. 「チャレンジ・ユーザー」、「チャレンジの初期化」、「チャレンジの検証」で、「チャレンジの検証」を選択します。これにより、/oaa/runtime/authn/v1エンドポイントへのPUTリクエストが行われます。「本文」にcorrelationIdを入力し、前のレスポンスで返されたnonceを入力します。ChallengeAnswerに、Oracle Mobile Authenticatorからの有効なOTPを入力します。

   

   図validate.jpgの説明

9. 「送信」をクリックします。

10. レスポンスで、Status: 200 OKが表示されていることを確認します。OTPの検証に成功すると、ユーザーがAuthenticatedであることを示すOAA-40004メッセージが返されます。

    

    図validateuces.jpgの説明

さらに学ぶ

• Oracle Advanced認証
• OAA管理API
• OAAランタイムAPI
• マルチファクタ認証のためのOracle RADIUSエージェントとOracle Advanced Authenticationの使用
• Oracle Access ManagementとOracle Advanced認証の統合

フィードバック

このチュートリアルに関するフィードバックは、[e-mail]までお問い合わせください。

謝辞

• 作成者 -ロシア・ホジソン

その他の学習リソース

docs.oracle.com/learnの他のラボを調べるか、Oracle Learning YouTubeチャネルでさらに無料の学習コンテンツにアクセスします。さらに、education.oracle.com/learning-explorerにアクセスしてOracle Learning Explorerにします。

製品ドキュメントは、Oracleヘルプ・センターを参照してください。

---

タイトルおよび著作権情報

Use Oracle Advanced Authentication REST APIs with Postman

F53376-01

February 2022

Copyright © 2022, Oracle and/or its affiliates.