Você está vendo a documentação do Apigee Edge.
Acesse a
documentação da Apigee X. informações

O que
A política de LDAP oferece:
- Autenticação: as credenciais do usuário fornecidas na solicitação são validadas em relação às credenciais no provedor LDAP. A política de LDAP oferece muita flexibilidade na autenticação, permitindo que você use qualquer valor de DN com a senha, mesmo que o valor de DN que você quer não esteja na solicitação. Por exemplo, digamos que você precise usar e-mail / senha para
autenticação. Estas são as opções possíveis:
- Se o e-mail estiver na solicitação, basta usá-lo com a senha para a autenticação LDAP.
- Se o e-mail não estiver na solicitação, mas outro atributo do DN estiver (como número de telefone), você vai poder usar esse número para receber o e-mail correspondente do LDAP e usar e-mail/senha para a autenticação.
- Pesquisa de nome distinto (DN): além da autenticação, também é possível usar a política de LDAP para identificar um atributo de usuário na solicitação, por exemplo, e-mail, e executar uma consulta que recupera outros atributos de DN do LDAP para esse usuário. O DN recuperado é armazenado em uma variável.
Use a política de LDAP quando o acesso a recursos protegidos precisar ser limitado a usuários no provedor de LDAP, como usuários administradores, usuários da organização e desenvolvedores, especialmente quando o acesso ao token OAuth for desnecessário ou muito pesado. A política também foi projetada para recuperar metadados de nomes de domínio para uso em fluxos de proxy de API.
Por exemplo, é possível fazer com que uma chamada de API seja executada somente quando um usuário for autenticado no LDAP e, opcionalmente, recuperar atributos DN (nome de domínio) para o usuário depois que a autenticação for bem-sucedida.
Para mais informações, consulte:
- Como gerenciar a política de senha LDAP padrão para o gerenciamento da API
- "Informações importantes sobre sua política de senha" na Comunidade Apigee
Exemplos
Autenticação com nome de usuário/senha
<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>
Este exemplo fornece autenticação em um provedor LDAP. A política passa o nome de usuário e a senha da solicitação ao LDAP para autenticação.
Autenticação por atributo de 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>
Essa política recebe o DN do usuário com o e-mail no cabeçalho da solicitação e o autentica no LDAP com a senha fornecida no cabeçalho da solicitação.
Pesquisando 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>
Esta política faz referência a um provedor LDAP personalizado. Ele usa o endereço de e-mail no cabeçalho da solicitação para identificar o usuário e, em seguida, recupera o endereço, o telefone e o cargo do usuário no LDAP. Os atributos DN recuperados são armazenados em uma variável. Consulte "Variáveis específicas da política".
Para pesquisar LDAP e recuperar atributos DN, a solicitação precisa incluir credenciais de administrador.
Referência de elemento
Veja a seguir descrições dos elementos e atributos da política LDAP.
Elemento |
Descrição |
---|---|
|
Elemento pai com um atributo de nome para você inserir o nome da política. |
|
Ao usar a política de LDAP com um provedor de LDAP personalizado (não fornecido pela Apigee), especifique a classe do conector de LDAP totalmente qualificada.
Essa é a classe em que você implementou a interface |
|
Digite o nome do ambiente do recurso LDAP. Consulte Criar um recurso LDAP para mais informações. |
|
O nível básico do LDAP no qual estão todos os seus dados. Por exemplo, no
provedor LDAP da Apigee, todos os dados estão em
|
|
|
Authentication |
|
|
Elemento pai para o comportamento de autenticação implementado. |
|
Elemento vazio que assume um dos seguintes atributos:
Se você não estiver autenticando com o nome de usuário ou se o nome de usuário não estiver incluído na solicitação, não será necessário incluir esse elemento. Se o nome de usuário estiver na solicitação, mas você quiser autenticar um usuário com um atributo de DN
diferente de nome de usuário, como e-mail, inclua um |
|
Elemento vazio que assume um dos seguintes atributos:
|
|
Se você quiser autenticar usando um atributo de DN diferente de nome de usuário, como e-mail, configure a política de LDAP para receber um atributo de DN da solicitação (como nome de usuário), que é usado para identificar o usuário no LDAP, recuperar o e-mail e autenticar o usuário. Por exemplo, suponha que o LDAP defina um atributo "mail" para armazenar endereços de e-mail:
|
Pesquisar |
|
|
Elemento pai para o comportamento de pesquisa implementado. |
|
Ao identificar o usuário com metadados na solicitação ou resposta, é possível usar esse
elemento para recuperar atributos DN adicionais para o usuário do LDAP. Por exemplo, se a solicitação contiver o e-mail do usuário e o LDAP definir um atributo
Essa consulta pesquisa no LDAP um e-mail que corresponda ao e-mail na solicitação, e a política agora pode recuperar outros atributos DN para esse usuário com o elemento Attributes. |
|
Use um ou mais elementos Por exemplo, depois que Os valores do atributo são os nomes dos atributos do DN definidos no seu LDAP. <Attributes> <Attribute>address</Attribute> <Attribute>phone</Attribute> <Attribute>title</Attribute> </Attributes> |
Observações sobre uso
O Apigee Edge para nuvem privada permite usar um provedor LDAP nas chamadas de API. Com a política de LDAP, os aplicativos podem autenticar credenciais em relação a usuários armazenados no LDAP e você pode recuperar nomes distintos (DNs, na sigla em inglês) do LDAP, ou seja, os metadados ou atributos associados a cada usuário, como e-mail, endereço e número de telefone. O DN retornado é armazenado em uma variável para uso futuro pelo proxy de API.
Criar um recurso LDAP
A política LDAP usa um recurso LDAP que você cria na Apigee Edge. Um recurso LDAP fornece as informações de conexão para o repositório LDAP.
Para criar e gerenciar recursos LDAP, use a API e o payload a seguir:
API
Criar (POST
) um recurso LDAP ou listar (GET
) todos os recursos LDAP:
/v1/organizations/org_name/environments/environment/ldapresources
Acessar detalhes de (GET
), atualizar (POST
) e excluir (DELETE
) um recurso LDAP:
/v1/organizations/org_name/environments/environment/ldapresources/ldap_resource_name
Payload
Veja a seguir um exemplo de payload XML com comentários de uso.
<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>
Exemplo de curl: criar um recurso LDAP
O exemplo a seguir cria um recurso LDAP chamado 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>'
Códigos de resposta
Veja a seguir os códigos de resposta HTML que a política retorna para sucesso ou falha:
- Sucesso: 200
- Falha: 401.
Como usar um provedor LDAP personalizado no Edge para nuvem privada
Como usar um provedor LDAP personalizado
O Apigee Edge para nuvem privada vem com um provedor LDAP que já está configurado para interagir com a política de LDAP. No entanto, se você estiver usando um provedor LDAP personalizado, será necessário ativá-lo para que ele seja compatível com a política de LDAP. Para isso:
- Implemente a interface
ExternalLdapConProvider
na classe do provedor LDAP.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(); }
- No
<LdapConnectorClass>
da configuração da política (próximas seções), adicione o nome de classe totalmente qualificado do seu provedor LDAP personalizado. - Faça o download deste arquivo: custom-ldap.jar_.zip. Talvez seja necessário clicar com o botão direito e selecionar Salvar como.
- Descompacte.
- Adicione o arquivo custom-ldap.jar ao seu ambiente e verifique se ele está no seu caminho de classe.
- Crie um recurso de ambiente para seu provedor LDAP. Você usará o nome do recurso do ambiente no elemento
<LdapResource>
da política LDAP.
Como usar o SDK LDAP UnboundID para Java
Você pode usar o SDK LDAP UnboundID com a política LDAP, mas primeiro precisa fazer o download da versão 2.3.1 e adicioná-la a cada um dos caminhos de classe do processador de mensagens.
Para usar o SDK LDAP UnboundID com a política LDAP:
- Abra um navegador e acesse o repositório de arquivos do Sourceforge para o SDK LDAP UnboundID:
https://sourceforge.net/projects/ldap-sdk/files/
- Encontre a versão 2.3.1 (SE ou Standard Edition) do SDK e faça o download do arquivo ZIP dela. Por exemplo, faça o download de "unboundid-ldapsdk-2.3.1-se.zip".
- Extraia o arquivo JAR do arquivo ZIP do SDK, conforme o exemplo a seguir:
unzip -j -d ~/tmp ~/Downloads/unboundid-ldapsdk-2.3.1-se.zip unboundid-ldapsdk-2.3.1-se/unboundid-ldapsdk-se.jar
Esse comando extrai apenas o arquivo JAR para o diretório ~/tmp. Ele descarta a estrutura de diretórios com
-j
, embora isso seja opcional. - Em cada nó do processador de mensagens:
- Copie o arquivo JAR para o diretório
/opt/apigee/edge-gateway/lib/thirdparty
do processador de mensagens. - Se necessário, conceda permissão ao usuário da Apigee no arquivo JAR para que o processador de mensagens possa acessá-lo.
- Reinicie o processador de mensagens:
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
O Edge adiciona todas as bibliotecas de terceiros no diretório
/opt/apigee/edge-gateway/lib/thirdparty
ao caminho de classe. - Copie o arquivo JAR para o diretório
Variáveis de fluxo
Veja a seguir as variáveis de política LDAP preenchidas por um SearchQuery
.
Variável |
Descrição |
---|---|
ldap.policyName.execution.success |
Depois que a política for executada, essa variável de fluxo terá um valor "true" ou "false", dependendo do resultado. |
ldap.policyName.search.result[index]. attribute.attrName[index]=value |
O formato flexível dessa variável, o índice em específico: considera vários atributos e atributos com diversos valores. O índice é um número que começa em 1. Se nenhum número de índice for fornecido, o padrão vai ser 1. Se a política retornar endereço, telefone e e-mail, é possível recuperar o primeiro atributo e valor usando estas variáveis: ldap.policyName.search.result.attribute.address ldap.policyName.search.result.attribute.phone ldap.policyName.search.result.attribute.email Para recuperar o terceiro atributo de endereço nos resultados da pesquisa, use: ldap.policyName.search.result[3].attribute.address Se um atributo tivesse vários valores (por exemplo, se um usuário tivesse vários endereços de e-mail), você recuperaria o segundo endereço de e-mail dos resultados da seguinte forma: ldap.policyName.search.result.attribute.mail[2] |
Códigos de erro
Os erros retornados das políticas do Edge seguem um formato consistente, conforme descrito na Referência do código de erro.
Esta política usa os seguintes códigos de erro:
Código do erro | A mensagem |
---|---|
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. |