מדיניות LDAP

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

מה

מדיניות ה-LDAP כוללת את הפרטים הבאים:

• אימות: פרטי הכניסה של המשתמש שצוינו בבקשה מאומתים מול פרטי כניסה בספק ה-LDAP. מדיניות LDAP מספקת גמישות רבה אימות, כך שתוכל להשתמש בכל ערך DN יחד עם הסיסמה, גם אם ערך ה-DN שאתם רוצים לא נמצאים בבקשה. לדוגמה, נניח שצריך להשתמש באימייל או בסיסמה אימות. אלה האפשרויות האפשריות:
  • אם האימייל נשלח בבקשה, אפשר פשוט להשתמש בו עם הסיסמה עבור LDAP אימות.
  • אם כתובת האימייל לא מופיעה בבקשה, אבל כן מאפיין DN אחר (כמו מספר טלפון) ניתן להשתמש במספר הטלפון כדי לקבל את כתובת האימייל המתאימה מ-LDAP, ואז להשתמש באימייל / לאימות.
• חיפוש שמות ייחודיים (DN): בנוסף לאימות, אפשר להשתמש גם במדיניות LDAP כדי לזהות מאפיין משתמש בבקשה, כמו אימייל, להריץ שאילתה שמאחזרת מאפייני DN אחרים מ-LDAP עבור המשתמש הזה. ה-DN שאוחזר הוא מאוחסן במשתנה.

יש להשתמש במדיניות LDAP כאשר הגישה למשאבים מוגנים צריכה להיות מוגבלת למשתמשים ב-LDAP ספק – למשל משתמשים עם הרשאת אדמין, משתמשים בארגון ומפתחים – במיוחד כאשר הגישה לאסימון OAuth היא מיותרת או כבדה מדי. המדיניות נועדה גם אחזור מטא-נתונים של שם דומיין לשימוש בתהליכי שרת proxy ל-API.

לדוגמה, אפשר להפעיל קריאה ל-API רק לאחר שמשתמש אומת בהצלחה כנגד LDAP; ואז באופן אופציונלי לאחזר מאפייני DN (שם דומיין) עבור המשתמש האימות מצליח.

מידע נוסף זמין במאמרים הבאים:

• ניהול מדיניות ברירת המחדל לסיסמאות של LDAP לניהול API
• 'מידע חשוב על המדיניות בנושא סיסמאות' ב קהילת Apigee

דוגמאות

<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 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>

<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.

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

הערות שימוש

באמצעות Apigee Edge לענן פרטי אפשר להשתמש בספק LDAP בקריאות API. עם LDAP למדיניות, אפליקציות יכולות לאמת פרטי כניסה מול משתמשים שמאוחסנים ב-LDAP, וניתן גם אחזור שמות מובחנים (DNs) מ-LDAP – המטא-נתונים או המאפיינים שמשויכים כל משתמש, למשל אימייל, כתובת ומספר טלפון. ה-DN המוחזר נשמר במשתנה של שימוש נוסף על ידי ה-proxy של ה-API.

יצירת משאב LDAP

מדיניות ה-LDAP משתמשת במשאב LDAP שיוצרים ב-Apigee Edge. משאב LDAP מספק את פרטי החיבור למאגר ה-LDAP.

כדי ליצור ולנהל משאבי LDAP, צריך להשתמש ב-API ובמטען הייעודי (payload) הבאים:

API

יצירת (POST) משאב או רשימה של LDAP (GET) כל משאבי ה-LDAP:

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

קבלת פרטים על (GET), עדכון (POST) ומחיקה (DELETE) של משאב LDAP:

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

מטען ייעודי (payload)

בהמשך מוצגת דוגמה למטען ייעודי (payload) של 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

בדוגמה הבאה נוצר משאב LDAP בשם ldap1.

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

שימוש בספק LDAP בהתאמה אישית ב-Edge לענן פרטי

באמצעות התאמה אישית ספק LDAP

Apigee Edge לענן פרטי מגיע עם ספק 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 שלך. ייעשה שימוש במשאב הסביבה השם ברכיב <LdapResource> של מדיניות ה-LDAP.

באמצעות UnboundID LDAP SDK ל-Java

אפשר להשתמש ב-UnboundID LDAP SDK עם מדיניות ה-LDAP, אבל קודם צריך להוריד את הגרסה 2.3.1 ולהוסיף אותו לכל אחד מנתיבי הכיתה של מעבד ההודעות.

כדי להשתמש ב-UnboundID LDAP SDK עם מדיניות ה-LDAP:

1. פותחים דפדפן ועוברים למאגר הקבצים Sourceforge של UnboundID LDAP SDK:

   https://sourceforge.net/projects/ldap-sdk/files/

2. מאתרים את גרסה 2.3.1 (SE או המהדורה הסטנדרטית) של ה-SDK ומורידים את קובץ ה-ZIP לגרסה הזו. לדוגמה, מורידים את "unboundid-ldapsdk-2.3.1-se.zip".
3. מחלצים את קובץ ה-JAR מקובץ ה-ZIP של ה-SDK, כמו בדוגמה הבאה:

   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. אם צריך, צריך לתת הרשאת משתמש של Apigee בקובץ ה-JAR כדי שמעבד ההודעות יוכל לגשת אליו.

   Edge מוסיף את כל הספריות של צד שלישי הספרייה /opt/apigee/edge-gateway/lib/thirdparty לנתיב הכיתה.

   3. מפעילים מחדש את מעבד ההודעות:

      /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

משתני זרימה

בהמשך מופיעים המשתנים של מדיניות LDAP שמאוכלסים על ידי SearchQuery.

ldap.policyName.execution.success

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

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 הן בפורמט עקבי כפי שמתואר בחומר העזר בנושא קוד שגיאה.

המדיניות הזו משתמשת בקודי השגיאה הבאים: