SSO (Single Sign-On)

O ION Guard permite que sua organização use Single Sign-On via Microsoft Entra ID (antigo Azure AD), eliminando a necessidade de senhas locais para os usuários e centralizando a gestão de acesso no seu diretório corporativo.

A plataforma é construída sobre uma abstração de provedores (SsoProviderContract) — Microsoft Entra ID é o provedor suportado nativamente, e a arquitetura aceita outros provedores OIDC (Google Workspace, Okta, Keycloak) com pequenas adições de código.

Caminho de acesso: menu Configurações → SSO (rota /settings/sso).

Perfil necessário

Disponível para Tenant Admin ou superior.

Múltiplo fator de autenticação (MFA)

O ION Guard não possui um segundo fator (TOTP) próprio. O múltiplo fator e as políticas de acesso condicional são aplicados pelo provedor de identidade (Microsoft Entra ID): ao habilitar o SSO e desativar o login por senha do usuário, toda a autenticação — incluindo MFA — passa a ser controlada pelo seu diretório corporativo.

Pré-requisitos no Azure Portal

Antes de configurar no ION Guard, prepare no Azure Portal:

Uma App Registration dedicada ao ION Guard (Entra ID → App registrations → New registration), do tipo single tenant (Accounts in this organizational directory only)
Os identificadores anotados na aba Overview:
- Application (client) ID
- Directory (tenant) ID
Um client secret criado em Certificates & secrets — copie o Value logo após criar (ele só aparece uma vez)
A Redirect URI cadastrada como tipo Web: https://<seu-dominio>/auth/sso/entraid/callback

As permissões delegadas do Microsoft Graph usadas pelo SSO são openid, profile, email e User.Read — geralmente já vêm pré-configuradas na App Registration.

dica

A URL exata de callback aparece na tela de configuração SSO do ION Guard (campo URI de redirecionamento, com botão de copiar). Copie de lá e cole no Azure Portal para evitar erros de digitação.

Configurar o provedor

Na página Configurações → SSO, preencha o card do Microsoft Entra ID:

Campo	Onde encontrar no Azure
Azure Tenant ID	App registration → Overview → Directory (tenant) ID
Application (client) ID	App registration → Overview → Application (client) ID
Client secret	Certificates & secrets → o Value copiado na criação
Habilitar este provedor	Marque o checkbox para ativar

Clique em Salvar configuração. A partir desse momento, a tela de login passa a exibir o botão Entrar com Microsoft.

Todos os três campos são obrigatórios no primeiro cadastro. Azure Tenant ID e Application (client) ID são validados como UUID; o Client secret exige no mínimo 8 caracteres.

Não cole o "ID secreto"

O Azure mostra duas colunas para cada client secret: Value (o segredo real) e Secret ID (UUID). Use o Value. Colar o Secret ID causa erro AADSTS7000215.

Rotação de secret

Quando precisar rotacionar:

Crie um novo client secret no Azure Portal e copie o Value
Cole no campo Client secret do ION Guard e salve
Delete o secret antigo no Azure (após confirmar que o novo funciona)

Deixar o campo Client secret em branco preserva o valor armazenado — útil para alterar apenas Azure Tenant ID ou Application (client) ID sem rotacionar o secret. O secret é criptografado em repouso e nunca é reexibido na interface (o card apenas indica que há um secret salvo).

Habilitar SSO para usuários

Por padrão, novos usuários têm SSO desabilitado. Para liberar acesso via SSO a um usuário existente:

Abra a página de Usuários
Edite o usuário
Em Métodos de login, marque Login via SSO
(Opcional) Desmarque Login por senha para forçá-lo a usar apenas SSO
Salvar

Pré-existência obrigatória

O usuário precisa já existir no ION Guard com o mesmo e-mail do Entra ID. O SSO faz match passivo por e-mail — não há criação automática de contas (JIT) no primeiro login.

Após o primeiro login via SSO, o oid (Object ID imutável do Entra ID) é salvo como vínculo. Daí em diante, mesmo que o e-mail do usuário mude no diretório, o login continua funcionando.

Cada usuário precisa de pelo menos um método de login

As flags Login por senha e Login via SSO são independentes, mas ao menos uma precisa estar ativa. O usuário Platform Admin mantém sempre o login por senha habilitado, como acesso de emergência.

Como o usuário entra

Com SSO configurado e habilitado para o usuário:

