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

Apigee 提供のプロバイダではなくカスタム LDAP プロバイダで 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: ユーザー名

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

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

Password

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

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

SearchQuery

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

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

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

検索

Search

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

SearchQuery

リクエストまたはレスポンスのメタデータを使用してユーザーを識別します。この要素を使用してユーザーの追加の DN 属性を LDAP から取得します。たとえば、リクエストにユーザーのメールアドレスが含まれ、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 をダウンロードします。リンクを右クリックして [Save As] を選択してください。
  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 ディレクトリのすべてのサードパーティ ライブラリを classpath に追加します。

    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.