כרגע מוצג התיעוד של 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. המדיניות מעבירה את שם המשתמש והסיסמה מהבקשה אל 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 עם ספק LDAP מותאם אישית (לא סופק על ידי Apigee), עליך לציין את המחלקה המלאה של מחבר ה-LDAP.
זו הכיתה שבה הטמעת את ממשק |
|
יש להזין את שם הסביבה של משאב ה-LDAP. למידע נוסף, ראו יצירת משאב LDAP. |
|
הרמה הבסיסית של LDAP שמתחתיה קיימים כל הנתונים. לדוגמה, אצל ספק ה-LDAP של Apigee, כל הנתונים מופיעים תחת
|
|
|
אימות |
|
|
רכיב הורה להתנהגות האימות שמטמיעים. |
|
רכיב ריק שמוגדר לו אחד מהמאפיינים הבאים:
אם לא מתבצע אימות באמצעות שם משתמש, או אם שם המשתמש לא נכלל בבקשה, אין צורך לכלול את הרכיב הזה. אם הבקשה מכילה שם משתמש, אבל ברצונך לאמת משתמש באמצעות מאפיין DN
שאינו שם משתמש, כמו כתובת אימייל, יש לכלול |
|
רכיב ריק שמוגדר לו אחד מהמאפיינים הבאים:
|
|
אם רוצים לבצע אימות באמצעות מאפיין DN שהוא לא שם משתמש, כמו אימייל, צריך להגדיר את מדיניות ה-LDAP לקבלת מאפיין DN מהבקשה (כמו שם משתמש). המאפיין הזה ישמש לזיהוי המשתמש ב-LDAP, אחזור האימייל ואימות המשתמש. לדוגמה, בהנחה ש-LDAP מגדיר מאפיין 'דואר' לאחסון כתובת אימייל:
|
חיפוש |
|
|
רכיב הורה לפעולת החיפוש שמטמיעים. |
|
זיהוי המשתמש באמצעות מטא-נתונים בבקשה או בתגובה, יאפשר לך להשתמש ברכיב הזה כדי לאחזר מ-LDAP מאפייני DN נוספים עבור המשתמש. לדוגמה, אם
הבקשה מכילה את כתובת האימייל של המשתמש, ו-LDAP מגדיר מאפיין
השאילתה הזו מחפשת ב-LDAP כתובת אימייל שתואמת לכתובת האימייל שצוינה בבקשה, והמדיניות יכולה עכשיו לאחזר מאפייני DN נוספים של המשתמש הזה באמצעות הרכיב Attributes. |
|
צריך להשתמש ברכיב לדוגמה, אחרי שמזהה המשתמש ב- ערכי המאפיינים הם השמות של מאפייני ה-DN שמוגדרים ב-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. לשם כך:
- במחלקה של ספק ה-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 לסביבה שלכם ומוודאים שהוא נמצא בנתיב המחלקה שלכם.
- יצירת משאב סביבה לספק ה-LDAP. צריך להשתמש בשם של משאב
הסביבה ברכיב
<LdapResource>
של מדיניות ה-LDAP.
שימוש ב-UnboundID LDAP SDK ל-Java
אפשר להשתמש ב-UnboundID LDAP SDK עם מדיניות ה-LDAP, אבל תחילה צריך להוריד את גרסה 2.3.1 ולהוסיף אותה לכל אחד מנתיבי המחלקה של מעבד ההודעות.
כדי להשתמש ב-UnboundID LDAP SDK עם מדיניות ה-LDAP:
- פותחים דפדפן ועוברים למאגר הקבצים Sourceforge (מאגר הקבצים של Sourceforge) עבור UnboundID LDAP SDK:
https://sourceforge.net/projects/ldap-sdk/files/
- מאתרים את גרסה 2.3.1 (SE או Standard Edition) של ה-SDK ומורידים את קובץ ה-ZIP של הגרסה הזו. לדוגמה, צריך להוריד את "unboundid-ldapsdk-2.3.1-se.zip".
- מחלצים את קובץ ה-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
, אם כי אפשרות זו אופציונלית. - בכל צומת של מעבד ההודעות:
- מעתיקים את קובץ ה-JAR לספרייה
/opt/apigee/edge-gateway/lib/thirdparty
של מעבד ההודעות. - אם יש צורך, מעניקים ל-Apigee הרשאת משתמש בקובץ ה-JAR כדי שמעבד ההודעות יוכל לגשת אליו.
- מפעילים מחדש את מעבד ההודעות:
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
Edge מוסיפה ל-classpath את כל ספריות הצד השלישי בספרייה
/opt/apigee/edge-gateway/lib/thirdparty
. - מעתיקים את קובץ ה-JAR לספרייה
משתני זרימה
בהמשך מופיעים המשתנים של מדיניות LDAP שמאוכלסים על ידי SearchQuery
.
משתנה |
התיאור |
---|---|
ldap.policyName.execution.success |
אחרי שהמדיניות החלה, משתנה הזרימה הזה מכיל את הערך 'true' או 'false', בהתאם לתוצאה. |
ldap.policyName.search.result[index]. attribute.attrName[index]=value |
הפורמט הגמיש של המשתנה הזה, האינדקס בפרט: מביא בחשבון כמה מאפיינים וגם מאפיינים עם ערכים מרובים. Index הוא מספר שמתחיל ב-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. |