O usuário acessa a tela de login do ION Guard
Clica no botão Entrar com Microsoft
É redirecionado para o portal Microsoft, onde autentica normalmente (incluindo MFA, se exigido pelo diretório)
Volta para o ION Guard já logado, indo direto para o dashboard

Quando ambos os métodos de login estão habilitados, o usuário pode escolher: usar o botão SSO ou preencher e-mail/senha logo abaixo do divisor "ou".

Acesso de emergência

Mesmo com SSO ativo, o usuário Platform Admin mantém sempre acesso por senha local — é o mecanismo de recuperação caso o IdP fique indisponível ou o client secret expire.

Para situações de IdP fora do ar:

O Platform Admin entra por /login com senha
Pode desabilitar temporariamente o provedor SSO em Configurações → SSO desmarcando "Habilitar este provedor"
Usuários com apenas SSO habilitado podem ter o login por senha reativado individualmente na página de Usuários

Mapeamento de papéis via App Roles

Esta é uma capacidade opcional e avançada. Por padrão, o papel ION Guard de cada usuário é gerenciado localmente no painel. Se você prefere centralizar a gestão de papéis no Entra ID (quem está no grupo X vira automaticamente Tenant Admin no ION Guard, sem o operador do painel precisar lembrar de atualizar), você pode declarar App Roles na sua App Registration e mapeá-los para papéis ION Guard.

Por que App Roles e não grupos

App Roles vêm como claim roles direto no token de identidade (sem chamada extra ao Microsoft Graph), são gerenciados em uma UI dedicada no Azure, e ficam scoped à própria aplicação (não vazam para outros sistemas).

Declarar App Roles no manifest

No Azure Portal: App registrations → ION Guard → Manifest. Localize o array "appRoles" (geralmente vazio: "appRoles": []) e substitua por:

"appRoles": [
    {
        "allowedMemberTypes": ["User"],
        "description": "Acesso total ao tenant ionguard.",
        "displayName": "ionguard TenantMaster",
        "id": "44005cb8-2ebb-48f0-bd23-2a6855771b20",
        "isEnabled": true,
        "origin": "Application",
        "value": "ionguard.tenant_master"
    },
    {
        "allowedMemberTypes": ["User"],
        "description": "Gestão operacional do tenant (CRUD, alertas, usuários Operator/Viewer).",
        "displayName": "ionguard TenantAdmin",
        "id": "2c74b29d-4cab-466b-8909-4d9ad99760ba",
        "isEnabled": true,
        "origin": "Application",
        "value": "ionguard.tenant_admin"
    },
    {
        "allowedMemberTypes": ["User"],
        "description": "Reconhecimento e resolução de alertas em sites atribuídos.",
        "displayName": "ionguard Operator",
        "id": "22a9792b-aede-4fa3-9350-cc361b948033",
        "isEnabled": true,
        "origin": "Application",
        "value": "ionguard.operator"
    },
    {
        "allowedMemberTypes": ["User"],
        "description": "Acesso somente leitura em sites atribuídos.",
        "displayName": "ionguard Viewer",
        "id": "b702a6b4-8720-4b0e-8ce5-091edb78db16",
        "isEnabled": true,
        "origin": "Application",
        "value": "ionguard.viewer"
    }
]

Detalhes do manifest

Gere UUIDs únicos para cada id (não reuse os do exemplo).
allowedMemberTypes aceita apenas "User" e/ou "Application". Não use "Group" (o Azure rejeita com erro Entitlement DirectAccessGrantTypes invalid). Grupos podem ser atribuídos ao role pela UI mesmo com ["User"].
O value é o que vem no token — pode ser qualquer string, desde que consistente entre o Azure e o cadastro no ION Guard.
Não declare um role mapeado para Platform Admin — esse papel nunca é gerenciado por SSO.

Clique em Save.

Claim roles no token

Não é preciso adicionar roles como optional claim em Token configuration. O endpoint v2.0 do Microsoft Identity Platform (usado pelo ION Guard) inclui automaticamente esse claim quando o usuário tem App Roles atribuídos.

Atribuir usuários/grupos aos App Roles

Azure Portal → Enterprise applications (menu diferente de App registrations)
Selecione o ION Guard
Users and groups → Add user/group
Escolha usuários ou grupos → selecione o App Role → Assign

Um mesmo usuário pode receber mais de um App Role — o ION Guard escolhe o de maior prioridade entre os mapeados.

