מדיניות 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, ואפשר לאחזר שמות ייחודיים (DN) מ-LDAP – המטא-נתונים או המאפיינים המשויכים לכל משתמש, כמו כתובת אימייל, כתובת ומספר טלפון. ה-DN שמוחזר מאוחסן במשתנה לשימוש נוסף על ידי שרת ה-API של שרת ה-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 לסביבה שלכם ומוודאים שהוא נמצא בנתיב המחלקה שלכם.
6. יצירת משאב סביבה לספק ה-LDAP. צריך להשתמש בשם של משאב הסביבה ברכיב <LdapResource> של מדיניות ה-LDAP.

שימוש ב-UnboundID LDAP SDK ל-Java

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

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

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

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

2. מאתרים את גרסה 2.3.1 (SE או Standard Edition) של ה-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 מוסיפה ל-classpath את כל ספריות הצד השלישי בספרייה /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 הן בפורמט עקבי, כמו שמתואר בחומר העזר בנושא קוד שגיאה.

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