1. Oracle Unified Directoryの管理
  2. RESTインタフェース
  3. REST APIサポートの構成

40 REST APIサポートの構成

OUDデータ管理およびSCIM REST APIサポートのためにOUDインスタンスで必要な構成について説明します。

このセクションには次のトピックが含まれます:

40.1 REST APIサポートのためのサーバー・インスタンスの構成

データ管理およびSCIM REST APIサポート用にOUDインスタンスを構成できます。

OUDでは、HTTP(S)接続ハンドラを介してデータ管理およびSCIMインタフェースを公開します。

ノート:

管理REST APIについては、「REST APIを使用したOracle Unified Directoryの管理」を参照してください。

接続ハンドラを有効にするには、次のいずれかを実行します:

40.2 OUDでのOAuthアイデンティティ・プロバイダとしてのOAMの構成

OUDでは、Open Authorization (OAuth)アイデンティティ・プロバイダとしてのOracle Access Management (OAM)の構成がサポートされています。

OUDバンドル・パッチ12.2.1.4.230928以降のリリース。 次の内容は、OUDバンドル・パッチ12.2.1.4.230928以降のリリースにのみ適用されます。

OUDでは、基本認証手法に加えて、OUDデータ管理およびSCIM REST API認証のためにOAMからのOAuth 2.0 JWTアクセス・トークンがサポートされています。OUDデータ管理およびSCIM REST APIのコールで、JWTトークンをベアラー・トークンとして使用できます。

この項の内容は、次のとおりです。

40.2.1 OAuthサービス認可の理解

OAM OAuth 2.0サービスは、委任された認可のみを処理するオープン標準のOAuthプロトコルです。

保護されたリソースへの安全なアクセスを支援するOAuthでは、次のロールがサポートされています:

  • リソース・サーバー: 保護されているリソースをホストするサーバー。アクセス・トークンを使用してリソースのリクエストを受け入れ、応答できます。リソース・サーバーは、OAMおよびクライアントと異なる場所にデプロイされます。
  • リソース所有者: これは、保護されているリソースへのアクセス権を付与することが可能なエンティティです。リソース所有者が個人である場合、エンド・ユーザーと呼ばれます。
  • クライアント: リソース所有者のかわりにその認可を使用して、保護されているリソースのリクエストを作成するアプリケーションです。
  • OAuthサービス: 認可サーバー、Oracle Access Managementを示します。リソース所有者を正常に認証し、認可を取得した後で、クライアントにアクセス・トークンを発行するサーバー。

OAuth 2.0は、認可レイヤーを追加し、クライアントのロールをリソース所有者のロールから分離します。

OAuth 2.0では、クライアントはリソース所有者によって制御され、リソース・サーバーによってホストされるリソースへのアクセスを要求し、リソース所有者の資格証明とは異なる資格証明が提供されます。保護されたリソースにアクセスするには、クライアントは、リソース所有者の資格証明を開示するのではなく、アクセス・トークン(特定のスコープ、期間およびその他のアクセス属性を識別する文字列)を取得します。サードパーティ・クライアントには、リソース所有者の承認を得て認可サーバーによってアクセス・トークンが付与されます。クライアントは、アクセス・トークンを使用して、リソース・サーバーの保護されたリソースにアクセスします。このシナリオは、リソースのリクエストを承認するリソース所有者が関与するため、3-legged OAuthフローと呼ばれます。3-legged認可の理解に関する項を参照してください。

40.2.2 OAuthサービスの構成

認可プロトコルを使用するには、まずOAuthサービスを構成する必要があります。

次のステップを実行して、OAuthサービスを構成します。

  1. OAMでのOAuthサービスの設定
  2. OUDでのOAuthアイデンティティ・プロバイダとしてのOAMの設定
  3. REST APIの起動
40.2.2.1 OAMでのOAuthサービスの設定

この項では、OAMにOAuthを設定する際の上位レベル・タスクについて説明します。

OAuth構成の前提条件

OUDを構成する前に、まずOAMでOAuthサービスを構成し、次に示す前提条件を実行する必要があります。

  1. REST APIコールを使用してアイデンティティ・ドメインを作成します。アイデンティティ・ドメインの作成に関する項を参照してください。
  2. REST APIコールを使用して新しいリソースを登録します。リソースの作成に関する項を参照してください。

    ノート:

    OUDで作成したリソース名およびスコープも構成する必要があります。たとえば、OUDResourceServerという名前のリソース・サーバーが作成され、スコープreadおよびwriteが設定されます。
  3. REST APIコールを使用して信頼できるクライアントを作成します。クライアントの作成に関する項を参照してください。

OAuth REST APIの詳細は、『Oracle Access ManagerでのOauth REST API』およびOracle Access Management OAuthサービスおよびOpenIDConnectの管理に関する項を参照してください。

40.2.2.2 OUDでのOAuthアイデンティティ・プロバイダとしてのOAMの設定

OAMは、OUDでOAuthアイデンティティ・プロバイダとして設定できます。

OUDでOAMをOAuthアイデンティティ・プロバイダとして構成するには、次のステップを実行します。

  1. create-identity-providerサブコマンドを指定してdsconfigコマンドライン・ユーティリティを実行し、OUDでOAMをOAuthアイデンティティ・プロバイダとして作成して有効にします。
    dsconfig create-identity-provider  \
