SSO OIDC

Guia de configuração para Single Sign-On via OpenID Connect com Google, Okta, Auth0, Keycloak e Azure AD v2.

Esta é uma documentação conceitual. A configuração OIDC é realizada em conjunto com o time Fhinck. Consulte contato@fhinck.com para configuração personalizada.

Provedores suportados

Provedor	Discovery URL padrão
Google Workspace	`https://accounts.google.com/.well-known/openid-configuration`
Okta	`https://<seu-dominio>.okta.com/.well-known/openid-configuration`
Auth0	`https://<seu-dominio>.auth0.com/.well-known/openid-configuration`
Keycloak	`https://<host>/realms/<realm>/.well-known/openid-configuration`
Azure AD v2	`https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration`

O que o cliente fornece

Item	Descrição
`client_id`	ID do cliente OIDC registrado no provedor de identidade.
`client_secret`	Segredo do cliente. Transmitido de forma segura ao time Fhinck.
Discovery URL	URL do endpoint `.well-known/openid-configuration` do provedor.
Claims mapping	Quais campos do JWT mapeiam para email, nome e grupos na Fhinck.

O que a Fhinck fornece

Item	Descrição
Redirect URI	URL de callback após autenticação — fornecida pelo time Fhinck.
Scopes requeridos	`openid profile email` são obrigatórios.

Scopes necessários

Configure o cliente OIDC para solicitar no mínimo os seguintes scopes:

Scopes mínimos

openid profile email

Para acesso a grupos e departamentos, adicione o scope específico do provedor (ex.: https://www.googleapis.com/auth/cloud-identity.groups.readonly no Google).

Mapeamento de claims

Campo Fhinck	Claim JWT típica	Obrigatório
Email	`email`	Sim
Nome	`name` ou `given_name + family_name`	Recomendado
Grupos	`groups` (Okta/Azure) ou `roles`	Opcional

Fluxo de configuração

Abertura de chamado

Contate o time Fhinck informando o provedor OIDC e a Discovery URL do ambiente.

Fhinck envia o Redirect URI

O time Fhinck envia a URL de callback para ser registrada no provedor.

Admin registra o aplicativo no provedor

Cria o cliente OIDC com o Redirect URI fornecido, habilita os scopes openid profile email e copia o client_id e client_secret.

Cliente envia as credenciais para a Fhinck

O client_id, client_secret e Discovery URL são enviados de forma segura ao time Fhinck.

Teste e validação

O time Fhinck configura o provedor na plataforma e valida o fluxo de login com um usuário de teste.

Troubleshooting

redirect_uri_mismatch

Causa: A Redirect URI configurada no provedor não corresponde exatamente à URI registrada na Fhinck.

Solução: Copie a Redirect URI exatamente como fornecida pelo time Fhinck — sem barra no final, sem parâmetros extras.

invalid_grant

Causa: O authorization code expirou (válido por ~60s) ou já foi usado.

Solução: O fluxo OIDC deve ser completado em menos de 1 minuto. Verifique latência de rede entre o provedor e o servidor Fhinck.

scope not granted

Causa: O scope solicitado não foi aprovado pelo admin do provedor ou pelo usuário.

Solução: No console do provedor, certifique-se de que os scopes openid profile email estão habilitados para o client criado. Em Google Workspace, pode ser necessário conceder acesso ao app no Google Admin.

Email não retornado

Causa: O provedor não inclui o claim email no ID token por padrão.

Solução: Adicione email ao escopo da requisição e verifique nas configurações do cliente se o claim está habilitado. Em Keycloak, pode ser necessário adicionar o mapper de email no Client Scope.