Registo de aplicação OpenID Connect
Um registo de aplicação OpenID Connect no FoxIDs permite que uma aplicação web, de página única ou nativa autentique utilizadores através do FoxIDs e receba tokens de ID e de acesso. A aplicação é o Relying Party (RP) e o FoxIDs é o OpenID Provider (OP).
As principais funcionalidades OpenID Connect incluem discovery, Authorization Code Flow, PKCE, segredos e chaves de cliente, o endpoint UserInfo, logout iniciado pelo RP e front-channel logout.
Configuração
No FoxIDs Control:
- Selecione o ambiente onde a aplicação deve ser registada.
- Abra Applications e clique em Add application.
- Escolha Web Application, Single Page Application ou Native Application. Estas três opções OpenID Connect são apresentadas sem ativar Show all options.
- Introduza um nome e um URI de redirecionamento, reveja as informações geradas da aplicação e clique em Create.
- Copie qualquer segredo gerado antes de fechar o resultado da criação. Um segredo gerado só é apresentado durante a criação.
Após a criação, clique em Change application para rever ou alterar todas as definições da aplicação. O cartão do tipo de aplicação fornece uma configuração inicial adequada; o cliente OpenID Connect resultante pode depois ser ajustado.
Aplicação web (cliente confidencial)
Escolha Web Application para uma aplicação executada num servidor, como uma aplicação ASP.NET Core, Node.js, Java ou PHP. É criada como cliente confidencial com:
- Authorization Code Flow com o response type
code. - Um segredo de cliente gerado.
- PKCE desativado por predefinição. Ative Require PKCE após a criação quando a aplicação suportar PKCE. É recomendado como proteção adicional do código de autorização.
Introduza o URL base ou de callback da aplicação como Redirect URI. Ative Show advanced durante a criação apenas se precisar de escolher o ID de cliente ou configurar a correspondência exata do URL de redirecionamento.
Aplicação de página única (cliente público)
Escolha Single Page Application para uma aplicação executada no browser, como React, Angular, Vue ou Blazor WebAssembly. É criada como cliente público com:
- Authorization Code Flow com o response type
code. - PKCE ativado por predefinição.
- Sem segredo de cliente.
- A origem do URL de redirecionamento adicionada como origem CORS permitida.
Aplicação nativa (cliente público)
Escolha Native Application para uma aplicação móvel ou de computador instalada, como iOS, Android, React Native, .NET MAUI ou Ionic. É criada como cliente público com Authorization Code Flow, PKCE ativado por predefinição e sem segredo de cliente.
O URI de redirecionamento pode usar um esquema específico da aplicação, como myapp://callback, ou um URI HTTPS suportado pela aplicação.
URI de redirecionamento e valores absolutos
Por predefinição, Absolute URIs está desativado para aplicações web e de página única. O URL de redirecionamento configurado é então tratado como um valor base, sendo aceites os URL de redirecionamento que começam por esse valor.
Ative Show advanced e Absolute URIs se souber o URL exato na sua aplicação para o qual o utilizador deve ser redirecionado após o login. Introduza esse URL exato como Redirect URI. A mesma definição suporta URI exatos específicos de aplicações nativas.
Após a criação, os URI de redirecionamento, o URI de redirecionamento após logout e as origens CORS permitidas podem ser alterados no separador OpenID Connect Client. Mantenha Show advanced desativado, exceto quando a definição necessária for avançada.
Implicit Flow
Implicit Flow é mantido por compatibilidade, mas não é recomendado para novas aplicações. Prefira Authorization Code Flow com PKCE.
Para configurar um cliente público existente para Implicit Flow, clique em Change application, ative Show advanced, altere Response types para token id_token ou, opcionalmente, apenas token, e desative Require PKCE. Os response types podem ser alterados nas mesmas definições avançadas do cliente quando for necessária outra combinação suportada.
Endpoints da aplicação e segurança do cliente
As informações da aplicação no FoxIDs Control incluem a authority, o ID de cliente, o endpoint discovery, o endpoint authorize e o endpoint de token. Um documento discovery OpenID Connect tem este formato:
https://foxids.com/tenant-x/environment-y/application-client1(*)/.well-known/openid-configuration
Uma aplicação pode permitir login através de vários métodos de autenticação. Se um método de autenticação definir perfis, o método base e cada perfil podem ser selecionados de forma independente. Para selecionar um método de autenticação no URL de authority, adicione o respetivo nome ao segmento da aplicação:
https://foxids.com/tenant-x/environment-y/application-client1(login)/.well-known/openid-configuration
Durante o logout iniciado pelo RP, o nome do método de autenticação pode ser omitido quando o token de ID é incluído no pedido.
Issuer específico da aplicação
Por predefinição, os tokens emitidos para a aplicação usam o issuer do ambiente:
https://foxids.com/tenant-x/environment-y/
Para fazer corresponder o issuer à authority da aplicação, clique em Change application, ative Show advanced e ative Use matching issuer and authority with application specific issuer. O issuer passa a ser:
https://foxids.com/tenant-x/environment-y/application-client1(*)
O issuer específico da aplicação muda quando mudam os métodos de autenticação selecionados no URL de authority. Para APIs, o issuer depende assim da aplicação que efetua a chamada. Token exchange só é possível entre configurações com métodos de autenticação correspondentes.
Segurança do cliente
Os clientes públicos, incluindo aplicações de página única e nativas, não conseguem guardar credenciais de cliente em segurança. Configure-os sem um segredo de cliente e utilize Authorization Code Flow com PKCE.
Os clientes confidenciais autenticam-se no endpoint de token. O método de autenticação de cliente predefinido é client secret post. Ative Show advanced para o alterar para client secret basic ou private key JWT. PKCE também é recomendado quando o cliente confidencial o suporta. Se estiverem configurados tanto PKCE como um segredo ou chave de cliente, o FoxIDs valida ambos.
O método de autenticação de cliente none é suportado com PKCE. Podem ser configurados até 10 segredos e 4 chaves para um cliente. Guarde os segredos de cliente e as chaves privadas em segurança e faça a respetiva rotação quando necessário.
O FoxIDs estabelece uma sessão quando o utilizador é autenticado e inclui o respetivo ID de sessão no token de ID. A sessão é invalidada no logout. Dependendo da configuração do cliente e de o pedido de logout conter ou não um token de ID, o FoxIDs pode apresentar uma caixa de diálogo de confirmação do logout.
Cliente e API
Um registo de aplicação OpenID Connect pode conter tanto o cliente como o respetivo recurso OAuth 2.0. O ID de cliente é então também o nome do recurso API.
O exemplo seguinte configura oidc-web-app como cliente OpenID Connect e API:
- Clique em Change application e ative Show advanced.
- Altere o tipo de registo para OpenID Connect Client and OAuth 2.0 Resource.
- No separador OpenID Connect Client, mantenha selecionado Default resource 'oidc-web-app' for the application itself.
- Adicione os scopes
readewritesob o recurso predefinido.
No separador OAuth 2.0 Resource, defina os mesmos scopes read e write expostos pela API.
Recurso e scopes
Em alternativa, uma API pode ser registada separadamente como recurso OAuth 2.0. Neste exemplo, o cliente oidc-web-app chama uma Orders API separada com o nome de recurso orders-api.
No separador OpenID Connect Client do cliente:
- Desmarque Default resource 'oidc-web-app' for the application itself, porque este cliente não atua como a sua própria API.
- Adicione o recurso
orders-api. - Adicione os scopes
readewritesob esse recurso.
Os valores completos de scope pedidos pelo cliente são orders-api:read e orders-api:write.
No registo da Orders API, defina read e write no separador OAuth 2.0 Resource.
Os scopes pedidos por um cliente são validados face aos scopes configurados na API. Se o cliente e a API estiverem no mesmo registo, os scopes adicionados sob o recurso predefinido do cliente são adicionados automaticamente ao recurso.
Por predefinição, o ID de cliente é a audience tanto do token de ID como do token de acesso. Os scopes de recurso configurados adicionam audiences de API ao token de acesso, e um token de acesso pode destinar-se a vários recursos API.
Scopes e claims
Os scopes OpenID Connect são configurados no separador OpenID Connect Client. Os scopes predefinidos offline_access, profile, email, address e phone podem ser alterados ou removidos. Para cada scope, Voluntary claims controla os claims emitidos quando o cliente pede esse scope.
Ative Show advanced para configurar Issue claims. Adicione um claim específico ou * para emitir todos os claims disponíveis no token de acesso. Mantenha Include in ID token desativado para *; caso contrário, todos os claims disponíveis são copiados para o token de ID, podendo torná-lo excessivamente grande e causar problemas em flows em que o token de ID é enviado durante o logout.
Em alternativa, adicione um claim a Voluntary claims de um scope e peça esse scope a partir da aplicação. Claims individuais podem ser incluídos no token de ID quando a aplicação precisar deles. Os claims também podem ser alterados com transformações e tarefas de claims.
Tempo de vida dos tokens
Clique em Change application e ative Show advanced para configurar o tempo de vida do código de autorização, do token de ID, do token de acesso e do refresh token.
Neste exemplo, cada refresh token é válido durante 36 000 segundos. A aplicação pode continuar a renovar a sessão até ser atingido o tempo de vida absoluto do refresh token de 86 400 segundos.
Exigir autenticação multifator (MFA)
Um cliente OpenID Connect pode exigir MFA incluindo urn:foxids:mfa no parâmetro acr_values. Pode ser combinado com valores mais específicos, como urn:foxids:link. Consulte pedir MFA a partir de aplicações.
O parâmetro acr_values pode ser definido no evento OnRedirectToIdentityProvider em Startup.cs:
options.Events.OnRedirectToIdentityProvider = (context) =>
{
context.ProtocolMessage.AcrValues = "urn:foxids:mfa";
return Task.FromResult(string.Empty);
};
Consulte AspNetCoreOidcAuthorizationCodeSample e a respetiva configuração de Startup.cs.
Guias práticos
- Ligar Tailscale