概要
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 ポリシーの要素と属性について説明します。
要素 |
説明 |
---|---|
|
name 属性の親要素。ポリシー名を入力します。 |
|
カスタム LDAP プロバイダ(Apigee では提供されません)で LDAP ポリシーを使用する場合、完全修飾 LDAP コネクタクラスを指定します。これは、Apigee の |
|
LDAP リソースの環境名を入力します。詳細については、LDAP リソースを作成するをご覧ください。 |
|
すべてのデータが存在する LDAP のベースレベル。たとえば、Apigee の LDAP プロバイダでは、すべてのデータが |
|
|
認証 |
|
|
実装する認証動作の親要素。 |
|
次のいずれかの引数を使用する空の要素:
ユーザー名で認証を行わない場合や、リクエストにユーザー名が含まれていない場合は、この要素を組み込む必要はありません。 リクエストにユーザー名が含まれているが、ユーザー名以外の DN 属性(メールなど)でユーザーを認証する場合は、 |
|
次のいずれかの引数を使用する空の要素:
|
|
ユーザー名以外の DN 属性(email など)を使用して認証を行う場合は、リクエストからユーザー名などの LDAP でユーザーを識別する DN 属性を取得するように LDAP ポリシーを構成します。 たとえば、LDAP でメールアドレスを格納する "mail" 属性が定義されているとします。
|
Search |
|
|
実装する検索動作の親要素。 |
|
リクエストまたはレスポンスでユーザーをメタデータで識別することで、この要素を使用して LDAP からユーザーの追加の DN 属性を取得できます。たとえば、リクエストにユーザーのメールが含まれ、LDAP でユーザーのメールアドレスを格納するための
このクエリは、リクエストのメールに一致するメールを LDAP で検索します。ポリシーでは、Attributes 要素を持つユーザーの DN 属性を取得できるようになりました。 |
|
1 つ以上の たとえば、 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 ポリシーをサポートする必要があります。手順は次のとおりです。
- 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(); }
- ポリシー構成の
<LdapConnectorClass>
(次のセクション)で、カスタム LDAP プロバイダの完全修飾クラス名を追加します。 - ファイル custom-ldap.jar_.zip をダウンロードします(右クリックして、[名前を付けて保存] を選択する必要が生じる場合があります)。
- ファイルを解凍します。
- custom-ldap.jar ファイルを環境に追加し、classpath に設定します。
- LDAP プロバイダに環境リソースを作成します。LDAP ポリシーの
<LdapResource>
要素で環境リソース名を使用します。
Java 用の UnboundID LDAP SDK を使用する
LDAP ポリシーでは UnboundID LDAP SDK を使用できますが、最初にバージョン 2.3.1 をダウンロードして、それを各 Message Processor の classpaths に追加する必要があります。
LDAP ポリシーで UnboundID LDAP SDK を使用するには:
- ブラウザを開き、UnboundID LDAP SDK の Sourceforge ファイル リポジトリに移動します。
https://sourceforge.net/projects/ldap-sdk/files/
- SDK のバージョン 2.3.1(SE または Standard Edition)を見つけて、そのバージョンの ZIP ファイルをダウンロードします。たとえば、unboundid-ldapsdk-2.3.1-se.zip をダウンロードします。
- 次の例のように、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
を含むディレクトリ構造がドロップされますが、これはオプションです。 - 各 Message Processor ノードで、次を行います。
- JAR ファイルを Message Processor の
/opt/apigee/edge-gateway/lib/thirdparty
ディレクトリにコピーします。Edge により、
/opt/apigee/edge-gateway/lib/thirdparty
ディレクトリ内のすべてのサードパーティ ライブラリがクラスパスに追加されます。 - Message Processor を再起動します。
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
- JAR ファイルを Message Processor の
フロー変数
以下は、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. |