/.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;
```
İşleyiciyi üç olay tamamlar. Birincisi API'nizin tanımlayıcısını `resource` (RFC 8707) olarak ekler; bu olmadan erişim token'ı API'niz için amaçlanmamış olur ve API bunu reddeder. İkincisi yetkilendirme yanıtının `iss` parametresini denetler (RFC 9207): ASP.NET Core bunu denetlemez, KeenAuth ise bunu duyurur.
```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.");
}
},
```
Üçüncü olay, ortamınızın bir anahtarıyla imzalanmamış bir ID token'ı reddeder. ASP.NET Core, token uç noktasından gelen bir ID token'ın imza denetimini atlar; OpenID Connect Core bunu TLS üzerinden izin verir. Bu uygulama yine de denetler.
```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.");
}
},
```
Son iki olay, çıkış isteğine çıkış sonrası yönlendirme URI'sini ekler ve başarısız bir girişi nedenini göstermeden ana sayfaya geri gönderir:
```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. Giriş yapın, bir sayfayı koruyun ve çıkış yapın
`/login` girişi başlatır ve sonrasında sabit bir yerel yol olan panele döner:
```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);
}
```
Panel bir oturum gerektirir: oturum yoksa ASP.NET Core girişi başlatır. Çıkış bir `POST` isteğidir ve Razor Pages antiforgery token'ını denetler. Oturumu burada sonlandırır, ardından KeenAuth'a yönlendirir (`id_token_hint` ve `post_logout_redirect_uri` ile OpenID Connect RP-Initiated Logout):
```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);
}
```
Ana sayfa girişe bağlanır ve çıkış için POST gönderir; form tag helper antiforgery token'ını ekler:
```cshtml
@if (User.Identity?.IsAuthenticated == true)
{
Signed in as @Model.DisplayName.
Dashboard
}
else
{
Sign in
}
```
## 6. API'nizi çağırın
Panel, erişim token'ını oturumdan alır ve API'nizi bu token ile çağırır. Token sunucuda kalır; tarayıcı yalnızca HTML alır.
```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);
}
}
```
Örnekte yenileme token'ı yoktur: erişim token'ının süresi dolduğunda API'niz `401` yanıtı verir ve panel bu durumu gösterir. Tekrar giriş yapın.
## 7. Uygulamayı çalıştırın
Hızlı başlangıçtaki Express API'sini (ya da bu token'ları kabul eden herhangi bir API'yi) başlatın ve uygulamayı değişkenler dışa aktarılmış halde çalıştırın:
```sh
ASPNETCORE_URLS=http://localhost:8080 dotnet run --project App
```
`http://localhost:8080` adresini açın, **Giriş yap** seçeneğini seçin, KeenAuth'ta giriş yapın ve paneli açın.
## 8. Ağ olmadan test edin
Testler ağ bağlantısı ve KeenAuth hesabı gerektirmez. Loopback bağlantı noktasındaki küçük bir Kestrel sunucusu ortamınızı (keşif, test çalıştırması için oluşturulmuş bir anahtar kümesi, token uç noktası, itilmiş yetkilendirme istekleri, oturumu sonlandırma uç noktası) ve API'nizi taklit eder. Testler gerçek uygulamayı başka bir bağlantı noktasında başlatır ve yönlendirmeleri takip etmeyen bir HTTP istemcisiyle sürer; bu istemci, okuyabildiğiniz bir tarayıcı gibidir:
```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
```
Testler şunları denetler: yapılandırmanın başlangıçta doğrulandığını ve hiçbir hatanın bir sır içermediğini; girişin PKCE S256, `state`, `nonce` ve `resource` gönderdiğini ve kodun eşleşen verifier ile değiştirildiğini; itilmiş bir yetkilendirme isteğinin parametreleri tarayıcıdan uzak tuttuğunu; erişim token'ının API'ye `Authorization` başlığıyla gittiğini ve hiçbir zaman bir çereze ya da sayfaya yazılmadığını; bilinmeyen ya da yeniden kullanılan bir state, hatalı ya da eksik bir `iss`, ve imzasız, başka bir anahtarla imzalanmış, genel anahtarla HMAC imzalanmış ya da başka bir hedef kitle, nonce veya issuer için verilmiş ya da süresi dolmuş bir ID token'ın oturum açılmadan reddedildiğini; oturumu olmayan bir sayfanın girişi başlattığını; ve çıkışın antiforgery token'ı gerektirdiğini, `id_token_hint` ile oturumu sonlandırma uç noktasına gittiğini ve oturumu sunucuda sonlandırdığını.
Gerçek bir tarayıcıyla tam giriş bir KeenAuth ortamı gerektirir. Bu, çevrimdışı testlerin bir parçası değildir.
## Proxy veya yük dengeleyicinin arkasında
`APP_BASE_URL` değerini uygulamanın herkese açık URL'sine ayarlayın; yönlendirme URI'si `Host` başlığından değil, bundan oluşturulur. Bir proxy TLS'yi sonlandırıyorsa, oturum çerezleri `Secure` bayrağını alsın diye iletilen başlıklar ara katmanını yalnızca uygulamaya ulaşmanın tek yolu proxy ise ekleyin.
## Bugünkü sınırlar
- Giriş, `/login` adresine bir `GET` isteğiyle başlar. Geri çağırmayı `state` denetimi ve PKCE korur.
- İşleyici istemciyi `client_secret_basic` ile değil, `client_secret_post` ile doğrular.
- Uygulama RS256, ES256 veya PS256 ile imzalanmış ID token'ları kabul eder. KeenAuth EdDSA ile de imzalayabilir; bu örnek bunu kabul etmez ve EdDSA denenmedi. Web uygulamasının ortamı için bu üç algoritmadan birini tutun.
- Bilet deposu ile CSRF token'ını ve state çerezlerini koruyan anahtarlar tek bir sürecin belleğinde durur. Yeniden başlatmadan sonra oturumlar sona erer ve devam eden girişler başarısız olur. Birden fazla sunucuda, biletleri paylaşılan bir önbellekte tutun ve ASP.NET Core Data Protection anahtarlarını kalıcı hale getirin.
- Yenileme token'ı yoktur ve sessiz oturum açma yoktur.
## Sonraki adımlar
- [Express API'sini koruyun](/docs/quickstarts/express): bu uygulamanın çağırdığı API.
- [Token doğrulama](/docs/sdk/token-verification): API'nizin ara katmanının altındaki doğrulayıcı.