Ativar SAML (Beta)

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

Nesta seção, descrevemos como ativar o SAML para o Apigee Edge para que a autenticação dos membros das suas organizações possa ser delegada ao seu próprio serviço de identidade. Para uma visão geral da SAML e do gerenciamento de zonas de identidade no Edge, consulte Visão geral da SAML.

Vídeo:assista a um vídeo curto para saber como acessar as APIs do Apigee Edge antes e depois de ativar o logon único (SSO) usando SAML.

Sobre a função zoneadmin

Você precisa ser um zoneadmin para gerenciar zonas de identidade no Edge. A função zoneadmin oferece procedimentos CRUD completos para gerenciar apenas zonas de identidade.

Para atribuir o papel de administrador da zona à sua conta do Apigee Edge, entre em contato com o suporte do Apigee Edge.

Antes de começar

Antes de começar, obtenha as seguintes informações do seu provedor de identidade SAML de terceiros:

  • Certificado para verificação de assinatura (formato PEM ou PKCSS). Se necessário, converta um certificado x509 para o formato PEM.

  • Informações de configuração (definidas na tabela a seguir)

    Configuração Descrição
    URL de login URL para o qual os usuários são redirecionados para fazer login no provedor de identidade SAML.
    URL de êxito de logout URL para o qual os usuários são redirecionados para sair do provedor de identidade SAML.
    ID da entidade do IdP URL exclusivo para este provedor de identidade. Por exemplo: https://idp.example.com/saml

Além disso, configure seu provedor de identidade SAML terceirizado com as seguintes configurações:

  • Verifique se o atributo NameID está mapeado para o endereço de e-mail do usuário. O endereço de e-mail do usuário serve como identificador exclusivo da conta de desenvolvedor do Edge. O exemplo a seguir usa o Okta, em que o campo Formato do ID do nome define o atributo NameID.

  • (Opcional) Defina a duração da sessão autenticada como 15 dias para corresponder à duração da sessão autenticada da interface do Edge.

Conheça a página "Administração da zona de SSO do Edge"

Gerencie zonas de identidade para o Edge usando a página de administração de zonas do SSO do Edge. A página de administração da zona de SSO do Edge existe fora da sua organização, permitindo que você atribua várias organizações à mesma zona de identidade.

Para acessar a página "Administração da zona de SSO do Edge":

  1. Faça login em https://apigee.com/edge usando uma conta de usuário do Apigee Edge com privilégios de zoneadmin.
  2. Selecione Administrador > SSO na barra de navegação à esquerda.

A página "Administração da zona de SSO do Edge" é exibida (fora da sua organização).

Conforme destacado na figura, a página "Administração da zona de SSO do Edge" permite:

Adicionar uma zona de identidade

Para adicionar uma zona de identidade:

  1. Acesse a página "Administração da zona de SSO do Edge".
  2. Na seção "Zonas de identidade", clique em +.

  3. Insira um nome e uma descrição para a zona de identidade.
    O nome da zona precisa ser exclusivo em todas as organizações de borda.

    Observação: a Apigee se reserva o direito de remover qualquer nome de zona considerado injustificável.

  4. Insira uma string para anexar ao subdomínio, se necessário.
    Por exemplo, se acme for o nome da zona, talvez você queira definir uma zona de produção, acme-prod, e uma zona de teste, acme-test.
    Para criar a zona de produção, insira prod como o sufixo do subdomínio. Nesse caso, o URL usado para acessar a interface do Edge seria: acme-prod.apigee.com, conforme descrito em Acessar sua organização usando a zona de identidade.

    Observação: o sufixo de subdomínio anexado precisa ser exclusivo em todas as suas zonas.

  5. Clique em OK.

  6. Configure o provedor de identidade SAML.

Configurar o provedor de identidade SAML

Para configurar o provedor de identidade SAML, siga estas etapas:

  1. Configure as definições de SAML.
  2. Fazer upload de um novo certificado.
    Se necessário, converta um certificado x509 para o formato PEM.

Configurar as definições de SAML

