Integrations

É possível estabelecer conexão via SAML com um provedor de identidade para que usuários sejam capazes de logar no API Manager utilizando as credenciais desse provedor. É necessário que o provedor escolhido suporte o padrão SAML 2.0.

A configuração da conexão é feita na tela Integrations.

integrations
Tela "Integrations": configuração de conexão com um provedor de identidade
Veja abaixo algumas dicas úteis para configurar a integração com o API Manager no seu provedor.

Configurando uma conexão via SAML2.0

Para configurar uma conexão com um provedor de identidade, preencha os seguintes campos:

  • Name: campo para incluir o nome do seu provedor SAML.

  • Application ID: campo para incluir o identificador único do API Manager dentro do seu provedor SAML. Ele é usualmente referenciado nos provedores de identidade como Application ID ou Service Provider Entity ID. Cheque a documentação do seu provedor para mais informações.

  • Metadata Type: campo para selecionar o tipo de acesso aos metadados (opções: "URL" ou "File Upload"). Para localizar a Metadata URL ou baixar um arquivo SAML válido, cheque a documentação do seu provedor de identidade.

    • Se a opção escolhida for "URL", incluir o endereço no campo Metadata URL.

      integrations config url

    • Se a opção escolhida for "File Upload", clique no botão METADATA UPLOAD e escolha um documento de metadados da sua máquina.
      integrations config upl

Desativando ou editando uma conexão via SAML 2.0

Após ativa, a conexão com o provedor de identidade pode ser atualizada a qualquer momento. Para isso, clique em qualquer campo que deseja editar, faça as devidas modificações e clique em UPDATE CONNECTION.

Para desabilitar uma conexão ativa, clique no botão DISCONNECT. Os usuários do provedor de identidade (independentemente de terem sido cadastrados antes ou após a integração ter sido ativada) não serão deletados do Manager, mas terão o acesso bloqueado até que uma senha seja criada/resetada — o que pode ser feito por meio do link Forgot your password? na tela de login.

integrations active
Conexão ativa com botões para desativar ou atualizar a conexão

Login e controle de usuários

Após ativada uma conexão com um provedor de identidade, a tela de login do Manager será alterada:

login

Ao clicar em SIGN IN, os usuários serão levados à tela de login do provedor de identidade escolhido e deverão informar suas credenciais para acesso. Os usuários que haviam sido cadastrados no Manager antes da conexão estar ativa não conseguirão mais iniciar sessão utilizando o login e senha cadastrados no Manager, apenas as credenciais registradas no provedor de identidade.

Caso seja o primeiro acesso de um usuário, ele será automaticamente incluído como usuário federado na tela Users com a função "API Operations". A função pode ser alterada posteriormente, editando o usuário na tela Users.

"API Operations" é um papel que já vem criado no seu Manager. Caso ele tenha sido ou seja deletado, será recriado automaticamente no momento em que um novo usuário federado for incluído no Manager.

Caso um usuário que já havia sido criado no Manager (pelo processo usual de cadastro de usuários) faça login pelo provedor de identidade, o seu status na tela Users será alterado para "Federated" mas o papel que ele já tinha será mantido (ou seja, um usuário Admin do Manager será transformado em um usuário do tipo federado, mas manterá o papel Admin com todas as permissões específicas do papel). Veja mais sobre os usuários federados aqui.

Dicas para configurar uma aplicação do API Manager em seu provedor de identidade

Para habilitar uma conexão SAML 2.0, é preciso que uma aplicação do API Manager seja cadastrada no seu provedor de identidade. A documentação oficial do seu provedor deve ajudá-lo com as configurações necessárias, mas algumas dicas pontuais são úteis para facilitar o processo:

  1. Configure a URL de callback
    É necessário incluir a URL de callback (Single Sign On URL), que tem como base o endereço do seu API Manager: <MANAGER-URL>/api-manager/api/v3/saml/callback.

  2. Sete o atributo de email
    O provedor deve enviar para o Manager a informação dos emails dos usuários como um atributo SAML. O nome do atributo deve ser http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress e seu tipo deve ser Basic. Pode haver pequenas variações de configuração em cada provedor, então é uma boa ideia checar a documentação oficial do seu.

Exemplo de configuração

A conexão via SAML 2.0 pode ser feita com o provedor de acesso da sua escolha. Existem diversos provedores, um deles é o Okta. Para configurá-lo, siga os passos listados a seguir.

  1. Se já não possuir, crie uma conta no Okta.
    Acesse pelo link https://developer.okta.com/signup/

  2. Crie um app do tipo SAML 2.0.
    Para isso, clique em Applications  Applications e no botão Create App Integration, como mostra a figura abaixo.
    okta step1a

    Em seguida, na tela modal que se abrirá, selecione a opção SAML 2.0 e clique em Next

    localização da opção SAML 2.0

  3. Configure o app, especificando um nome para a sua integração, ícone ou logo (opcional) e opções de visibilidade.
    Em seguida, clique em Next.

  4. Na tela seguinte, preencha os campos:

    • Single sign on URL: URL de callback, que tem como base o endereço do seu API Manager: <MANAGER-URL>/api-manager/api/v3/saml/callback;

    • Audience URI (SP Entity ID): o valor informado neste campo será utilizado no API Manager como "application ID";

    • Default RelayState: campo de preenchimento não obrigatório;

    • Name ID format: selecione EmailAddress.

      Mais abaixo, em Attribute Statements (imagem abaixo), preencha:

    • Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress ;

    • Name format: selecione basic ;

    • Value: preencha com: user.e-mail ;
      okta step4
      Em seguida, clique em NEXT para finalizar o cadastro.

  5. Na tela que aparece ao clicar em NEXT, exporte o metadata clicando em Identity Provider metadata is available if this application supports dynamic configuration (identificado na imagem a seguir).
    okta step5
    A tela que abrir vai mostrar o conteúdo, que pode ser salvo como metadata.xml.
    Anote a URL. Ela será usada para configurar o API Manager.

  6. Vincule o usuário do Okta ao app criado.
    Para isso, clique na aba Assignments e, em seguida, clique em Assig  Assign to People, como ilustra a imagem abaixo.
    okta step6

    Na tela que abrir, clique em Assign, ao lado do seu nome e e-mail, como ilustra a imagem abaixo.

    okta step6b

    Na tela seguinte, clique no botão Save and Go Back.

É necessário que o usuário esteja vinculado ao app criado para que ele consiga fazer o login.

Após ter configurado o Okta, entre no seu API Manager.

Volte ao início desta página para mais detalhes sobre a configuração de uma integração no API Manager.
Em resumo, em IAM_Users  Integrations, preencha os campos:

  • Name: nome que você cadastrou no passo 3;

  • Application ID: nome informado como Audience URI (SP Entity ID) no passo 4;

  • Metadata type: selecione URL;

  • Metadata URL: coloque a URL que você obteve no passo 5;

    Clique em CONNECT

Thanks for your feedback!
EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]