/.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;
```
Drei Events vervollständigen den Handler. Das erste fügt die Identifier Ihrer API als `resource` hinzu (RFC 8707); ohne sie ist das Access Token nicht für Ihre API bestimmt, und die API lehnt es ab. Das zweite prüft den Parameter `iss` der Autorisierungsantwort (RFC 9207): ASP.NET Core prüft ihn nicht, KeenAuth bietet ihn aber an.
```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.");
}
},
```
Das dritte lehnt ein ID Token ab, das nicht von einem Schlüssel Ihrer Umgebung signiert ist. ASP.NET Core überspringt die Signaturprüfung eines ID Tokens, das vom Token-Endpunkt kommt, was OpenID Connect Core über TLS erlaubt; diese App prüft es trotzdem.
```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.");
}
},
```
Die letzten beiden Events setzen die Post-Logout-Redirect-URI in die Abmeldeanfrage und schicken eine fehlgeschlagene Anmeldung zur Startseite zurück, ohne den Grund anzuzeigen:
```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. Anmelden, Seite schützen und abmelden
`/login` startet die Anmeldung und kehrt danach zum Dashboard zurück, einem festen lokalen Pfad:
```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);
}
```
Das Dashboard erfordert eine Sitzung: Ohne eine startet ASP.NET Core die Anmeldung. Abmelden ist ein `POST`, und Razor Pages prüft das Antiforgery-Token. Es beendet die Sitzung hier und leitet dann zu KeenAuth weiter (OpenID Connect RP-Initiated Logout mit `id_token_hint` und `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);
}
```
Die Startseite verlinkt zur Anmeldung und sendet das Formular zum Abmelden; der Form-Tag-Helper fügt das Antiforgery-Token hinzu:
```cshtml
@if (User.Identity?.IsAuthenticated == true)
{
Signed in as @Model.DisplayName.
Dashboard
}
else
{
Sign in
}
```
## 6. Ihre API aufrufen
Das Dashboard nimmt das Access Token aus der Sitzung und ruft damit Ihre API auf. Das Token bleibt auf dem Server; der Browser erhält nur das 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);
}
}
```
Das Beispiel hat kein Refresh Token: Läuft das Access Token ab, antwortet Ihre API mit `401`, und das Dashboard zeigt diesen Status an. Melden Sie sich erneut an.
## 7. App starten
Starten Sie die API aus dem Express-Schnellstart (oder eine beliebige API, die die Tokens akzeptiert) und starten Sie die App mit exportierten Variablen:
```sh
ASPNETCORE_URLS=http://localhost:8080 dotnet run --project App
```
Öffnen Sie `http://localhost:8080`, wählen Sie **Sign in**, melden Sie sich bei KeenAuth an und öffnen Sie das Dashboard.
## 8. Ohne Netzwerk testen
Die Tests benötigen kein Netzwerk und kein KeenAuth-Konto. Ein kleiner Kestrel-Server auf einem Loopback-Port übernimmt die Rolle Ihrer Umgebung (Discovery, ein für den Testlauf erstellter Schlüsselsatz, der Token-Endpunkt, Pushed Authorization Requests, der End-Session-Endpunkt) und Ihrer API. Die Tests starten die echte App auf einem anderen Port und steuern sie mit einem HTTP-Client, der Weiterleitungen nicht folgt, wie ein Browser, den Sie auslesen können:
```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
```
Die Tests prüfen, dass die Konfiguration beim Start validiert wird (und dass kein Fehler ein Secret enthält); dass die Anmeldung PKCE S256, `state`, `nonce` und `resource` sendet und dass der Code mit dem passenden Verifier eingetauscht wird; dass eine Pushed Authorization Request die Parameter aus dem Browser heraushält; dass das Access Token im Header `Authorization` an die API geht und nie in ein Cookie oder eine Seite gelangt; dass ein unbekannter oder wiederverwendeter State, ein falscher oder fehlender `iss`, sowie ein ID Token, das unsigniert ist, mit einem anderen Schlüssel signiert wurde, mit einer HMAC signiert wurde, deren Schlüssel der öffentliche Schlüssel ist, oder für eine andere Audience, einen anderen Nonce oder Issuer ausgestellt oder bereits abgelaufen ist, ohne Sitzung abgelehnt werden; dass eine Seite ohne Sitzung die Anmeldung startet; und dass das Abmelden das Antiforgery-Token benötigt, zum End-Session-Endpunkt mit `id_token_hint` geht und die Sitzung auf dem Server beendet.
Die vollständige Anmeldung mit einem echten Browser benötigt eine KeenAuth-Umgebung. Sie ist nicht Teil der Offline-Tests.
## Hinter einem Proxy oder Load Balancer
Setzen Sie `APP_BASE_URL` auf die öffentliche URL der App; die Redirect-URI wird daraus gebildet, nicht aus dem Header `Host`. Beendet ein Proxy TLS, fügen Sie die Middleware für weitergeleitete Header nur hinzu, wenn der Proxy der einzige Weg zur App ist, damit die Session-Cookies das Flag `Secure` erhalten.
## Aktuelle Grenzen
- Die Anmeldung startet mit einem `GET` auf `/login`. Die Prüfung von `state` und PKCE schützt den Callback.
- Der Handler authentifiziert den Client mit `client_secret_post`, nicht mit `client_secret_basic`.
- Die App akzeptiert ID Tokens, die mit RS256, ES256 oder PS256 signiert sind. KeenAuth kann auch mit EdDSA signieren; dieses Beispiel akzeptiert das nicht, und EdDSA wurde nicht getestet. Behalten Sie für die Umgebung der Webanwendung einen der drei Algorithmen bei.
- Der Ticket-Speicher und die Schlüssel, die das Antiforgery-Token und die State-Cookies schützen, liegen im Speicher eines Prozesses. Nach einem Neustart enden Sitzungen, und laufende Anmeldungen schlagen fehl. Mit mehreren Servern halten Sie die Tickets in einem gemeinsamen Cache und speichern die ASP.NET-Core-Data-Protection-Schlüssel dauerhaft.
- Kein Refresh Token und keine stille Anmeldung.
## Nächste Schritte
- [Eine Express-API schützen](/docs/quickstarts/express): die API, die diese App aufruft.
- [Tokens prüfen](/docs/sdk/token-verification): der Verifier unter der Middleware Ihrer API.