Para definir as configurações de SAML:

  1. Acesse a página "Administração da zona de SSO do Edge".
  2. Clique na linha da zona de identidade em que você quer configurar o provedor de identidade SAML.
  3. Na seção Configurações de SAML, clique em .

  4. Clique em Copiar ao lado do URL dos metadados do SP.

  5. Configure seu provedor de identidade SAML usando as informações no arquivo de metadados do provedor de serviços (SP).

    Para alguns provedores de identidade SAML, será solicitado apenas o URL de metadados. Para outros, será necessário extrair informações específicas do arquivo de metadados e inseri-las em um formulário.

    No último caso, cole o URL em um navegador para fazer o download do arquivo de metadados SP e extrair as informações necessárias. Por exemplo, o ID da entidade ou o URL de login pode ser extraído dos seguintes elementos no arquivo de metadados do SP:

    Observação: no arquivo de metadados do SP, o URL de login é chamado de URL do AssertionConsumerService (ACS).

    • <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="diyyaumzqchrbui-a5vnmu1sp8qzekbd.apigee-saml-login" entityID="diyyaumzqchrbui-a5vnmu1sp8qzekbd.apigee-saml-login">
    • <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://diyyaumzqchrbui-a5vnmu1sp8qzekbd.portal-login.apigee.com/saml/SSO/alias/diyyaumzqchrbui-a5vnmu1sp8qzekbd.apigee-saml-login" index="0" isDefault="true"/>

    Observação: se exigido pelo provedor de identidade SAML, defina a restrição de público-alvo como zoneID.apigee-saml-login, que pode ser copiada do elemento entityID no arquivo de metadados do SP (mostrado acima).

  6. Configure as definições de SAML para o provedor de identidade SAML.

    Na seção Configurações de SAML, edite os seguintes valores recebidos do arquivo de metadados do seu provedor de identidade SAML:

    Configuração de SAMLDescrição
    URL de loginURL para o qual os usuários são redirecionados para fazer login no provedor de identidade do portal SAML.
    Por exemplo: https://dev-431871.oktapreview.com/app/googledev431871_devportalsaml_1/exkhgdyponHIp97po0h7/sso/saml
    URL de êxito de logoutURL para o qual os usuários são redirecionados para sair do provedor de identidade do portal SAML.
    Observação: se o provedor de identidade SAML não fornecer um URL de saída, deixe este campo em branco. Nesse caso, ele será definido com o mesmo valor usado para o URL de login.
    ID da entidade do IdPURL exclusivo do provedor de identidade SAML.
    Por exemplo: http://www.okta.com/exkhgdyponHIp97po0h7

    Observação:dependendo do provedor de identidade SAML, esse campo pode ter um nome diferente, como Entity ID, SP Entity ID, Audience URI e assim por diante.

    Observação: o SSO da Apigee não é compatível com os dois recursos a seguir:

    • Atualização automática do certificado do IdP usando um URL de metadados do IdP e fazendo o download dos metadados periodicamente para atualizar as mudanças no lado do provedor de serviços do SSO do Apigee.
    • Fazer upload de um arquivo XML completo de metadados do IdP ou usar um URL de metadados do IdP para configuração automática.

  7. Clique em Salvar.

Em seguida, faça upload de um certificado no formato PEM ou PKCSS, conforme descrito na próxima seção.

Enviar um novo certificado

Para fazer upload de um novo certificado:

  1. Faça o download do certificado para verificação de assinatura do seu provedor de identidade SAML.

    Observação: o certificado precisa estar no formato PEM ou PKCSS. Se necessário, converta um certificado x509 para o formato PEM.

  2. Acesse a página "Administração da zona de SSO do Edge".

  3. Clique na linha da zona de identidade para qual você quer fazer upload de um novo certificado.

  4. Na seção Certificado, clique em .

  5. Clique em Procurar e navegue até o certificado no diretório local.

  6. Clique em Abrir para fazer o upload do novo certificado.
    Os campos de informações do certificado são atualizados para refletir o certificado selecionado.

  7. Verifique se o certificado é válido e não expirou.

  8. Clique em Salvar.

Converter um certificado x509 para o formato PEM

Se você fizer o download de um certificado x509, será necessário convertê-lo em formato PEM.

Para converter um certificado x509 para o formato PEM:

  1. Copie o conteúdo de ds:X509Certificate element do arquivo de metadados do provedor de identidade SAML e cole-o no seu editor de texto favorito.
  2. Adicione a seguinte linha na parte superior do arquivo:
    -----BEGIN CERTIFICATE-----
  3. Adicione a seguinte linha na parte inferior do arquivo:
    -----END CERTIFICATE-----
  4. Salve o arquivo usando uma extensão .pem.

Veja a seguir um exemplo de conteúdo do arquivo PEM:

-----BEGIN CERTIFICATE-----
MIICMzCCAZygAwIBAgIJALiPnVsvq8dsMA0GCSqGSIb3DQEBBQUAMFMxCzAJBgNV
BAYTAlVTMQwwCgYDVQQIEwNmb28xDDAKBgNVBAcTA2ZvbzEMMAoGA1UEChMDZm9v
MQwwCgYDVQQLEwNmb28xDDAKBgNVBAMTA2ZvbzAeFw0xMzAzMTkxNTQwMTlaFw0x
ODAzMTgxNTQwMTlaMFMxCzAJBgNVBAYTAlVTMQwwCgYDVQQIEwNmb28xDDAKBgNV
BAcTA2ZvbzEMMAoGA1UEChMDZm9vMQwwCgYDVQQLEwNmb28xDDAKBgNVBAMTA2Zv
bzCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAzdGfxi9CNbMf1UUcvDQh7MYB
OveIHyc0E0KIbhjK5FkCBU4CiZrbfHagaW7ZEcN0tt3EvpbOMxxc/ZQU2WN/s/wP
xph0pSfsfFsTKM4RhTWD2v4fgk+xZiKd1p0+L4hTtpwnEw0uXRVd0ki6muwV5y/P
+5FHUeldq+pgTcgzuK8CAwEAAaMPMA0wCwYDVR0PBAQDAgLkMA0GCSqGSIb3DQEB
BQUAA4GBAJiDAAtY0mQQeuxWdzLRzXmjvdSuL9GoyT3BF/jSnpxz5/58dba8pWen
v3pj4P3w5DoOso0rzkZy2jEsEitlVM2mLSbQpMM+MUVQCQoiG6W9xuCFuxSrwPIS
pAqEAuV4DNoxQKKWmhVv+J0ptMWD25Pnpxeq5sXzghfJnslJlQND
-----END CERTIFICATE-----

Conectar uma organização do Edge a uma zona de identidade

Para conectar uma organização do Edge a uma zona de identidade:

  1. Acesse a página "Administração da zona de SSO do Edge".
  2. Na seção Mapeamento da organização, selecione uma zona de identidade no menu suspenso Zona de identidade associada à organização que você quer atribuir a uma zona.
    Selecione Nenhum (padrão do Apigee) para ativar a autenticação básica na organização.
  3. Clique em Confirmar para confirmar a mudança.

Acessar sua organização usando a zona de identidade

O URL usado para acessar a interface do Edge é definido pelo nome da sua zona de identidade:

https://zonename.apigee.com

Da mesma forma, o URL usado para acessar a interface clássica do Edge é:

https://zonename.enterprise.apigee.com

Por exemplo, a Acme Inc. quer usar a SAML e escolhe "acme" como o nome da zona. Os clientes da Acme Inc. acessam a interface do Edge com o seguinte URL:

https://acme.apigee.com

A zona identifica as organizações do Edge que oferecem suporte ao SAML. Por exemplo, a Acme Inc. tem três organizações: OrgA, OrgB e OrgC. A Acme pode adicionar todas as organizações à zona SAML ou apenas um subconjunto. As demais organizações continuam usando a autenticação básica ou tokens OAuth2 gerados com credenciais de autenticação básica.

É possível definir várias zonas de identidade. Todas as zonas podem ser configuradas para usar o mesmo provedor de identidade.

Por exemplo, a Acme pode querer definir uma zona de produção, "acme-prod", que contenha OrgAProd e OrgBProd, e uma zona de teste, "acme-test", que contenha OrgATest, OrgBTest, OrgADev e OrgBDev.

Em seguida, use os seguintes URLs para acessar as diferentes zonas:

https://acme-prod.apigee.com
https://acme-test.apigee.com

Registrar usuários do Edge com autenticação SAML

Depois de ativar o SAML para uma organização, é necessário registrar os usuários que ainda não estão registrados. Para mais informações, consulte Gerenciar usuários da organização.

Atualizar scripts para transmitir tokens de acesso do OAuth2

Depois de ativar o SAML, a autenticação básica será desativada para a API Edge. Todos os scripts (Maven, shell, apigeetool etc.) que dependem de chamadas da API Edge compatíveis com autenticação básica não vão mais funcionar. É necessário atualizar as chamadas de API e os scripts que usam a autenticação básica para transmitir tokens de acesso OAuth2 no cabeçalho do portador. Consulte Usar SAML com a API Edge.

Excluir uma zona de identidade

Para excluir uma zona de identidade:

  1. Acesse a página "Administração da zona de SSO do Edge".
  2. Posicione o cursor sobre a linha associada à zona de identidade que você quer excluir para exibir o menu de ações.
  3. Clique em .
  4. Clique em Excluir para confirmar a operação de exclusão.

Saia da página de administração da zona de SSO do Edge

Como você gerencia as zonas de identidade do Edge fora da sua organização, é necessário sair da página de administração da zona de SSO do Edge e fazer login na sua organização para acessar outros recursos do Apigee Edge.