Mapeamento de grupos SAML do Apidog com Microsoft Entra ID
O mapeamento de grupos SAML atribui acesso às equipes do Apidog com base nos grupos incluídos na declaração SAML do usuário. Assim, o provedor de identidade continua sendo a fonte de verdade, reduzindo o trabalho manual de associação à equipe.
Este tutorial mostra como configurar o Microsoft Entra ID, adicionar uma declaração groups, mapear um grupo Entra para uma equipe Apidog e verificar as permissões iniciais do projeto no login.
Antes de começar
Você precisa de:
- uma organização Apidog Enterprise com SSO SAML configurado;
- acesso de Proprietário ou Administrador da Organização no Apidog;
- acesso de administrador ao aplicativo empresarial Microsoft Entra usado pelo Apidog;
- pelo menos um grupo Entra e um usuário de teste atribuído a esse grupo.
Se o SAML ainda não estiver configurado, siga primeiro Configurando o Microsoft Entra ID.
O mapeamento de grupos SAML controla o acesso às equipes e aos projetos do Apidog. Ele não concede acesso a APIs de produção nem substitui a autorização em tempo de execução.
Como o acesso inicial ao projeto é atribuído
Quando um grupo corresponde ao mapeamento, o Apidog adiciona o usuário à equipe configurada e deriva o acesso inicial ao projeto a partir da função de equipe selecionada.
| Função de equipe mapeada | Função de projeto inicial |
|---|---|
| Administrador de Equipe | Mantenedor de Projeto |
| Membro da Equipe | Projeto Somente Leitura |
| Convidado da Equipe | Projeto Somente Leitura |
O Apidog cria associações de projeto ausentes ou atualiza associações que ainda não têm uma função. Uma função de projeto atribuída manualmente não é sobrescrita em logins SAML posteriores.
Passo 1: adicionar a declaração groups no Microsoft Entra ID
- Entre no centro de administração do Microsoft Entra.
- Acesse Aplicativos empresariais e abra o aplicativo usado para o SSO do Apidog.
- Selecione Logon único e abra Atributos & Declarações.
- Selecione Adicionar uma declaração de grupo.
- Escolha Todos os grupos.
- Ative Personalizar o nome da declaração de grupo e informe
groupscomo nome. - Salve a declaração.
Configure a declaração de grupo para que o Apidog receba os IDs de Objeto do grupo Entra no atributo groups.
O Apidog usa os IDs de Objeto presentes nessa declaração. Ele não recupera outras informações sobre os grupos do Microsoft Entra ID.
Passo 2: copiar o nome e o ID de Objeto do grupo Entra
- No Microsoft Entra ID, abra Grupos.
- Selecione o grupo que deve receber acesso no Apidog.
- Copie o Nome e o ID de Objeto.
Use o ID de Objeto mostrado na página do grupo Entra. Não use um ID de aplicativo, ID de locatário ou nome de exibição no lugar dele.
Mantenha essa página aberta durante a configuração do mapeamento no Apidog.
Passo 3: mapear o grupo para uma equipe Apidog
- Abra a organização no Apidog.
- Acesse as configurações de Grupo SAML da organização.
- Adicione um mapeamento de grupo.
- Informe o nome do grupo Entra e cole o ID de Objeto.
- Selecione as equipes Apidog às quais o grupo deve ter acesso.
- Escolha a função de equipe necessária para cada equipe.
- Salve o mapeamento.
Mapeie o ID de Objeto do grupo Entra para as equipes e funções de equipe necessárias no Apidog.
O mapeamento de grupo SAML não tem um seletor de função de projeto separado. A função inicial do projeto é determinada pela função de equipe mostrada na tabela anterior. Quando necessário, ajuste posteriormente a função do usuário nas configurações de membro do projeto.
Passo 4: testar o mapeamento
Use uma conta de teste, não uma conta de administrador:
- Confirme que o usuário de teste pertence ao grupo Entra mapeado.
- Faça logout do Apidog.
- Faça login pelo ponto de entrada SSO da organização.
- Abra a equipe mapeada e confirme que ela está disponível.
- Verifique a função de equipe do usuário.
- Abra os projetos da equipe e confirme a função inicial do projeto.
Se o usuário já tiver uma função de projeto atribuída manualmente, confirme que ela permanece inalterada após um novo login SSO.
Verificar a remoção de associação
Teste também a remoção de grupo antes da implementação:
- Remova o usuário de teste do grupo Entra mapeado.
- Aguarde a propagação da alteração no provedor de identidade.
- Faça o usuário entrar novamente pelo SSO.
- Verifique a associação à equipe correspondente e os vínculos com projetos.
Quando o usuário deixa de pertencer a um grupo mapeado, o Apidog pode removê-lo da equipe correspondente durante a sincronização SAML. Se a associação à equipe for removida, as associações aos projetos dessa equipe também serão removidas.
Não use uma conta de produção no primeiro teste de remoção. Registre o resultado observado para sua configuração de identidade e para o procedimento de desligamento.
Solução de problemas
| Problema | O que verificar |
|---|---|
| O usuário faz login, mas não é adicionado à equipe | Confirme que a declaração se chama exatamente groups, que a asserção contém o ID de Objeto esperado e que o ID no Apidog não tem espaços extras. |
| A asserção não contém valores de grupo | Confirme que o usuário pertence ao grupo e que o aplicativo empresarial Entra envia declarações de grupo. Para usuários com muitas associações, consulte as orientações da Microsoft sobre excesso de declarações de grupo. |
| O usuário recebe a função de projeto errada | Verifique a função de equipe mapeada. Funções de projeto já atribuídas não são sobrescritas por sincronizações SAML posteriores. |
| Uma alteração de grupo não é refletida | Confirme que a alteração foi propagada para o Entra e inicie um novo login SSO para que o Apidog sincronize a asserção atual. |
| O usuário permanece na organização | O mapeamento de grupo SAML gerencia o acesso às equipes mapeadas. A associação à organização também pode ser gerenciada por convites, SSO ou SCIM. |
Limitações importantes
- O Apidog não cria nem exclui grupos do provedor de identidade via SCIM.
- O mapeamento de grupo SAML não oferece uma função separada para cada projeto.
- Funções de projeto existentes não são redefinidas em logins SSO posteriores.
- Se vários mapeamentos puderem ser aplicados ao mesmo usuário e à mesma equipe, teste o resultado antes da implementação em vez de presumir uma regra de precedência.
- As funções de workspace não autorizam chamadas para APIs implantadas.
Tutoriais relacionados sobre governança de API
Estes tutoriais apresentam controles complementares para governar um workspace de API empresarial:
- Framework de Governança de API — conecte propriedade, controles, evidências e decisões de ciclo de vida.
- Mapeamento de Grupo SAML com Microsoft Entra ID — atribua acesso a equipes com base nos grupos do provedor de identidade.
- Scanner de Segredos — revise possíveis credenciais expostas nos ativos Apidog compatíveis.
- Logs de Auditoria — investigue e exporte atividades administrativas da organização.
- Provisionamento SCIM — conecte repositórios GHE.com compatíveis para fluxos de trabalho OpenAPI.
Top comments (0)