--set enabled:true \
--set identity-mapper:Exact\ Match  \
--set oauth-resource-server:OUDResourceServer  \
--set oauth-scope:OUDResourceServer.read  \
--set oauth-token-issuer:http://host4:7777/oauth2  \
--type oauth \
--provider-name OAMProvider \
--hostname localhost \
--port 4444  \
--portProtocol LDAP \
--bindDN "cn=Directory Manager" \
--bindPasswordFile /home/oracle/pwd.txt \
--trustAll \
--no-prompt

    表40-1 OUDでのOAuthアイデンティティ・プロバイダ構成

    パラメータ 説明
    oauth-resource-server OAMでの作成時のリソース・サーバーの名前を示します。「OAMでのOAuthサービスの設定」のステップ2を参照してください。
    oauth-scope OAMでの作成時にリソース・サーバーに対して構成されたスコープを示します。これは複数値の引数です。「OAMでのOAuthサービスの設定」のステップ2を参照してください。

    ノート:値を指定する際は、リソース・サーバー名をスコープの前に付ける必要があります。たとえば、OUDResourceServer.readです。

    oauth-token-issuer OAMからのOAuthトークン発行者URLを示します。これは、OAMからOpenIDConnect検出エンドポイントを使用して取得できます。検出エンドポイントの詳細は、Oracle Access ManagerでのOpenIDConnect認証フローに関する項を参照してください。
    identity-mapper JWTトークンのユーザー(サブ要求)をOUDの有効なユーザーにマップするようにアイデンティティ・マッパーを構成する必要があります。アイデンティティ・マッパーを作成するには、「アイデンティティ・マッパーの概要」を参照してください。
    oauth-provider OAuth 2.0準拠のアイデンティティ・プロバイダの名前を示します。現在、OUDはOAMのみをサポートしています。そのため、デフォルト値はOAMです。
    oauth-token-x5t-algorithm アイデンティティ・プロバイダのX.509証明書のサムプリントの生成に使用されるアルゴリズムを示します。

    ノート: アクセス・トークン・ヘッダーには、同じアルゴリズムを使用して生成されたサムプリントを含める必要があります。デフォルト値はSHA-1で、アクセス・トークン・ヘッダーに、証明書のSHA-1フィンガープリントに設定された値を持つx5tプロパティが含まれていることを前提としています。ただし、アイデンティティ・プロバイダによって発行されたアクセス・トークンにx5tプロパティがなく、x5t#256プロパティのみが含まれている場合、ここでの値はSHA-256である必要があります。

    token-introspection-endpoint OAuthトークン・イントロスペクション・エンドポイントのURLを示します。これはオプションのパラメータです。構成すると、JWTトークンが本物であることを確認するためにOAuthサーバーにも問合せが行われます。OAM OAuthトークン・イントロスペクション・エンドポイントを取得するには、OpenIDConnect検出エンドポイントを使用します。これはPOST操作である必要があります。たとえば、http://host4:7777/oauth2/rest/token/introspectです。
    custom-claim-to-id-mapper アイデンティティ・マッパーがOUDの有効なユーザー・レコードにマップするために使用するアクセス・トークン内のカスタム要求の名前を示します。これはオプションのパラメータで、構成されていない場合、トークン要求内のsubが自動的にマップされます。
  2. RESTサーバー拡張でhttp-authentication-schemeを設定して、基本スキームに加えてベアラーを含めます。
    dsconfig set-extension-prop \
--extension-name REST\ Server  \
--add http-authentication-scheme:bearer \
--hostname localhost \
--port 4444  \
--portProtocol LDAP \
--bindDN "cn=Directory Manager"  \
--bindPasswordFile /scratch/nenekris/OUD/pwd.txt \
--trustAll \
--no-prompt

    ノート:

    RESTサーバー拡張はデフォルトで有効になっています。有効にしない場合は、「REST APIサポートのためのサーバー・インスタンスの構成」を参照してください。
  3. OAMの公開キー証明書(JWTトークン署名キー)をOUDのJKSトラストストアにインポートして、REST APIコールで提示されたときにOUDがJWTトークンの署名検証を実行できるようにします。

    ノート:

    OAMの信頼証明書は、jwks_uriを使用してOpenIDConnect検出エンドポイントを使用して取得できます: http://<ManagedServerHost>:<ManagedServerPort>/oauth2/rest/security

    検出エンドポイントの詳細は、Oracle Access ManagerでのOpenIDConnect認証フローに関する項を参照してください。

40.2.2.3 REST APIの起動

OAuthのデータ管理またはSCIM REST APIを起動できます。

次のサンプルRESTリクエストは、cURLコマンドを使用してOUDデータ管理REST APIを起動し、特定のペイロードを使用してリクエストをhttps://<OUD HOST>:<HTTP Port>/REST/v1/directoryに送信する方法を示しています。

基本認証の使用:

curl -X GET -u '<userdn>':<password> http://<OUD Host>:<HTTP Port>/rest/v1/directory/dc=example,dc=com?scope=sub&filter=(objectclass=*) -H 'cache-control: no-cache' -H 'content-type: application/json'

ヘッダーにベアラー・トークンを使用:

curl -X GET -H "Authorization: Bearer {token}" http://<OUD Host>:<HTTP Port>/rest/v1/directory/dc=example,dc=com?scope=sub&filter=(objectclass=*) -H 'cache-control: no-cache' -H 'content-type: application/json'