As aplicações modernas estão cada vez mais a afastar-se das palavras-passe tradicionais e a adotar métodos de autenticação sem palavra-passe que são mais seguros e fáceis para os utilizadores. Neste post, mostrarei como autenticar utilizadores numa aplicação ASP.NET Core gerada por IA utilizando FoxIDs com OpenID Connect e ativar uma experiência de início de sessão totalmente sem palavra-passe utilizando códigos únicos entregues por e-mail.
Começaremos com um ambiente FoxIDs limpo, criaremos uma nova aplicação web ASP.NET Core, ligá-la-emos com OpenID Connect e, finalmente, activaremos o login passwordless com OTP baseado em e-mail.
Criação de um ambiente de desenvolvimento FoxIDs
Comecei por criar um novo ambiente de desenvolvimento vazio em FoxIDs. Um ambiente limpo simplifica a configuração da autenticação a partir do zero e garante que pode replicar estes passos no seu próprio tenant.
Se nunca utilizou FoxIDs antes, pode criar um tenant gratuito em:
Cada tenant vem com dois ambientes prontos a usar para que possa experimentar livremente.
Configurar autenticação
Comece por configuring como os utilizadores devem iniciar sessão. Neste caso, queremos que os utilizadores iniciem sessão sem palavra-passe, utilizando apenas o seu endereço de e-mail e uma palavra-passe de utilização única (OTP) que lhes foi enviada.
- Selecione o separador Autenticações no seu ambiente FoxIDs.
- Clique em Padrão — UI de início de sessão do utilizador.
- Na secção Autenticação, desative Autenticação por palavra-passe e ative Sem palavra-passe com e-mail (palavra-passe de utilização única).
- Clique em Atualizar para guardar as alterações.
Isto permite aos utilizadores criar uma nova conta e proporcionar uma experiência sem palavra-passe, onde se autenticam simplesmente introduzindo o seu endereço de e-mail e o OTP que recebem.
Gere a aplicação ASP.NET Core
Em seguida, precisamos de uma aplicação para autenticação. Pode utilizar o aviso do AI para gerar uma nova aplicação ASP.NET Core Razor Pages direcionada para o .NET 10 ou adicionar OpenID Connect a uma aplicação existente.
Leia a publicação “Autenticação sem palavra-passe em ASP.NET Core com FoxIDs e OTP” se pretender criar a aplicação ASP.NET Core manualmente.
Para este passo a passo, estou a gerar uma aplicação ASP.NET Core simples em VS Code com Codex. Também pode usar o Copilot.
É um programador especialista em ASP.NET Core.
Objectivo: Criar (ou actualizar) uma aplicação web ASP.NET Core que autentica os utilizadores com FoxIDs utilizando OpenID Connect (fluxo de código de autorização), utilizando autenticação de cookies para a sessão local e OIDC como esquema de desafio.
### Modo (escolha um)
- MODE = "NEW_APP" -> criar uma nova aplicação Razor Pages
- MODE = "EXISTING_APP" -> modificar a solução atual sem quebrar as rotas/páginas existentes
MODE: {{MODE}}
### Detalhes do aplicativo
- ProjectName: {{PROJECT_NAME}} (utilizado apenas se MODE = "NEW_APP")
- TargetFramework: net10.0 (ou manter existente se for mais recente)
- URL HTTPS local (deve corresponder ao endereço base do URI de redireccionamento FoxIDs): {{APP_BASE_URL}} (exemplo: https://localhost:7283/)
### Configuração FoxIDs OIDC
Não codifique Authority, ClientId ou ClientSecret no código ou neste aviso.
Em vez de:
- Leia-os nas chaves de configuração:
- "IdentitySettings:Authority"
- "IdentitySettings:ClientId"
- "IdentitySettings:ClientSecret"
- A resposta final deve explicar claramente ao utilizador onde e como definir estes valores de configuração (por exemplo, em appsettings.json, variáveis de ambiente ou segredos do utilizador).
### Requisitos de implementação
1) Adicione autenticação em Program.cs:
- Configurar a autenticação:
- DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme
- DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme
- Adicione autenticação de cookies.
- Adicionar autenticação OpenID Connect:
- Authority da configuração: "IdentitySettings:Authority"
- ClientId da configuração: "IdentitySettings:ClientId"
- ClientSecret da configuração: "IdentitySettings:ClientSecret"
- ResponseType = "code"
- SaveTokens = true
- Scopes: "openid", "profile", "email", "offline_access"
- MapInboundClaims = false
- TokenValidationParameters:
- NameClaimType = "sub"
- RoleClaimType = "role"
- Adicione OpenIdConnectEvents com:
- OnAuthenticationFailed: apenas em Development, devolve uma resposta simples em texto simples com a mensagem de exceção para depuração. Nunca exponha detalhes de exceção ou PII em produção.
- Certifique-se de que o middleware está registado:
- app.UseAuthentication() é chamado antes de app.UseAuthorization().
2) Adicionar cablagem de configuração:
- Adicione uma secção `IdentitySettings` em appsettings.json contendo apenas valores de espaço reservado não secretos, por exemplo:
- "Authority": "https://your-foxids-authority/"
- "ClientId": "your-client-id"
- Leia "IdentitySettings:ClientSecret" da configuração, mas armazene o seu valor em segredos de utilizador .NET para desenvolvimento local ou numa variável de ambiente ou armazenamento secreto seguro em produção.
- Se MODE = "EXISTING_APP", junte esta secção à configuração existente sem substituir as definições não relacionadas.
- Adicione comentários ou texto explicativo na resposta final que:
- Estes valores devem ser substituídos pelo utilizador pelos seus FoxIDs Authority, ClientId e ClientSecret reais.
- Os segredos não devem ser gravados em appsettings.json ou confirmados no controlo de origem.
3) Adicione pontos finais de login/logout:
- Crie `Controllers/AuthController.cs` com um controlador MVC padrão:
- Utilize o padrão de rota `[controller]/[action]`.
- Ação de início de sessão (GET):
- Caso o utilizador já esteja autenticado, redirecione para "/".
- Caso contrário, emita um Challenge utilizando OpenIdConnectDefaults.AuthenticationScheme com RedirectUri = "/".
- Ação de logout (POST, com [ValidateAntiForgeryToken]):
- Caso o utilizador não esteja autenticado, redirecione para "/".
- Caso contrário, SignOut de:
- CookieAuthenticationDefaults.AuthenticationScheme e
- OpenIdConnectDefaults.AuthenticationScheme
com um RedirectUri = "/".
4) Adicionar login parcial da UI:
- Crie `Pages/Shared/_LoginPartial.cshtml`.
- Comportamento:
- Se o utilizador estiver autenticado:
- Mostre um botão "Log off" que envia para `Auth/Logout` com um token anti-falsificação.
- Se o utilizador não estiver autenticado:
- Mostrar um link "Login" a apontar para `Auth/Login`.
5) Adicionar parcial ao layout:
- Atualize `Pages/Shared/_Layout.cshtml` para incluir:
- `<partial name="_LoginPartial" />` na área da barra de navegação, de preferência alinhado ao lado direito da barra de navegação.
- Não remova o conteúdo do layout existente.
6) Comportamento da página inicial (para apresentação de claims):
- Se MODE = "NEW_APP" ou se a página inicial existente estiver efetivamente vazia (apenas padrão ou nenhum conteúdo significativo):
- Implemente uma página inicial simples que:
- Dá as boas-vindas ao utilizador.
- Se o utilizador estiver autenticado, apresenta uma lista ou tabela dos claims do utilizador (tipo e valor).
- Se o utilizador não estiver autenticado, será apresentada uma mensagem como "Não está ligado" e uma dica para clicar no link de login.
- Se MODE = "EXISTING_APP" e a página inicial já tiver conteúdo significativo:
- Não modifique a página inicial existente para adicionar a visualização de claims.
- Deixe o conteúdo existente da página inicial intacto.
### Expectativas de produção
1) Alterações de código e ficheiro:
- Liste todos os ficheiros criados ou modificados.
- Para cada ficheiro, produza o conteúdo completo do ficheiro (ou uma comparação muito clara se o ficheiro for grande).
- Certifique-se de que o projeto pode ser compilado e executado com `dotnet run` (ou o comando habitual para a estrutura de destino escolhida).
2) Posicionamento e orientação da configuração:
- Mostre claramente onde são exactamente lidos os valores de configuração Authority, ClientId e ClientSecret no código (secção IdentitySettings).
- Explique ao utilizador:
- Que devem definir esses valores após a geração do código.
- Como definir Authority e ClientId em appsettings.json.
- Como definir ClientSecret em segredos do utilizador localmente ou numa variável de ambiente ou armazenamento secreto seguro em produção.
3) Informações do endpoint da aplicação:
- Na sua resposta final ao utilizador, declare explicitamente:
- O URL do terminal local que a aplicação escuta (por exemplo: `{{APP_BASE_URL}}` ou o URL que o modelo utiliza).
- Uma instrução curta e clara informando o utilizador:
- "Configure o seu FoxIDs Authority e ClientId na secção IdentitySettings. Armazene ClientSecret em segredos de utilizador localmente ou numa variável de ambiente ou armazenamento secreto seguro em produção, para que possa ser lido em tempo de execução sem ser confirmado."
4) Guarda-corpos:
- Não introduza refatoração não relacionada.
- Não remova quaisquer recursos existentes para além do estritamente necessário para integrar o OIDC com o FoxIDs.
- Mantenha a solução focada em:
- Adicionando cookie + autenticação OIDC,
- AuthController,
- Login parcial,
- Alterações mínimas na página inicial, conforme descrito.
Agora implemente todos os itens acima.
A resposta da IA deve instruí-lo sobre onde configurar o Authority, o ID do cliente e o segredo do cliente.
Agora tente executar a aplicação para encontrar o endpoint.
A minha aplicação de exemplo é executada localmente em https://localhost:7154/
Pode encontrar o código de exemplo gerado por IA em: https://github.com/ITfoxtec/dotnet.samples/tree/main/WebAppPasswordLessEmailAI
Configure a aplicação web em FoxIDs
Agora que já sabemos o endereço local da aplicação web, podemos registá-la em FoxIDs para que possa autenticar os utilizadores através de OpenID Connect.
- Selecione o separador Aplicações no seu ambiente FoxIDs.
- Escolha Nova aplicação e selecione Aplicação Web — OpenID Connect.
- Em Nome, introduza um nome, por exemplo: ASP.NET aplicação web.
- No Redirect URI, adicione o endereço base da aplicação: https://localhost:7154/ Por defeito, o FoxIDs permite o redireccionamento para qualquer página subsequente neste URL base. Se preferir uma validação mais rigorosa, pode exigir URIs de redireccionamento absolutos.
- Clique em Criar.
FoxIDs apresenta agora os detalhes da ligação para a sua nova aplicação, incluindo:
- Authority
- ID do cliente
- Segredo do cliente
Copie Authority e Client ID para a secção IdentitySettings do projeto. Armazene o Segredo do cliente em segredos do utilizador .NET localmente ou numa variável de ambiente segura ou armazenamento de segredos na produção.
Configurar a autenticação na aplicação ASP.NET
Com a aplicação FoxIDs criada, o passo seguinte é configurar a autenticação no projeto ASP.NET Core.
Adicione os detalhes da ligação não secreta FoxIDs a appsettings.json:
{
"IdentitySettings": {
"Authority": "https://foxids.com/{tenant}/{environment}/{application}/",
"ClientId": "your-client-id"
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"AllowedHosts": "*"
}
Armazene o segredo do cliente localmente sem o adicionar ao appsettings.json:
dotnet user-secrets init
dotnet user-secrets set "IdentitySettings:ClientSecret" "your-client-secret"
*Substitua os valores de exemplo pelos do seu próprio ambiente FoxIDs e nunca confirme o verdadeiro segredo do cliente. *
Conecte-se
Clique em Login e será redirecionado para o ecrã de login do FoxIDs.
Selecione Criar utilizador.
Preencha o formulário Criar utilizador com o seu e-mail (ou um e-mail de teste ao qual tenha acesso), nome e apelido e clique em Criar.
Introduza a palavra-passe de utilização única (OTP) que recebeu por e-mail e clique em Efetuar login.
Está ligado e os claims do seu utilizador de teste são exibidas.
Em seguida, tente fazer logoff e login novamente para experimentar o fluxo de login sem palavra-passe utilizando o e-mail OTP.