LDAP ポリシー

概要

LDAP ポリシーは次の機能を提供します。

  • 認証: リクエストで指定されたユーザー認証情報が LDAP プロバイダの認証情報に照らして検証されます。LDAP ポリシーを使用すると、必要な DN 値がリクエストに含まれていない場合でも、任意の DN 値をパスワードと使用して認証を柔軟に行うことができます。たとえば、認証にメール / パスワードを使用する必要があるとします。次のオプションを使用できます。
    • リクエストにメールアドレスが含まれている場合は、このアドレスとパスワードを使用して LDAP 認証を行うことができます。
    • リクエストにメールアドレスがなく、他の DN 属性(電話番号など)がある場合、電話番号を使用して対応するメールアドレスを LDAP から取得し、メールアドレスとパスワードで認証を行うことができます。
  • 識別名(DN)検索: 認証に加えて、LDAP ポリシーを使用してリクエスト内のユーザー属性(メールなど)を識別し、そのユーザーに対して LDAP から他の DN 属性を取得するクエリを実行できます。取得した DN は変数に保存されます。

LDAP ポリシーは、保護リソースに対するアクセスを LDAP プロバイダのユーザー(管理ユーザー、組織ユーザー、デベロッパーなど)に限定する場合に使用します。特に、OAuth トークン アクセスが不要か、負荷が高すぎる場合に使用します。また、このポリシーでは API プロキシフローで使用するドメイン名のメタデータも取得できます。

たとえば、ユーザーが LDAP 認証に成功した場合にのみ API 呼び出しを実行できます。また、認証に成功した後にユーザーの DN(ドメイン名)属性を取得することもできます。

追加情報については、以下をご覧ください。

サンプル

ユーザー名 / パスワードによる認証

<Ldap name="4GLdapPolicy">
   <LdapResource>ldap1</LdapResource>
   <Authentication>
       <UserName ref="request.header.username"/>
       <Password ref="request.header.password"/>
       <Scope>subtree</Scope>
       <BaseDN></BaseDN> <!-- default is dc=apigee,dc=com -->
    </Authentication>
 </Ldap>

このサンプルでは、LDAP プロバイダで認証を行います。このポリシーは、認証を行うためにリクエストから LDAP にユーザー名とパスワードを渡します。

DN 属性による認証

<Ldap name="LdapPolicy">
   <LdapResource>ldap1</LdapResource>
   <Authentication>
       <Password ref="request.header.password"/>
       <SearchQuery>mail={request.header.mail}</SearchQuery>
       <Scope>subtree</Scope>
       <BaseDN></BaseDN> <!-- default is dc=apigee,dc=com -->
    </Authentication>
 </Ldap>

このポリシーは、リクエスト ヘッダーにあるユーザーの DN とメールアドレスを取得してから、リクエスト ヘッダーで指定されたパスワードを使用して LDAP でユーザー認証を行います。

LDAP の検索

<Ldap name="LdapPolicy">
    <!-- using a custom LDAP provider -->
    <LdapConnectorClass>com.custom.ldap.MyProvider</LdapConnectorClass>
    <LdapResource>MyLdap</LdapResource>
    <Search>
        <BaseDN></BaseDN> <!-- default is dc=apigee,dc=com -->
        <SearchQuery>mail={request.header.mail}</SearchQuery>
        <Attributes>
            <Attribute>address</Attribute>
            <Attribute>phone</Attribute>
            <Attribute>title</Attribute>
        </Attributes>
        <Scope></Scope> <!-- default is subtree -->
    </Search>
</Ldap>

このポリシーは、カスタム LDAP プロバイダを参照します。リクエスト ヘッダーのメールアドレスを使用してユーザーを識別し、ユーザーの住所、電話番号、役職などの情報を LDAP から取得します。取得した DN 属性は変数に格納されます。「ポリシー固有の変数」をご覧ください。

LDAP を検索して DN 属性を取得するには、リクエストに管理者の認証情報が必要です。

要素リファレンス

以下では、LDAP ポリシーの要素と属性について説明します。

要素

説明

Ldap

name 属性の親要素。ポリシー名を入力します。

LdapConnectorClass

