Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Cosa
Il criterio LDAP fornisce:
- Autenticazione: le credenziali utente fornite nella richiesta vengono convalidate in base alle credenziali del provider LDAP. Il criterio LDAP offre molta flessibilità nell'autenticazione, consentendo di utilizzare qualsiasi valore DN insieme alla password, anche se il valore DN desiderato non è incluso nella richiesta. Ad esempio, supponiamo che tu debba utilizzare email / password per l'autenticazione. Ecco le opzioni possibili:
- Se l'indirizzo email è incluso nella richiesta, puoi semplicemente utilizzarlo con la password per l'autenticazione LDAP.
- Se l'indirizzo email non è presente nella richiesta, ma un altro attributo DN è (ad esempio il numero di telefono), puoi utilizzare il numero di telefono per ricevere l'email corrispondente da LDAP e quindi utilizzare l'indirizzo email/password per l'autenticazione.
- Ricerca del nome distinto (DN): oltre all'autenticazione, puoi anche utilizzare il criterio LDAP per identificare un attributo utente nella richiesta, ad esempio email, ed eseguire una query che recupera altri attributi DN da LDAP per l'utente in questione. Il DN recuperato viene archiviato in una variabile.
Utilizza il criterio LDAP quando l'accesso alle risorse protette deve essere limitato agli utenti del tuo provider LDAP, ad esempio utenti amministratore, utenti dell'organizzazione e sviluppatori, soprattutto quando l'accesso al token OAuth non è necessario o è troppo pesante. Il criterio è progettato anche per recuperare i metadati dei nomi di dominio da utilizzare nei flussi del proxy API.
Ad esempio, puoi fare in modo che una chiamata API venga eseguita solo quando un utente viene autenticato con LDAP e, successivamente, recupera gli attributi DN (Domain Name) per l'utente dopo l'autenticazione.
Per ulteriori informazioni, consulta:
- Gestire i criteri predefiniti per le password LDAP per la gestione delle API
- "Informazioni importanti sui criteri relativi alle password" nella community di Apigee
Samples
Autenticazione nome utente/password
<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>
Questo esempio fornisce l'autenticazione rispetto a un provider LDAP. Il criterio trasmette il nome utente e la password dalla richiesta a LDAP per l'autenticazione.
Autenticazione attributo 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>
Questo criterio ottiene il DN dell'utente con l'email nell'intestazione della richiesta, quindi autentica l'utente in base a LDAP con la password fornita nell'intestazione della richiesta.
Ricerca in 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>
Questo criterio fa riferimento a un provider LDAP personalizzato. Utilizza l'indirizzo email nell'intestazione della richiesta per identificare l'utente, quindi recupera l'indirizzo, il telefono e il titolo dell'utente da LDAP. Gli attributi DN recuperati sono memorizzati in una variabile. Vedi "Variabili specifiche del criterio".
Per eseguire ricerche in LDAP e recuperare gli attributi DN, la richiesta deve includere le credenziali dell'amministratore.
Riferimento elemento
Di seguito sono riportate le descrizioni degli elementi e degli attributi dei criteri LDAP.
Elemento |
Descrizione |
---|---|
|
Elemento principale con un attributo name che ti consente di inserire il nome del criterio. |
|
Quando utilizzi il criterio LDAP con un provider LDAP personalizzato (non fornito da Apigee), specifica la classe del connettore LDAP completa.
Questa è la classe in cui hai implementato l'interfaccia |
|
Inserisci il nome dell'ambiente della risorsa LDAP. Per ulteriori informazioni, consulta Creare una risorsa LDAP. |
|
Il livello di base di LDAP con cui esistono tutti i dati. Ad esempio, nel
provider LDAP di Apigee, tutti i dati sono inferiori a
|
|
|
Autenticazione |
|
|
Elemento principale per il comportamento di autenticazione implementato. |
|
Elemento vuoto che accetta uno dei seguenti attributi:
Se non esegui l'autenticazione con il nome utente o se il nome utente non è incluso nella richiesta, non è necessario includere questo elemento. Se il nome utente è incluso nella richiesta, ma vuoi autenticare un utente con un attributo DN diverso dal nome utente, come l'email, includi un |
|
Elemento vuoto che accetta uno dei seguenti attributi:
|
|
Se vuoi eseguire l'autenticazione utilizzando un attributo DN diverso dal nome utente, ad esempio l'email, configura il criterio LDAP in modo da ottenere un attributo DN dalla richiesta (ad esempio, il nome utente), che viene utilizzato per identificare l'utente in LDAP, recuperare l'email e autenticare l'utente. Ad esempio, supponendo che LDAP definisca un attributo "mail" per archiviare l'indirizzo email:
|
Cerca |
|
|
Elemento principale del comportamento di ricerca implementato. |
|
Identificando l'utente con i metadati nella richiesta o nella risposta, puoi utilizzare questo elemento per recuperare attributi DN aggiuntivi per l'utente da LDAP. Ad esempio, se la richiesta contiene l'indirizzo email dell'utente e LDAP definisce un attributo
Questa query cerca in LDAP un'email che corrisponde all'indirizzo email della richiesta e il criterio può ora recuperare attributi DN aggiuntivi per quell'utente con l'elemento Attributes. |
|
Utilizza uno o più elementi Ad esempio, dopo che I valori degli attributi sono i nomi degli attributi DN definiti nel tuo LDAP. <Attributes> <Attribute>address</Attribute> <Attribute>phone</Attribute> <Attribute>title</Attribute> </Attributes> |
Note sull'utilizzo
Apigee Edge per il cloud privato ti consente di utilizzare un provider LDAP nelle chiamate API. Con i criteri LDAP, le applicazioni possono autenticare le credenziali rispetto agli utenti archiviati in LDAP e tu puoi recuperare i nomi distinti (DN) da LDAP, ovvero i metadati o gli attributi associati a ciascun utente, come email, indirizzo e numero di telefono. Il DN restituito viene archiviato in una variabile per ulteriore utilizzo da parte del proxy API.
crea una risorsa LDAP
Il criterio LDAP utilizza una risorsa LDAP creata in Apigee Edge. Una risorsa LDAP fornisce le informazioni sulla connessione al repository LDAP.
Per creare e gestire le risorse LDAP, utilizza l'API e il payload seguenti:
API
Crea (POST
) una risorsa LDAP o un elenco (GET
) di tutte le risorse LDAP:
/v1/organizations/org_name/environments/environment/ldapresources
Ottieni i dettagli di (GET
), aggiorna (POST
) ed elimina (DELETE
) una risorsa LDAP:
/v1/organizations/org_name/environments/environment/ldapresources/ldap_resource_name
Payload
Di seguito è riportato un payload XML di esempio con commenti sull'utilizzo.
<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>
Esempio di curl: creare una risorsa LDAP
L'esempio seguente crea una risorsa LDAP denominata 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>'
Codici di risposta
Di seguito sono riportati i codici di risposta HTML restituiti dal criterio in caso di esito positivo o negativo:
- Operazione riuscita: 200
- Errore: 401
Utilizzo di un provider LDAP personalizzato in Edge per il cloud privato
Utilizzo di un provider LDAP personalizzato
Apigee Edge per il cloud privato viene fornito con un provider LDAP già configurato per l'interazione con il criterio LDAP. Tuttavia, se utilizzi un provider LDAP personalizzato, devi abilitare il provider in modo che supporti il criterio LDAP. Per farlo:
- Nella classe del provider LDAP, implementa l'interfaccia
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(); }
- Nella sezione
<LdapConnectorClass>
della configurazione dei criteri (sezioni successive), aggiungi il nome completo della classe del provider LDAP personalizzato. - Scarica questo file: custom-ldap.jar_.zip. Potrebbe essere necessario fare clic con il tasto destro del mouse e selezionare Salva con nome.
- Decomprimilo.
- Aggiungi il file custom-ldap.jar al tuo ambiente e assicurati che sia incluso nel tuo classpath.
- Crea una risorsa di ambiente per il tuo provider LDAP. Utilizzerai il nome della risorsa di ambiente nell'elemento
<LdapResource>
del criterio LDAP.
Utilizzo dell'SDK LDAP UnboundID per Java
Puoi utilizzare l'SDK LDAP UnboundID con il criterio LDAP, ma devi prima scaricare la versione 2.3.1 e aggiungerla a ciascun percorso di classe del processore di messaggi.
Per utilizzare l'SDK LDAP UnboundID con il criterio LDAP:
- Apri un browser e vai al repository di file Sourceforge per l'SDK LDAP UnboundID:
https://sourceforge.net/projects/ldap-sdk/files/
- Trova la versione 2.3.1 (SE o Standard Edition) dell'SDK e scarica il file ZIP per quella versione. Ad esempio, scarica "unboundid-ldapsdk-2.3.1-se.zip".
- Estrai il file JAR dal file ZIP dell'SDK, come illustrato nell'esempio seguente:
unzip -j -d ~/tmp ~/Downloads/unboundid-ldapsdk-2.3.1-se.zip unboundid-ldapsdk-2.3.1-se/unboundid-ldapsdk-se.jar
Questo comando estrae solo il file JAR nella directory ~/tmp. Elimina la struttura della directory con
-j
, anche se è facoltativo. - Su ciascun nodo del processore di messaggi:
- Copia il file JAR nella directory
/opt/apigee/edge-gateway/lib/thirdparty
del processore di messaggi. - Se necessario, concedi l'autorizzazione utente Apigee per il file JAR in modo che il processore dei messaggi possa accedervi.
- Riavvia il processore di messaggi:
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
Edge aggiunge tutte le librerie di terze parti nella directory
/opt/apigee/edge-gateway/lib/thirdparty
al classpath. - Copia il file JAR nella directory
Variabili di flusso
Di seguito sono riportate le variabili dei criteri LDAP compilate da SearchQuery
.
Variabile |
Descrizione |
---|---|
ldap.policyName.execution.success |
Dopo l'esecuzione del criterio, questa variabile di flusso contiene un valore "true" o "false", a seconda del risultato. |
ldap.policyName.search.result[index]. attribute.attrName[index]=value |
Il formato flessibile di questa variabile, in particolare l'indice: prende in considerazione più attributi e quelli con più valori. L'indice è un numero che inizia da 1. Se non viene fornito alcun numero di indice, il numero di indice predefinito è 1. Se la norma restituisce l'indirizzo, il numero di telefono e l'email, puoi recuperare il primo attributo e il primo valore utilizzando queste variabili: ldap.policyName.search.result.attribute.address ldap.policyName.search.result.attribute.phone ldap.policyName.search.result.attribute.email Per recuperare il terzo attributo dell'indirizzo nei risultati di ricerca, devi utilizzare questo: ldap.policyName.search.result[3].attribute.address Se un attributo ha più valori (ad esempio, se un utente ha più indirizzi email), devi recuperare il secondo indirizzo email dai risultati in questo modo: ldap.policyName.search.result.attribute.mail[2] |
Codici di errore
Gli errori restituiti dai criteri perimetrali seguono un formato coerente, come descritto in Riferimento ai codici di errore.
Questo criterio utilizza i seguenti codici di errore:
Codice di errore | Messaggio |
---|---|
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. |