
概要
LDAP ポリシーは次の機能を提供します。
- 認証: リクエストで指定されたユーザー認証情報が LDAP プロバイダの認証情報に照らして検証されます。LDAP ポリシーを使用すると、必要な DN 値がリクエストに含まれていない場合でも、任意の DN 値をパスワードと使用して認証を柔軟に行うことができます。たとえば、認証にメール / パスワードを使用する必要があるとします。次のオプションを使用できます。
- リクエストにメールアドレスが含まれている場合は、このアドレスとパスワードを使用して LDAP 認証を行うことができます。
- リクエストにメールアドレスがなく、他の DN 属性(電話番号など)がある場合、電話番号を使用して対応するメールアドレスを LDAP から取得し、メールアドレスとパスワードで認証を行うことができます。
- 識別名(DN)検索: 認証に加えて、LDAP ポリシーを使用してリクエスト内のユーザー属性(メールなど)を識別し、そのユーザーに対して LDAP から他の DN 属性を取得するクエリを実行できます。取得した DN は変数に保存されます。
LDAP ポリシーは、保護リソースに対するアクセスを LDAP プロバイダのユーザー(管理ユーザー、組織ユーザー、デベロッパーなど)に限定する場合に使用します。特に、OAuth トークン アクセスが不要か、負荷が高すぎる場合に使用します。また、このポリシーでは API プロキシフローで使用するドメイン名のメタデータも取得できます。
たとえば、ユーザーが LDAP 認証に成功した場合にのみ API 呼び出しを実行できます。また、認証に成功した後にユーザーの DN(ドメイン名)属性を取得することもできます。
追加情報については、以下をご覧ください。
サンプル
ユーザー名 / パスワードによる認証
<Ldap name="4GLdapPo>licy<" Ld>apRes<ourceldap1/Ld>apRe<source Auth>enticati<on UserName ref="request.he>ader.use<rname"/ Password ref=">request.<heade>r.passw<ord&qu>ot;/ < Sc><opesubt>r<ee/Scope BaseDN/BaseDN !-- >defau<lt is dc=apigee>,d<c=com> -- /Authentication /Ldap
このサンプルでは、LDAP プロバイダで認証を行います。このポリシーは、認証を行うためにリクエストから LDAP にユーザー名とパスワードを渡します。
DN 属性による認証
<Ldap name="LdapPo>licy<" Ld>apRes<ourceldap1/Ld>apRe<source Auth>enticati<on Password ref="request.he>ader.pas<sword">/ SearchQuerymail={<request.head>er.mail}</Sear>chQuery< > Scopes<ubtree></Scope > < BaseDN/BaseDN !-- default is> dc=a<pigee,dc=com --> < /A>uthentication /Ldap
このポリシーは、リクエスト ヘッダーにあるユーザーの DN とメールアドレスを取得してから、リクエスト ヘッダーで指定されたパスワードを使用して LDAP でユーザー認証を行います。
LDAP の検索
<Ldap name="LdapPo>licy&<quot; !-- using a custom LDAP p>rovid<er -- LdapConn>ectorClasscom.custom.ldap.<MyProvider/LdapConn>ector<Class Ld>apReso<urceMyLdap/Ld>apRes<ource<>/span> Searc<h >< Bas>e<DN/BaseDN !-- default is dc=apigee>,dc=com -<- S>earchQuerymail={request.he<ader.mail}/S>earchQuer<y >Attributes < > Attrib<uteaddress>/Attribute < > Attr<ibutephone>/Attribute < > Attr<ibutetitle>/Attribut<e />Attribute<s >< S>c<ope/Scope !-- d‘efault ’is >subtr<ee -- > < /Se>arch /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="l>dap<1" >Conne<ction> Ho<sts !-- port is optional: defaults to 389 for ldap:// and 636 for l>daps://< -- Host >port=&q<uot;6>36&qu<ot;foo>.com/<Host />Hosts< SSLEna>b<ledfalse/SSLEnabled !-- optional, >defau<lts to >f<alse -- > < Version3/Version !-- optio>nal, <defaults to 3->- <Authentications>i<mple/Authentication !-- optional, only> simp<le supported -- > ConnectionPr<oviderjndi|unboundi>d</ConnectionProv>ider <!-- required >-- ServerSetTypesingle|<round robin|fa>i<lover/ServerSetType !-- not ap>plica<ble for jndi -- !-- If using a custom LDAP provider, the fully> qual<ified class: -- > LdapConnectorClasscom.cu<stom.ldap.MyProvide>r/L<dapConnecto>rCl<ass /Connection Connec>t<Pool enabled="true" !-- enabled is> opti<onal, d>efaul<ts to tr>u<e -- Timeout30000/Timeout !-- optional, in milliseco>nds; <if not >se<t, no ti>m<eout -- Maxsize50/Maxsize !-- optional; if >not s<et, no m>ax< connecti>o<ns -- Prefsize30/Prefsize !-- optiona>l; if< not set><, no pref> <size -- Initsize/Initsize !-- optional>; if <not set,>< defaults> <to 1 -- Protocol/Protocol !-- optional; if not s>et,< defaults to> <39;ss>l pla<in>' -- /ConnectPool A<dmi>n < DNcn=ma>nager,<dc=apigee>,dc<=com/D>N< 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:passwor<d -d \ 'LdapResourc>e nam<e="ld>ap1&quo<t; > Conne<ctio>n < Host>s < Hostf>oo.com/<Host > /Hos<ts SS>LEnable<dfalse/>S<SLEnable>d < Version3/Vers>ion < Authenticat>ionsimp<le/Authentication > Con<nectionProviderunbo>undid/C<onnectionProv>ider <ServerSetTyper>ound <robin/Serve>rSetT<ype /Connection Co>nnectPo<ol enab>led=&<quot;tru>e"< >Ti<meout300>00/Time<out > <Maxsize50>/Maxsiz<e ><Prefsize3>0/Prefs<ize >< Initsiz>e/Ini<tsize >Proto<col/P>rotocol< > /ConnectPool Admin < > DNcn=<manager,>dc=api<gee,dc=co>m/DN < >Pas<swordsecret/P>assword /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. |