カスタム LDAP プロバイダ(Apigee では提供されません)で LDAP ポリシーを使用する場合、完全修飾 LDAP コネクタクラスを指定します。これは、Apigee の ExternalLdapConProvider インターフェースを実装したクラスです。

LdapResource

LDAP リソースの環境名を入力します。詳細については、LDAP リソースを作成するをご覧ください。

BaseDN

すべてのデータが存在する LDAP のベースレベル。たとえば、Apigee の LDAP プロバイダでは、すべてのデータが dc=apigee,dc=com にあります。

Scope

  • object: 認証または検索は LDAP の基本レベルでのみ行われます。
  • onelevel: 認証または検索は基本レベルより 1 レベル下で行われます。
  • subtree(デフォルト): 認証または検索は基本レベルで行われ、基本より下位で完全に繰り返されます。

認証

Authentication

実装する認証動作の親要素。

UserName

次のいずれかの引数を使用する空の要素:

  • ref: リクエスト内のユーザー名の参照(request.header.username など)
  • value: ユーザー名

ユーザー名で認証を行わない場合や、リクエストにユーザー名が含まれていない場合は、この要素を組み込む必要はありません。

リクエストにユーザー名が含まれているが、ユーザー名以外の DN 属性(メールなど)でユーザーを認証する場合は、SearchQuery を含めて、パスワードに関連付けられたユーザーのメールを取得します。LDAP ポリシーでは、ユーザー名を使用して対応のメールアドレスを LDAP プロバイダに照会し、結果から認証を行います。

Password