Cadastrar os mapeamentos no ION Guard

Em Configurações → SSO, role para baixo até Mapeamento de App Roles e adicione uma linha para cada App Role declarado no Azure:

App Role no Azure	Papel no ION Guard	Prioridade sugerida
`ionguard.tenant_master`	Tenant Master	40
`ionguard.tenant_admin`	Tenant Admin	30
`ionguard.operator`	Operator	20
`ionguard.viewer`	Viewer	10

Cada linha exige o App Role no Azure (texto livre), o Papel no ION Guard (Tenant Master, Tenant Admin, Operator ou Viewer — Platform Admin não é selecionável) e uma Prioridade (número inteiro de 0 a 10000). Prioridades maiores vencem em caso de conflito, quando um usuário tem múltiplos App Roles.

A cada login SSO bem-sucedido, o ION Guard:

Lê o claim roles do token de identidade
Para cada App Role recebido, procura o mapeamento correspondente
Aplica o de maior prioridade
Atualiza o papel local e marca o usuário como gerenciado por SSO

Quando o usuário está gerenciado por SSO, o select de papel no formulário de edição fica bloqueado (exceto para Platform Admin) e o backend rejeita alterações manuais de papel. Para readquirir controle manual:

Remova o usuário do App Role no Azure; ou
Desabilite SSO para esse usuário no painel

Cenários de borda: um usuário SSO sem nenhum App Role (ou com App Role sem mapeamento cadastrado) conserva o papel local; o Platform Admin nunca é tocado pela sincronização.

Propagação no Azure

Atribuições de App Roles em Enterprise applications podem levar alguns minutos para entrar em novos tokens. Se acabou de atribuir e o papel não sincronizou, aguarde uns minutos e tente login novamente.

Auditoria

Eventos SSO são registrados no Log de Auditoria (filtre por action começando com sso.):

Ação	Quando
`sso.login_success`	Usuário entrou via SSO com sucesso
`sso.config_created`	Primeira configuração do provedor
`sso.config_updated`	Alteração na configuração
`sso.role_mapping_saved`	Mapeamento criado ou atualizado
`sso.role_mapping_deleted`	Mapeamento removido

Tentativas de login rejeitadas (e-mail não cadastrado, SSO desabilitado para o usuário, etc.) não geram entrada no Log de Auditoria — vão para o log do servidor (storage/logs/laravel.log) com o prefixo sso.login_rejected, pois não há usuário válido associado.

Solução de problemas

Sintoma	Causa provável
Botão "Entrar com Microsoft" não aparece na tela de login	Provedor não habilitado em Configurações → SSO
Redirecionamento ao Azure dá `AADSTS50011: redirect URI mismatch`	A Redirect URI cadastrada no Azure não bate exatamente com a do ION Guard. Compare com a URL do campo URI de redirecionamento no card de SSO e ajuste em Authentication da App Registration
`AADSTS7000215: invalid client secret`	Secret expirou ou foi rotacionado no Azure mas não atualizado no ION Guard. Crie um novo no Azure e cole no painel
Login passa no Azure mas volta para `/login` sem erro visível	E-mail do Azure não bate com nenhum usuário no ION Guard, ou o usuário existe mas tem Login via SSO desmarcado. Verifique na página de Usuários
Papel não sincroniza após atribuir App Role	Propagação do Azure pode demorar alguns minutos. Faça logout e login depois de aguardar. Verifique também se o mapeamento existe em Configurações → SSO → Mapeamento de App Roles com o `value` exato do manifest
Manifest do Azure retorna `Entitlement DirectAccessGrantTypes invalid`	`allowedMemberTypes` contém valor inválido (provavelmente `"Group"`). Use apenas `"User"` e/ou `"Application"`

Próximos passos

Usuários — Habilitar SSO e gerenciar métodos de login por usuário
Perfis de Acesso — Papéis do ION Guard mapeados pelos App Roles
Auditoria — Rastrear eventos sso.*

Pré-requisitos no Azure Portal​

Configurar o provedor​

Rotação de secret​

Habilitar SSO para usuários​

Como o usuário entra​

Acesso de emergência​

Mapeamento de papéis via App Roles​

Por que App Roles e não grupos​

Declarar App Roles no manifest​

Atribuir usuários/grupos aos App Roles​

Cadastrar os mapeamentos no ION Guard​

Comportamento no login​

Auditoria​

Solução de problemas​

Próximos passos​