LDAP 政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

優勢

LDAP 政策提供以下功能:

  • 驗證:系統會針對 LDAP 供應商中的憑證驗證要求中提供的使用者憑證。LDAP 政策可讓您在驗證方面有許多彈性,可讓您搭配密碼使用任何 DN 值與密碼,即使要求中沒有所需的 DN 值也一樣。舉例來說,假設您需要使用電子郵件 / 密碼進行驗證。可能的選項如下:
    • 如果電子郵件包含在要求中,您可以直接將該電子郵件與密碼用於 LDAP 驗證。
    • 如果要求中沒有電子郵件,但有其他 DN 屬性 (例如電話號碼),您可以使用電話號碼從 LDAP 取得對應的電子郵件,然後使用電子郵件/密碼進行驗證。
  • 區分名稱 (DN) 搜尋:除了驗證之外,您也可以使用 LDAP 政策在要求中識別使用者屬性 (例如電子郵件),並執行查詢來從 LDAP 擷取該使用者的其他 DN 屬性。擷取的 DN 會儲存在變數中。

當您限制只有 LDAP 供應商 (例如管理員使用者、機構使用者和開發人員) 可存取受保護的資源時,請使用 LDAP 政策,特別是在不需要或過度使用 OAuth 權杖時。這項政策也設計為擷取網域名稱中繼資料,以用於 API Proxy 流程。

舉例來說,您可以只在使用者成功透過 LDAP 通過驗證時執行 API 呼叫,並在驗證成功後擷取使用者的 DN (網域名稱) 屬性。

若需更多資訊,請參閱:

範例

使用者名稱/密碼驗證

<Ldap name="4GLdapPolicy">
   <LdapResource>ldap1</LdapResource>
   <Authentication>
       <UserName ref="request.header.username"/>
       <Password ref="request.header.password"/>
       <Scope>subtree</Scope>
       <BaseDN ref="apigee.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 ref="apigee.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 ref="apigee.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

具有名稱屬性的父項元素,供您輸入政策名稱。

LdapConnectorClass

搭配自訂 LDAP 提供者 (並非由 Apigee 提供) 使用 LDAP 政策時,請指定完整的 LDAP 連接器類別。 這是您實作 Apigee ExternalLdapConProvider 介面的類別。

LdapResource

輸入 LDAP 資源的環境名稱。詳情請參閱「建立 LDAP 資源」。

BaseDN

包含所有資料的 LDAP 基本層級。舉例來說,在 Apigee 的 LDAP 供應商服務中,所有資料都會列於 dc=apigee,dc=com 下方。

  • ref:用於指定含有 BaseDN 值的流程變數,例如 apigee.baseDN。ref 優先於明確的 BaseDN 值。如果同時指定參照和值,參考資料會優先採用。如果 ref 未在執行階段解析,系統會使用值。

Scope

  • object:僅於 LDAP 的基本層級進行驗證或搜尋。
  • onelevel:驗證或搜尋發生在基礎等級以下的一個層級。
  • subtree (預設):驗證或搜尋在基礎層級且以遞迴方式低於基本層級。

身分驗證

Authentication

您實作驗證行為的父項元素。

UserName

採用下列任一屬性的空白元素:

  • ref:要求中使用者名稱的參照,例如 request.header.username
  • value:使用者名稱本身

如果未使用使用者名稱進行驗證,或是要求中不包含使用者名稱,就不需要加入此元素。

如果要求中包含使用者名稱,但您想使用使用者名稱 (例如電子郵件) 以外的 DN 屬性來驗證使用者,請加入 SearchQuery,取得與密碼相關聯的使用者電子郵件地址。LDAP 政策會使用使用者名稱,向 LDAP 供應商查詢對應的電子郵件地址,接著再用於驗證。

Password

採用下列任一屬性的空白元素:

  • ref:要求中密碼的參照,例如 request.header.password
  • value:加密密碼本身

SearchQuery

如要使用使用者名稱以外的 DN 屬性 (例如電子郵件) 進行驗證,請設定 LDAP 政策,從要求中取得 DN 屬性 (例如使用者名稱),這些資訊將用於在 LDAP 中識別使用者身分、擷取電子郵件,並驗證使用者。

舉例來說,假設 LDAP 定義了用來儲存電子郵件地址的「mail」屬性:

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

搜尋

Search

您實作搜尋行為的父項元素。

SearchQuery

透過要求或回應中的中繼資料來識別使用者,您可以利用這個元素從 LDAP 擷取使用者的其他 DN 屬性。舉例來說,如果要求包含使用者電子郵件地址,且您的 LDAP 定義了儲存使用者電子郵件地址的 mail 屬性,您應該使用以下設定:

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

這項查詢會搜尋 LDAP 尋找與要求中電子郵件地址相符的電子郵件,而政策現在可以透過 Attributes 元素擷取該使用者的其他 DN 屬性。

Attributes

使用一或多個 <Attribute> 元素識別要為使用者擷取的 DN 中繼資料。至少須提供一項屬性。

舉例來說,在 SearchQuery 識別使用者之後,政策現在可以擷取使用者的 DN 屬性,例如地址、電話號碼和使用者職稱,如以下範例所示。

屬性值為 LDAP 中定義的 DN 屬性名稱。

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

使用須知

適用於私有雲的 Apigee Edge 可讓您在 API 呼叫中使用 LDAP 提供者。透過 LDAP 政策,應用程式可以對 LDAP 中儲存的使用者驗證憑證,您也能從 LDAP 擷取辨別名稱 (DN),也就是與使用者相關聯的中繼資料或屬性,例如電子郵件、地址和電話號碼。傳回的 DN 會儲存在變數中,以便 API Proxy 進一步使用。

建立 LDAP 資源

LDAP 政策會使用您在 Apigee Edge 中建立的 LDAP 資源。LDAP 資源會提供與 LDAP 存放區的連線資訊。

如要建立及管理 LDAP 資源,請使用下列 API 和酬載:

API

建立 (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 檔案新增至環境,並確認該檔案位於類別路徑中,
  6. 為 LDAP 供應商建立環境資源。您會在 LDAP 政策的 <LdapResource> 元素中使用環境資源名稱。

使用 Java 適用的 UnboundID LDAP SDK

您可以將 UnboundID LDAP SDK 與 LDAP 政策搭配使用,但您必須先下載 2.3.1 版,並將其新增至每個訊息處理器的類別路徑。

如何將 UnboundID LDAP SDK 與 LDAP 政策搭配使用:

  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. 在每個訊息處理器節點上:
    1. 將 JAR 檔案複製到訊息處理器的 /opt/apigee/edge-gateway/lib/thirdparty 目錄。
    2. 如有需要,請將 JAR 檔案的權限授予 Apigee 使用者,讓訊息處理工具能夠存取該檔案。
    3. Edge 會將 /opt/apigee/edge-gateway/lib/thirdparty 目錄中的所有第三方程式庫新增至類別路徑。

    4. 重新啟動訊息處理器:
      /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

如要擷取搜尋結果中的第三個地址屬性,您可以使用下列指令:

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

如果屬性有多個值 (例如使用者有多個電子郵件地址),您可以從結果中擷取第二個電子郵件地址,如下所示:

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.