/.well-known/openid-configuration.
options.Authority = settings.Issuer;
options.ClientId = settings.ClientId;
options.ClientSecret = settings.ClientSecret;
options.ResponseType = OpenIdConnectResponseType.Code;
options.ResponseMode = OpenIdConnectResponseMode.Query;
// PKCE (RFC 7636) with S256; the handler also sends state and nonce and checks them on the way back.
options.UsePkce = true;
options.Scope.Clear();
options.Scope.Add("openid");
options.Scope.Add("profile");
options.Scope.Add("email");
// messages:read is a scope of your API; the example API requires it on /api/messages.
options.Scope.Add("messages:read");
options.SaveTokens = true;
options.MapInboundClaims = false;
options.GetClaimsFromUserInfoEndpoint = false;
// Pushed authorization requests (RFC 9126) when the environment offers the endpoint.
options.PushedAuthorizationBehavior = PushedAuthorizationBehavior.UseIfAvailable;
options.CallbackPath = "/signin-oidc";
// ID tokens must be signed, with the keys of the environment and one of these algorithms.
options.TokenValidationParameters.RequireSignedTokens = true;
options.TokenValidationParameters.ValidateIssuerSigningKey = true;
options.TokenValidationParameters.ValidAlgorithms = ["RS256", "ES256", "PS256"];
options.TokenValidationParameters.NameClaimType = "name";
// These cookies carry the state and the nonce between the redirect and the callback.
var cookiePolicy = settings.SecureCookie ? CookieSecurePolicy.Always : CookieSecurePolicy.SameAsRequest;
options.NonceCookie.SameSite = SameSiteMode.Lax;
options.NonceCookie.SecurePolicy = cookiePolicy;
options.CorrelationCookie.SameSite = SameSiteMode.Lax;
options.CorrelationCookie.SecurePolicy = cookiePolicy;
```
Tre eventi completano l'handler. Il primo aggiunge l'identificatore della tua API come `resource` (RFC 8707); senza di esso, l'access token non è destinato alla tua API e l'API lo rifiuta. Il secondo verifica il parametro `iss` della risposta di autorizzazione (RFC 9207): ASP.NET Core non lo verifica, mentre KeenAuth lo pubblicizza.
```csharp
OnRedirectToIdentityProvider = context =>
{
// Build the redirect URI from the setting, not from the Host header of the request.
context.ProtocolMessage.RedirectUri = settings.RedirectUri;
// RFC 8707: an access token for your API.
context.ProtocolMessage.SetParameter("resource", settings.ApiAudience);
return Task.CompletedTask;
},
OnMessageReceived = async context =>
{
// RFC 9207: the authorization response must name the issuer that answered.
var configuration = await context.Options.ConfigurationManager!
.GetConfigurationAsync(context.HttpContext.RequestAborted);
var iss = context.ProtocolMessage.Iss;
if (iss is not null ? iss != configuration.Issuer : configuration.AuthorizationResponseIssParameterSupported)
{
context.Fail("The authorization response has a wrong or missing iss parameter.");
}
},
```
Il terzo rifiuta un ID token che non è firmato con una chiave del tuo ambiente. ASP.NET Core salta la verifica della firma di un ID token che proviene dal token endpoint, cosa che OpenID Connect Core consente su TLS; questa app la esegue comunque.
```csharp
OnTokenResponseReceived = async context =>
{
// ASP.NET Core skips the signature check of an ID token that comes from the token endpoint (OpenID
// Connect Core 3.1.3.7 allows it over TLS). This app does not: the token must be signed by a key
// of the environment, with an allowed algorithm.
var configuration = await context.Options.ConfigurationManager!
.GetConfigurationAsync(context.HttpContext.RequestAborted);
var parameters = context.Options.TokenValidationParameters.Clone();
parameters.ValidIssuer = configuration.Issuer;
parameters.IssuerSigningKeys = configuration.SigningKeys;
parameters.ValidAudience = settings.ClientId;
var result = await new JsonWebTokenHandler().ValidateTokenAsync(
context.TokenEndpointResponse.IdToken ?? "", parameters);
if (!result.IsValid)
{
context.Fail("The ID token is not signed by a key of the environment.");
}
},
```
Gli ultimi due eventi inseriscono il post-logout redirect URI nella richiesta di disconnessione e rimandano alla home page un accesso fallito senza mostrare il motivo:
```csharp
OnRedirectToIdentityProviderForSignOut = context =>
{
context.ProtocolMessage.PostLogoutRedirectUri = settings.PostLogoutRedirectUri;
return Task.CompletedTask;
},
OnRemoteFailure = context =>
{
// Do not show the reason in the browser; the logs have it.
context.Response.Redirect("/?error=signin");
context.HandleResponse();
return Task.CompletedTask;
},
```
## 5. Accedi, proteggi una pagina e disconnettiti
`/login` avvia l'accesso e poi torna alla dashboard, un percorso locale fisso:
```csharp
public class LoginModel : PageModel
{
/// Starts sign-in: redirects to KeenAuth, and back to the dashboard afterwards (a fixed local path).
public IActionResult OnGet() =>
Challenge(new AuthenticationProperties { RedirectUri = "/dashboard" }, OpenIdConnectDefaults.AuthenticationScheme);
}
```
La dashboard richiede una sessione: senza di essa, ASP.NET Core avvia l'accesso. La disconnessione è una `POST`, e Razor Pages verifica il token antiforgery. Termina la sessione qui, poi reindirizza a KeenAuth (OpenID Connect RP-Initiated Logout con `id_token_hint` e `post_logout_redirect_uri`):
```csharp
public class LogoutModel : PageModel
{
///
/// POST only, and Razor Pages checks the antiforgery token. Ends the session here, then redirects to KeenAuth
/// (OpenID Connect RP-Initiated Logout with id_token_hint and post_logout_redirect_uri).
///
public IActionResult OnPost() =>
SignOut(new AuthenticationProperties(), CookieAuthenticationDefaults.AuthenticationScheme,
OpenIdConnectDefaults.AuthenticationScheme);
}
```
La home page contiene il link per accedere e invia un form per disconnettersi; il tag helper del form aggiunge il token antiforgery:
```cshtml
@if (User.Identity?.IsAuthenticated == true)
{
Signed in as @Model.DisplayName.
Dashboard
}
else
{
Sign in
}
```
## 6. Chiama la tua API
La dashboard prende l'access token dalla sessione e chiama la tua API con esso. Il token resta sul server; il browser riceve solo l'HTML.
```csharp
/// Needs a session. The access token stays on the server; the browser receives only the HTML.
[Authorize]
public class DashboardModel(MessagesClient messages) : PageModel
{
public string DisplayName => User.Identity?.Name ?? User.FindFirst("sub")?.Value ?? "";
public int Status { get; private set; }
public string? Messages { get; private set; }
public async Task OnGetAsync()
{
var accessToken = await HttpContext.GetTokenAsync("access_token");
(Status, Messages) = await messages.FetchAsync(accessToken ?? "", HttpContext.RequestAborted);
}
}
```
```csharp
public async Task<(int Status, string? Body)> FetchAsync(string accessToken, CancellationToken cancel)
{
using var request = new HttpRequestMessage(HttpMethod.Get, "api/messages");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
try
{
using var response = await http.SendAsync(request, cancel);
return ((int)response.StatusCode, response.IsSuccessStatusCode ? await response.Content.ReadAsStringAsync(cancel) : null);
}
catch (HttpRequestException)
{
return (502, null);
}
}
```
L'esempio non ha un refresh token: quando l'access token scade, la tua API risponde `401` e la dashboard mostra quello stato. Accedi di nuovo.
## 7. Esegui l'app
Avvia l'API della guida rapida Express (o qualsiasi API che accetti i token) ed esegui l'app con le variabili esportate:
```sh
ASPNETCORE_URLS=http://localhost:8080 dotnet run --project App
```
Apri `http://localhost:8080`, scegli **Accedi**, accedi su KeenAuth e apri la dashboard.
## 8. Testa senza rete
I test non richiedono rete né un account KeenAuth. Un piccolo server Kestrel su una porta di loopback simula il tuo ambiente (discovery, un set di chiavi creato per l'esecuzione dei test, il token endpoint, le pushed authorization request, l'end-session endpoint) e la tua API. I test avviano l'app reale su un'altra porta e la pilotano con un client HTTP che non segue i redirect, come un browser che puoi leggere:
```csharp
[Fact]
public async Task APageWithoutASessionStartsSignInAndCallsNoApi()
{
using var response = await h.Get("/dashboard");
Assert.Equal(HttpStatusCode.Redirect, response.StatusCode);
Assert.StartsWith(h.Fake.Issuer + "/oauth2/authorize?", response.Headers.Location!.ToString());
Assert.Empty(h.Fake.To("/api/messages"));
}
```
```sh
dotnet restore Tests --locked-mode
python3 ../scripts/nuget_deps.py # licences and exact pins (--age: 7-day rule, network)
dotnet test Tests --no-restore
```
I test verificano che la configurazione sia validata all'avvio (e che nessun errore contenga un secret); che l'accesso invii PKCE S256, `state`, `nonce` e `resource`, e che il codice venga scambiato con il verifier corrispondente; che una pushed authorization request tenga i parametri fuori dal browser; che l'access token arrivi alla API nell'header `Authorization` e non finisca mai in un cookie o in una pagina; che uno state sconosciuto o riutilizzato, un `iss` errato o mancante, e un ID token non firmato, firmato con un'altra chiave, firmato con un HMAC che usa la chiave pubblica, oppure emesso per un'altra audience, un altro nonce o un altro issuer, oppure già scaduto, vengano rifiutati senza creare una sessione; che una pagina senza sessione avvii l'accesso; e che la disconnessione richieda il token antiforgery, vada all'end-session endpoint con `id_token_hint` e termini la sessione sul server.
L'accesso completo con un browser reale richiede un ambiente KeenAuth. Non fa parte dei test offline.
## Dietro un proxy o un load balancer
Imposta `APP_BASE_URL` sull'URL pubblico dell'app; il redirect URI viene costruito a partire da esso, non dall'header `Host`. Se un proxy termina TLS, aggiungi il middleware degli header forwarded solo quando il proxy è l'unico modo per raggiungere l'app, così i cookie di sessione ricevono il flag `Secure`.
## Limiti attuali
- L'accesso inizia con una `GET` a `/login`. La verifica di `state` e PKCE proteggono il callback.
- L'handler autentica il client con `client_secret_post`, non con `client_secret_basic`.
- L'app accetta ID token firmati con RS256, ES256 o PS256. KeenAuth può firmare anche con EdDSA; questo esempio non lo accetta, e EdDSA non è stato provato. Mantieni uno dei tre algoritmi per l'ambiente dell'applicazione web.
- Il ticket store e le chiavi che proteggono il token antiforgery e i cookie di state risiedono nella memoria di un singolo processo. Dopo un riavvio, le sessioni terminano e gli accessi in corso falliscono. Con più server, conserva i ticket in una cache condivisa e rendi persistenti le chiavi di ASP.NET Core Data Protection.
- Nessun refresh token e nessun accesso silenzioso.
## Prossimi passi
- [Proteggi un'API Express](/docs/quickstarts/express): l'API che questa app chiama.
- [Verifica dei token](/docs/sdk/token-verification): il verificatore sotto il middleware della tua API.