oidc

Home > Autenticação > OpenID Connect 🚧

Login com Google, Microsoft, Keycloak (OpenID Connect)

Important

Em desenvolvimento (2.0). Ainda não está numa versão lançada e pode mudar.

Vale para a 2.0 · Delphi XE em diante e Lazarus/FPC 3.2 em diante · Nível: intermediário

Em uma frase: o TRALOIDCLogin faz o login da sua aplicação web por um provedor OpenID Connect (Google, Microsoft Entra ID, Keycloak, Auth0, Okta ou qualquer emissor OIDC) e o TRALClientOIDCAuth faz o mesmo num programa desktop ou de console.

Você vai precisar: o pacote RALPluginAuthPackage, um motor cliente ligado ao executável (Indy, Synopse, netHTTP ou fpHTTP: o login chama o provedor), o OpenSSL (o id_token vem assinado com RS256/ES256) e a aplicação registrada no provedor (ClientID, segredo e a URL de retorno).

No servidor (aplicação web)

Sessao := TRALServerJWTAuth.Create(Self);   // o token da SUA aplicação
Sessao.SignSecretKey := 'troque-esta-chave';
Sessao.UseCookie := True;                   // o token vai no cookie raltoken
Servidor.Authentication := Sessao;

Login := TRALOIDCLogin.Create(Self);
Login.Provider := opKeycloak;               // só ajusta RolesClaim
Login.Issuer := 'https://sso.empresa.com/realms/vendas';
Login.ClientID := 'portal';
Login.ClientSecret := '...';
Login.Session := Sessao;
Login.Server := Servidor;

Servidor.CreateRoute('painel', Painel).RequireRoles('admin');

O plugin tem três rotas próprias, que não pedem autenticação:

rota	o que faz
/oidc/login?return=/painel	manda o navegador ao provedor, com state, nonce e PKCE S256 guardados por 10 minutos
/oidc/callback	a volta do provedor: troca o código pelo token, confere o id_token e emite o token da aplicação no cookie
/oidc/logout	apaga o cookie e passa pelo logout do provedor, quando ele tem

Registre no provedor a URL de retorno https://seu-site/oidc/callback (ou fixe RedirectURI). O que o callback confere: a assinatura (pelas chaves publicadas no jwks_uri do provedor, ou o ClientSecret para HS256), iss, aud, azp, exp e o nonce. O state só vale uma vez. return só aceita um caminho local (/x): nunca outro site.

OnLogin recebe as claims e a identidade já preenchida, e pode recusar (AAllow := False) ou mudar a página de destino. Sem Session, é ali que você cria a sua sessão.

Provedores

Provider	Issuer	papéis (RolesClaim)
opGoogle	https://accounts.google.com (preenchido)	nenhum
opMicrosoft	https://login.microsoftonline.com/<tenant>/v2.0	roles,groups
opKeycloak	https://<host>/realms/<realm>	realm_access.roles,groups
opAuth0	https://<tenant>.auth0.com/	roles,groups
opOkta	https://<org>.okta.com	groups
opGeneric	o do provedor	roles,groups

Um nome com ponto em RolesClaim entra num objeto (realm_access.roles).

Vários servidores

O state fica em memória. Atrás de um balanceador, ligue Store a um TRALFileStore (ou outro armazenamento compartilhado) para o callback achar o state em qualquer servidor.

No cliente (desktop, console, serviço)

Fluxo de dispositivo (RFC 8628): o programa mostra um código, o usuário o digita no celular ou em outro computador.

Auth := TRALClientOIDCAuth.Create(Self);
Auth.Issuer := 'https://sso.empresa.com/realms/vendas';
Auth.ClientID := 'app-desktop';
if Auth.StartDeviceFlow(Disp, Erro) then
begin
  ShowMessage('Abra ' + Disp.VerificationURI + ' e digite ' + Disp.UserCode);
  if Auth.WaitDeviceFlow(Disp, 300, Erro) then
    Cliente.Authentication := Auth;   // daqui em diante, Bearer e renovação sozinhos
end;

Navegador do sistema (RFC 8252): Auth.LoginURL(Loopback.RedirectURI, State) dá a URL; com um TRALOAuth2Loopback o programa recebe o código e chama Auth.SetAuthorizationCode. IdToken e IdClaims guardam quem logou.

Erros comuns

sintoma	causa
502 no /oidc/login	o provedor não respondeu ou Issuer está errado (o documento é Issuer + /.well-known/openid-configuration; DiscoveryURL troca)
400 "state" no callback	o login demorou mais de 10 minutos, a página foi recarregada, ou outro servidor recebeu a volta (use Store)
403 "não é desta aplicação"	ClientID diferente do registrado, ou o relógio do servidor fora de hora (exp)
redirect_uri_mismatch no provedor	a URL de retorno registrada não é a que o RAL montou: fixe RedirectURI
depois do login, 401 nas rotas	Session não tem UseCookie, ou o site é HTTP e o cookie foi marcado Secure por um proxy (veja atrás de um proxy)

Veja também

• Papéis e políticas
• Autenticação
• Senhas e TOTP