次のいずれかの引数を使用する空の要素:

  • ref: リクエスト内のパスワードの参照(request.header.password
  • value: 暗号化されたパスワード

SearchQuery

ユーザー名以外の DN 属性(email など)を使用して認証を行う場合は、リクエストからユーザー名などの LDAP でユーザーを識別する DN 属性を取得するように LDAP ポリシーを構成します。

たとえば、LDAP でメールアドレスを格納する "mail" 属性が定義されているとします。

<SearchQuery>mail={request.header.mail}</SearchQuery>

Search

Search

実装する検索動作の親要素。

SearchQuery

リクエストまたはレスポンスでユーザーをメタデータで識別することで、この要素を使用して LDAP からユーザーの追加の DN 属性を取得できます。たとえば、リクエストにユーザーのメールが含まれ、LDAP でユーザーのメールアドレスを格納するための mail 属性が定義されている場合、次の設定を使用します。

<SearchQuery>mail={request.header.mail}</SearchQuery>

このクエリは、リクエストのメールに一致するメールを LDAP で検索します。ポリシーでは、Attributes 要素を持つユーザーの DN 属性を取得できるようになりました。

Attributes

1 つ以上の <Attribute> 要素を使用して、ユーザー用に取得する DN メタデータを指定します。1 つ以上の属性が必要です。

たとえば、SearchQuery によってユーザーが識別されると、次の例に示すように、ポリシーによって、ユーザーの住所、電話番号、役職など、ユーザーの DN 属性を取得できるようになります。

Attribute 値は、LDAP で定義されている DN 属性名です。

<Attributes>
  <Attribute>address</Attribute>
  <Attribute>phone</Attribute>
  <Attribute>title</Attribute>
</Attributes>

使用上の注意

Apigee Edge for Private Cloud では、API 呼び出しで LDAP プロバイダを利用できます。LDAP ポリシーを使用すると、アプリケーションで LDAP を使用してユーザー認証を行うことができます。メールアドレス、住所、電話番号など、ユーザーに関連するメタデータや属性などの識別名(DN)を LDAP から取得できます。後で API プロキシで使用できるように、取得した DN が変数に保存されます。

LDAP リソースを作成する

LDAP ポリシーでは、Apigee Edge で作成した LDAP リソースを利用します。LDAP リソースは LDAP リポジトリに接続情報を提供します。

LDAP リソースを作成して管理するには、次の API とペイロードを使用します。

API

LDAP リソースを作成(POST)するか、すべての LDAP リソースをリスト(GET)にします。

/v1/organizations/org_name/environments/environment/ldapresources

LDAP リソースの詳細の取得(GET)、更新(POST)、削除(DELETE)を行います。

/v1/organizations/org_name/environments/environment/ldapresources/ldap_resource_name

ペイロード

以下に、使用方法のコメントを含む XML ペイロードのサンプルを示します。

<LdapResource name="ldap1">
  <Connection>
    <Hosts>
      <!-- port is optional: defaults to 389 for ldap:// and 636 for ldaps:// -->
      <Host port="636">foo.com</Host>
    </Hosts>
    <SSLEnabled>false</SSLEnabled> <!-- optional, defaults to false -->
    <Version>3</Version> <!-- optional, defaults to 3-->
    <Authentication>simple</Authentication> <!-- optional, only simple supported -->
    <ConnectionProvider>jndi|unboundid</ConnectionProvider> <!-- required -->
    <ServerSetType>single|round robin|failover</ServerSetType> <!-- not applicable for jndi -->
    <!-- If using a custom LDAP provider, the fully qualified class: -->
    <LdapConnectorClass>com.custom.ldap.MyProvider</LdapConnectorClass>
  </Connection>
  <ConnectPool enabled="true"> <!-- enabled is optional, defaults to true -->
    <Timeout>30000</Timeout> <!-- optional, in milliseconds; if not set, no timeout -->
    <Maxsize>50</Maxsize> <!-- optional; if not set, no max connections -->
    <Prefsize>30</Prefsize> <!-- optional; if not set, no pref size -->
    <Initsize></Initsize> <!-- optional; if not set, defaults to 1 -->
    <Protocol></Protocol> <!-- optional; if not set, defaults to 'ssl plain' -->
  </ConnectPool>
  <Admin>
    <DN>cn=manager,dc=apigee,dc=com</DN>
    <Password>secret</Password>
  </Admin>
</LdapResource>

curl の例: LDAP リソースを作成する

次の例では、ldap1 という名前の LDAP リソースを作成します。

curl -X POST -H "Content-Type: application/xml" \
  https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/ldapresources \
  -u apigee_email:password -d \
  '<LdapResource name="ldap1">
    <Connection>
      <Hosts>
      <Host>foo.com</Host>
      </Hosts>
      <SSLEnabled>false</SSLEnabled>
      <Version>3</Version>
      <Authentication>simple</Authentication>
      <ConnectionProvider>unboundid</ConnectionProvider>
      <ServerSetType>round robin</ServerSetType>
    </Connection>
    <ConnectPool enabled="true">
      <Timeout>30000</Timeout>
      <Maxsize>50</Maxsize>
      <Prefsize>30</Prefsize>
      <Initsize></Initsize>
      <Protocol></Protocol>
    </ConnectPool>
    <Admin>
      <DN>cn=manager,dc=apigee,dc=com</DN>
      <Password>secret</Password>
    </Admin>
  </LdapResource>'

レスポンス コード

処理に成功または失敗したときにポリシーが返す HTML レスポンス コードは次のとおりです。

  • 成功: 200
  • 失敗: 401

Edge for Private Cloud でのカスタム LDAP プロバイダの使用

カスタム LDAP プロバイダを使用する

Apigee Edge for Private Cloud に付属の LDAP プロバイダは、LDAP ポリシーで使用できるように構成されています。ただし、カスタム LDAP プロバイダを使用している場合は、プロバイダを有効にして LDAP ポリシーをサポートする必要があります。手順は次のとおりです。

  1. LDAP プロバイダ クラスで、ExternalLdapConProvider インターフェースを実装します。
    public interface ExternalLdapConProvider {
      void doAuthentication(LdapBean LlapBean, String userDN, String password, String baseDN);
    
      void doSearchAndAuthentication(LdapBean LlapBean, String password, String baseDN, String query, int scope);
    
      Collection<Map<String, String[]>> doSearch(LdapBean LlapBean, String query,
        String baseDN, Collection<String> requiredAttributes, int scope);
    
      void closeConnections();
    }
  2. ポリシー構成の <LdapConnectorClass>(次のセクション)で、カスタム LDAP プロバイダの完全修飾クラス名を追加します。
  3. ファイル custom-ldap.jar_.zip をダウンロードします(右クリックして、[名前を付けて保存] を選択する必要が生じる場合があります)。
  4. ファイルを解凍します。
  5. custom-ldap.jar ファイルを環境に追加し、classpath に設定します。
  6. LDAP プロバイダに環境リソースを作成します。LDAP ポリシーの <LdapResource> 要素で環境リソース名を使用します。

Java 用の UnboundID LDAP SDK を使用する

LDAP ポリシーでは UnboundID LDAP SDK を使用できますが、最初にバージョン 2.3.1 をダウンロードして、それを各 Message Processor の classpaths に追加する必要があります。

LDAP ポリシーで UnboundID LDAP SDK を使用するには:

  1. ブラウザを開き、UnboundID LDAP SDK の Sourceforge ファイル リポジトリに移動します。
    https://sourceforge.net/projects/ldap-sdk/files/
  2. SDK のバージョン 2.3.1(SE または Standard Edition)を見つけて、そのバージョンの ZIP ファイルをダウンロードします。たとえば、unboundid-ldapsdk-2.3.1-se.zip をダウンロードします。
  3. 次の例のように、SDK ZIP ファイルから JAR ファイルを抽出します。
    unzip -j -d ~/tmp ~/Downloads/unboundid-ldapsdk-2.3.1-se.zip unboundid-ldapsdk-2.3.1-se/unboundid-ldapsdk-se.jar

    このコマンドを実行して、JAR ファイルだけを ~/tmp ディレクトリに展開します。これにより、-j を含むディレクトリ構造がドロップされますが、これはオプションです。

  4. 各 Message Processor ノードで、次を行います。
    1. JAR ファイルを Message Processor の /opt/apigee/edge-gateway/lib/thirdparty ディレクトリにコピーします。

      Edge により、/opt/apigee/edge-gateway/lib/thirdparty ディレクトリ内のすべてのサードパーティ ライブラリがクラスパスに追加されます。

    2. Message Processor を再起動します。
      /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

フロー変数

以下は、SearchQuery によって設定される LDAP ポリシー変数です。

変数

説明


ldap.policyName.execution.success

ポリシーの実行後、このフロー変数にはその結果に応じて "true" または "false" が保存されます。


ldap.policyName.search.result[index].
  attribute.attrName[index]=value

この変数の形式は柔軟です(特に、インデックスの場合)。複数の属性または複数の値を持つ属性から構成されます。インデックス番号は 1 から始まります。インデックス番号が指定されていない場合、デフォルトのインデックス番号は 1 になります。

ポリシーが住所、電話番号、メールアドレスを返した場合、次の変数を使用して最初の属性と値を取得できます。


ldap.policyName.search.result.attribute.address
ldap.policyName.search.result.attribute.phone
ldap.policyName.search.result.attribute.email

検索結果から 3 番目の住所属性を取得する場合は、次の変数を使用します。


ldap.policyName.search.result[3].attribute.address

1 つの属性に複数の値がある場合(たとえば、ユーザーに複数のメールアドレスがある場合)、検索結果から 2 番目のメールアドレスを取得するには、次の変数を使用します。


ldap.policyName.search.result.attribute.mail[2]

エラーコード

Edge ポリシーから返されるエラーは、エラーコード参照で説明されている一貫した形式に従います

このポリシーでは、次のエラーコードを使用します。

エラーコード メッセージ
InvalidAttributeName Invalid attribute name {0}.
InvalidSearchBase Search base can not be empty.
InvalidValueForPassword Invalid value for password field. It can not be empty.
InvalidSearchScope Invalid scope {0}. Allowed scopes are {1}.
InvalidUserCredentials Invalid user credentials.
InvalidExternalLdapReference Invalid external ldap reference {0}.
LdapResourceNotFound Ldap resource {0} not found.
BaseDNRequired Base DN required.
OnlyReferenceOrValueIsAllowed Only value or reference is allowed for {0}.
AttributesRequired At least one attribute required for search action.
UserNameIsNull User name is null.
SearchQueryAndUserNameCannotBePresent Both search query and username can not be present in the authentication action. Please specify either one of them.