diff --git a/.idea/dictionaries/project.xml b/.idea/dictionaries/project.xml new file mode 100644 index 000000000..a37f6ff4a --- /dev/null +++ b/.idea/dictionaries/project.xml @@ -0,0 +1,7 @@ + + + + backchannel + + + \ No newline at end of file diff --git a/README.md b/README.md index 22b5cb017..9591268e6 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,7 @@ WebStorm has Grazie as a built-in spell checker and grammar checker, and support * You can link to header anchors using the `#` symbol, for example `[multiple authentication methods](/identityserver/ui/federation.md#multiple-authentication-methods-for-users)`. * Link relevant text. Prefer `learn more about [improving the sign-in experience]` over `click [here] to learn more`. * Run `npm run linkchecker` to validate all links (note this will ignore links to GitHub because of rate limits in place). +* When a markdown link is long (75+ characters) or a link is repeated multiple times on a page, prefer moving the link to the bottom of the file and using markdown anchor syntax `[test.cs][repo-test-file]` ### Code Block Style @@ -74,19 +75,23 @@ WebStorm has Grazie as a built-in spell checker and grammar checker, and support * Make sure examples are runnable and complete. The goal is "Copy-paste from docs". Include namespaces, a result, and other prerequisites that are not obvious to someone new to the code. * Inline comments can be used to explain essential parts of the code. Expressive code can highlight line numbers, show diffs, and more. * Mention NuGet packages as a `bash` code block showing how to install it (`dotnet add package ...`). Link to the NuGet Gallery. +* When referencing a property, field, class, or other symbol in text, use the `test` format instead of *test*. +* Values should also be back-ticked, especially HTTP Status codes like `404` or `401`. +* Make sure code blocks start at the very first character space and don't have excessive starting padding. ### Frontmatter Rules * Always have a `title` property to set the page title. -* Always have a `description` property to set the page description. +* Always have a `description` property to set the page description. This is a summary of the page's core content. * Always have a `date` property to set the creation/significant update date for a page. Use the `YYYY-MM-DD` format. -* Add the `sidebar` property and include the `label`. The `label` is used in the menu, and should typically be shorter than the more descriptive `title`. For example: +* Add the `sidebar` property and must include the `label` and `order`. The `label` is used in the menu, and should typically be shorter than the more descriptive `title`. For example: + ```yaml title: "Using IdentityServer As A Federation Gateway" sidebar: label: "Federation" + order: 1 ``` -* In the `sidebar` property, use `order` to re-order entries in the navigation bar. ## 🧞 Commands diff --git a/src/content/docs/accesstokenmanagement/advanced/client-assertions.md b/src/content/docs/accesstokenmanagement/advanced/client-assertions.md index 5fca10a48..42eef2aa1 100644 --- a/src/content/docs/accesstokenmanagement/advanced/client-assertions.md +++ b/src/content/docs/accesstokenmanagement/advanced/client-assertions.md @@ -2,6 +2,7 @@ title: Client Assertions description: Learn how to use client assertions instead of shared secrets for token client authentication in Duende.AccessTokenManagement. sidebar: + label: Client Assertions order: 30 redirect_from: - /foss/accesstokenmanagement/advanced/client_assertions/ @@ -14,34 +15,36 @@ If your token client is using a client assertion instead of a shared secret, you Here's a sample client assertion service using the Microsoft JWT library: -```cs -public class ClientAssertionService : IClientAssertionService -{ - private readonly IOptionsSnapshot _options; - - public ClientAssertionService(IOptionsSnapshot options) - { - _options = options; - } +```csharp +// ClientAssertionService.cs +using Duende.AccessTokenManagement; +using Duende.IdentityModel; +using Duende.IdentityModel.Client; +using Microsoft.Extensions.Options; +using Microsoft.IdentityModel.JsonWebTokens; +using Microsoft.IdentityModel.Tokens; +public class ClientAssertionService(IOptionsSnapshot options) + : IClientAssertionService +{ public Task GetClientAssertionAsync( string? clientName = null, TokenRequestParameters? parameters = null) { if (clientName == "invoice") { - var options = _options.Get(clientName); + var options1 = options.Get(clientName); var descriptor = new SecurityTokenDescriptor { - Issuer = options.ClientId, - Audience = options.TokenEndpoint, + Issuer = options1.ClientId, + Audience = options1.TokenEndpoint, Expires = DateTime.UtcNow.AddMinutes(1), SigningCredentials = GetSigningCredential(), Claims = new Dictionary { { JwtClaimTypes.JwtId, Guid.NewGuid().ToString() }, - { JwtClaimTypes.Subject, options.ClientId! }, + { JwtClaimTypes.Subject, options1.ClientId! }, { JwtClaimTypes.IssuedAt, DateTime.UtcNow.ToEpochTime() } }, @@ -63,6 +66,11 @@ public class ClientAssertionService : IClientAssertionService return Task.FromResult(null); } + + private SigningCredentials GetSigningCredential() + { + throw new NotImplementedException(); + } } ``` diff --git a/src/content/docs/accesstokenmanagement/advanced/client-credentials.md b/src/content/docs/accesstokenmanagement/advanced/client-credentials.md index fd83ca1f8..32cdde532 100644 --- a/src/content/docs/accesstokenmanagement/advanced/client-credentials.md +++ b/src/content/docs/accesstokenmanagement/advanced/client-credentials.md @@ -8,13 +8,14 @@ redirect_from: - /foss/accesstokenmanagement/advanced/client_credentials/ --- -The most common way to use the access token management for machine to machine communication is described [here](/accesstokenmanagement/workers) - however you may want to customize certain aspects of it - here's what you can do. +The most common way to use the access token management for [machine-to-machine communication](/accesstokenmanagement/workers) - however, you may want to customize certain aspects of it. Here's what you can do. -## Client options +## Client Options You can add token client definitions to your host while configuring the ASP.NET Core service provider, e.g.: -```cs +```csharp +// Program.cs services.AddClientCredentialsTokenManagement() .AddClient("invoices", client => { @@ -40,7 +41,8 @@ You can set the following options: Internally the standard .NET options system is used to register the configuration. This means you can also register clients like this: -```cs +```csharp +// Program.cs services.Configure("invoices", client => { client.TokenEndpoint = "https://sts.company.com/connect/token"; @@ -55,37 +57,43 @@ services.Configure("invoices", client => Or use the `IConfigureNamedOptions` if you need access to the ASP.NET Core service provider during registration, e.g.: -```cs -public class ClientCredentialsClientConfigureOptions : IConfigureNamedOptions -{ - private readonly DiscoveryCache _cache; +```csharp +// ClientCredentialsClientConfigureOptions.cs +using Duende.AccessTokenManagement; +using Duende.IdentityModel.Client; +using Microsoft.Extensions.Options; - public ClientCredentialsClientConfigureOptions(DiscoveryCache cache) - { - _cache = cache; - } - - public void Configure(string name, ClientCredentialsClient options) +public class ClientCredentialsClientConfigureOptions(DiscoveryCache cache) + : IConfigureNamedOptions +{ + public void Configure(string? name, ClientCredentialsClient options) { if (name == "invoices") { - var disco = _cache.GetAsync().GetAwaiter().GetResult(); + var disco = cache.GetAsync().GetAwaiter().GetResult(); options.TokenEndpoint = disco.TokenEndpoint; - client.ClientId = "4a632e2e-0466-4e5a-a094-0455c6105f57"; - client.ClientSecret = "e8ae294a-d5f3-4907-88fa-c83b3546b70c"; + options.ClientId = "4a632e2e-0466-4e5a-a094-0455c6105f57"; + options.ClientSecret = "e8ae294a-d5f3-4907-88fa-c83b3546b70c"; - client.Scope = "list"; - client.Resource = "urn:invoices"; + options.Scope = "list"; + options.Resource = "urn:invoices"; } } + + public void Configure(ClientCredentialsClient options) + { + // implement default configure + Configure("", options); + } } ``` You will also need to register the config options, for example: -```cs +```csharp +// Program.cs services.AddClientCredentialsTokenManagement(); services.AddSingleton(new DiscoveryCache("https://sts.company.com")); @@ -93,7 +101,7 @@ services.AddSingleton, ClientCredentialsClientConfigureOptions>(); ``` -### Backchannel communication +### Backchannel Communication By default, all backchannel communication will be done using a named client from the HTTP client factory. The name is `Duende.AccessTokenManagement.BackChannelHttpClient` which is also a constant called `ClientCredentialsTokenManagementDefaults.BackChannelHttpClientName`. @@ -111,6 +119,7 @@ By default, tokens will be cached using the `IDistributedCache` abstraction in A For development purposes, you can use the `MemoryDistributedCache`: ```cs +// Program.cs services.AddDistributedMemoryCache(); ``` @@ -122,6 +131,7 @@ For production deployments, we recommend using a [distributed cache](https://lea The built-in cache in `Duende.AccessTokenManagment` uses two settings from the options, which apply with any `IDistributedCache`: ```cs +// Program.cs services.AddClientCredentialsTokenManagement(options => { options.CacheLifetimeBuffer = 60; diff --git a/src/content/docs/accesstokenmanagement/advanced/dpop.md b/src/content/docs/accesstokenmanagement/advanced/dpop.md index 0e12b67c2..171e4374f 100644 --- a/src/content/docs/accesstokenmanagement/advanced/dpop.md +++ b/src/content/docs/accesstokenmanagement/advanced/dpop.md @@ -1,7 +1,8 @@ --- -title: DPoP -description: DPoP (Demonstrating Proof-of-Possession) is a security mechanism that binds access tokens to specific cryptographic keys to prevent token theft and misuse. +title: Demonstrating Proof-of-Possession (DPoP) +description: Demonstrating Proof-of-Possession is a security mechanism that binds access tokens to specific cryptographic keys to prevent token theft and misuse. sidebar: + label: DPoP order: 40 redirect_from: - /foss/accesstokenmanagement/advanced/dpop/ @@ -19,11 +20,18 @@ The creation and management of this DPoP key is up to the policy of the client. Creating a JWK in .NET is simple: -```cs +```csharp +// Program.cs +using System.Security.Cryptography; +using System.Text.Json; +using Microsoft.IdentityModel.Tokens; + var rsaKey = new RsaSecurityKey(RSA.Create(2048)); var jwkKey = JsonWebKeyConverter.ConvertFromSecurityKey(rsaKey); jwkKey.Alg = "PS256"; var jwk = JsonSerializer.Serialize(jwkKey); + +Console.WriteLine(jwk); ``` ## Key Configuration @@ -36,6 +44,7 @@ Once you have a JWK you wish to use, then it must be configured or made availabl Here's a sample configuring the key in an application using `AddOpenIdConnectAccessTokenManagement` in the startup code: ```cs +// Program.cs services.AddOpenIdConnectAccessTokenManagement(options => { options.DPoPJsonWebKey = jwk; @@ -45,6 +54,7 @@ services.AddOpenIdConnectAccessTokenManagement(options => Similarly, for an application using `AddClientCredentialsTokenManagement`, it would look like this: ```cs +// Program.cs services.AddClientCredentialsTokenManagement() .AddClient("client_name", options => { @@ -61,7 +71,7 @@ There is nothing explicit needed on behalf of the developer using this library. When using DPoP and `AddOpenIdConnectAccessTokenManagement`, this library will also automatically include the `dpop_jkt` parameter to the authorize endpoint. -## Proof Tokens at the API +## Proof Tokens At The API Once the library has obtained a DPoP bound access token for the client, then if your application is using any of the `HttpClient` client factory helpers (e.g. `AddClientCredentialsHttpClient` or `AddUserAccessTokenHttpClient`) then those outbound HTTP requests will automatically include a DPoP proof token for the associated DPoP access token. diff --git a/src/content/docs/accesstokenmanagement/advanced/user-tokens.md b/src/content/docs/accesstokenmanagement/advanced/user-tokens.md index 58e304b5b..0edca3124 100644 --- a/src/content/docs/accesstokenmanagement/advanced/user-tokens.md +++ b/src/content/docs/accesstokenmanagement/advanced/user-tokens.md @@ -8,19 +8,28 @@ redirect_from: - /foss/accesstokenmanagement/advanced/user_tokens/ --- -The most common way to use the access token management for interactive web applications is described [here](/accesstokenmanagement/web-apps/) - however you may want to customise certain aspects of it - here's what you can do. +The most common way +to use [access token management is for interactive web applications](/accesstokenmanagement/web-apps.md) - +however, you may want to customize certain aspects of it. Here's what you can do. -## General options +## General Options You can pass in some global options when registering token management in the ASP.NET Core service provider. -* `ChallengeScheme` - by default the OIDC configuration is inferred from the default challenge scheme. This is recommended approach. If for some reason your OIDC handler is not the default challenge scheme, you can set the scheme name on the options -* `UseChallengeSchemeScopedTokens` - the general assumption is that you only have one OIDC handler configured. If that is not the case, token management needs to maintain multiple sets of token artefacts simultaneously. You can opt in to that feature using this setting. -* `ClientCredentialsScope` - when requesting client credentials tokens from the OIDC provider, the scope parameter will not be set since its value cannot be inferred from the OIDC configuration. With this setting you can set the value of the scope parameter. +* `ChallengeScheme` - by default the OIDC configuration is inferred from the default challenge scheme. This is + recommended approach. If for some reason your OIDC handler is not the default challenge scheme, you can set the scheme + name on the options +* `UseChallengeSchemeScopedTokens` - the general assumption is that you only have one OIDC handler configured. If that + is not the case, token management needs to maintain multiple sets of token artefacts simultaneously. You can opt in to + that feature using this setting. +* `ClientCredentialsScope` - when requesting client credentials tokens from the OIDC provider, the scope parameter will + not be set since its value cannot be inferred from the OIDC configuration. With this setting you can set the value of + the scope parameter. * `ClientCredentialsResource` - same as previous, but for the resource parameter * `ClientCredentialStyle` - specifies how client credentials are transmitted to the OIDC provider -```cs +```csharp +// Program.cs builder.Services.AddOpenIdConnectAccessTokenManagement(options => { options.ChallengeScheme = "schmeName"; @@ -34,7 +43,7 @@ builder.Services.AddOpenIdConnectAccessTokenManagement(options => ## Per Request Parameters -You can also modify token management parameters on a per-request basis. +You can also modify token management parameters on a per-request basis. The `UserTokenRequestParameters` class can be used for that: @@ -47,20 +56,21 @@ The `UserTokenRequestParameters` class can be used for that: The request parameters can be passed via the manual API: -```cs +```csharp var token = await _tokenManagementService.GetAccessTokenAsync(User, new UserAccessTokenRequestParameters { ... }); ``` ...the extension methods -```cs +```csharp var token = await HttpContext.GetUserAccessTokenAsync( new UserTokenRequestParameters { ... }); ``` ...or the HTTP client factory -```cs +```csharp +// Program.cs // registers HTTP client that uses the managed user access token builder.Services.AddUserAccessTokenHttpClient("invoices", parameters: new UserTokenRequestParameters { ... }, @@ -77,9 +87,10 @@ builder.Services.AddHttpClient(client => .AddUserAccessTokenHandler(new UserTokenRequestParameters { ... }); ``` -## Token storage +## Token Storage -By default, the user's access and refresh token will be store in the ASP.NET Core authentication session (implemented by the cookie handler). +By default, the user's access and refresh token will be store in the ASP.NET Core authentication session (implemented by +the cookie handler). You can modify this in two ways diff --git a/src/content/docs/accesstokenmanagement/blazor-server.md b/src/content/docs/accesstokenmanagement/blazor-server.md index ef317d9e1..31c791371 100644 --- a/src/content/docs/accesstokenmanagement/blazor-server.md +++ b/src/content/docs/accesstokenmanagement/blazor-server.md @@ -1,13 +1,15 @@ --- -title: Blazor Server +title: Blazor Server Access Token Management +date: 2024-10-12 description: Learn how to manage access tokens in Blazor Server applications and handle token storage and HTTP client usage with Duende.AccessTokenManagement. sidebar: + label: Blazor order: 4 redirect_from: - /foss/accesstokenmanagement/blazor_server/ --- -Blazor Server applications have the same token management requirements as a regular ASP.NET Core web application. Because Blazor Server streams content to the application over a websocket, there often is no HTTP request or response to interact with during the execution of a Blazor Server application. You therefore cannot use *HttpContext* in a Blazor Server application as you would in a traditional ASP.NET Core web application. +Blazor Server applications have the same token management requirements as a regular ASP.NET Core web application. Because Blazor Server streams content to the application over a websocket, there often is no HTTP request or response to interact with during the execution of a Blazor Server application. You therefore cannot use `HttpContext` in a Blazor Server application as you would in a traditional ASP.NET Core web application. This means: @@ -15,7 +17,7 @@ This means: * you cannot use the ASP.NET authentication session to store tokens * the normal mechanism used to automatically attach tokens to Http Clients making API calls won't work -Fortunately, Duende.AccessTokenManagement provides a straightforward solution to these problems. Also see the [*BlazorServer* sample](https://github.com/DuendeSoftware/foss/tree/main/access-token-management/samples/BlazorServer) for source code of a full example. +Fortunately, `Duende.AccessTokenManagement` provides a straightforward solution to these problems. Also see the [*BlazorServer* sample](https://github.com/DuendeSoftware/foss/tree/main/access-token-management/samples/BlazorServer) for source code of a full example. ## Token storage @@ -25,14 +27,16 @@ The store interface is straightforward. `StoreTokenAsync` adds a token to the st Register your token store in the ASP.NET Core service provider and tell Duende.AccessTokenManagement to integrate with Blazor by calling `AddBlazorServerAccessTokenManagement`: -```cs +```csharp +// Program.cs builder.Services.AddOpenIdConnectAccessTokenManagement() .AddBlazorServerAccessTokenManagement(); ``` Once you've registered your token store, you need to use it. You initialize the token store with the `TokenValidated` event in the OpenID Connect handler: -```cs +```csharp +// OidcEvents.cs public class OidcEvents : OpenIdConnectEvents { private readonly IUserTokenStore _store; @@ -60,13 +64,14 @@ public class OidcEvents : OpenIdConnectEvents } ``` -Once registered and initialized, Duende.AccessTokenManagement will keep the store up to date automatically as tokens are refreshed. +Once registered and initialized, `Duende.AccessTokenManagement` will keep the store up to date automatically as tokens are refreshed. ## Retrieving And Using Tokens If you've registered your token store with `AddBlazorServerAccessTokenManagement`, Duende.AccessTokenManagement will register the services necessary to attach tokens to outgoing HTTP requests automatically, using the same API as a non-blazor application. You inject an HTTP client factory and resolve named HTTP clients where ever you need to make HTTP requests, and you register the HTTP client's that use access tokens in the ASP.NET Core service provider with our extension method: ```cs +// Program.cs builder.Services.AddUserAccessTokenHttpClient("demoApiClient", configureClient: client => { client.BaseAddress = new Uri("https://demo.duendesoftware.com/api/"); diff --git a/src/content/docs/accesstokenmanagement/index.mdx b/src/content/docs/accesstokenmanagement/index.mdx index 94b49ccf8..a71cfd903 100644 --- a/src/content/docs/accesstokenmanagement/index.mdx +++ b/src/content/docs/accesstokenmanagement/index.mdx @@ -16,6 +16,12 @@ The `Duende.AccessTokenManagement` library provides automatic access token manag - automatic access token lifetime management using a refresh token for API calls on-behalf of the currently logged-in user - revocation of access tokens +To get started, install the NuGet Package: + +```bash +dotnet add package Duende.AccessTokenManagement +``` + { @@ -74,14 +88,16 @@ builder.Services.AddAuthentication(options => // adds services for token management builder.Services.AddOpenIdConnectAccessTokenManagement(); - ``` ### HTTP Client Factory -Similar to the worker service support, you can register HTTP clients that automatically send the access token of the current user when making API calls. The message handler plumbing associated with those HTTP clients will try to make sure, the access token is always valid and not expired. +Similar to the worker service support, you can register HTTP clients that automatically send the access token of the +current user when making API calls. The message handler plumbing associated with those HTTP clients will try to make +sure, the access token is always valid and not expired. -```cs +```csharp +// Program.cs // registers HTTP client that uses the managed user access token builder.Services.AddUserAccessTokenHttpClient("invoices", configureClient: client => { client.BaseAddress = new Uri("https://api.company.com/invoices/"); }); @@ -89,7 +105,8 @@ builder.Services.AddUserAccessTokenHttpClient("invoices", This could be also a typed client: -```cs +```csharp +// Program.cs // registers a typed HTTP client with token management support builder.Services.AddHttpClient(client => { @@ -98,9 +115,11 @@ builder.Services.AddHttpClient(client => .AddUserAccessTokenHandler(); ``` -Of course, the ASP.NET Core web application host could also do machine to machine API calls that are independent of a user. In this case all the token client configuration can be inferred from the OpenID Connect handler configuration. The following registers an HTTP client that uses a client credentials token for outgoing calls: +Of course, the ASP.NET Core web application host could also do machine to machine API calls that are independent of a +user. In this case all the token client configuration can be inferred from the OpenID Connect handler configuration. The +following registers an HTTP client that uses a client credentials token for outgoing calls: -```cs +```csharp // registers HTTP client that uses the managed client access token builder.Services.AddClientAccessTokenHttpClient("masterdata.client", configureClient: client => { client.BaseAddress = new Uri("https://api.company.com/masterdata/"); }); @@ -108,7 +127,8 @@ builder.Services.AddClientAccessTokenHttpClient("masterdata.client", As a typed client: -```cs +```csharp +// Program.cs builder.Services.AddHttpClient(client => { client.BaseAddress = new Uri("https://api.company.com/masterdata/"); @@ -120,7 +140,7 @@ builder.Services.AddHttpClient(client => There are three ways to interact with the token management service: -* manually +* Manually * HTTP context extension methods * HTTP client factory @@ -128,7 +148,7 @@ There are three ways to interact with the token management service: You can get the current user and client access token manually by writing code against the `IUserTokenManagementService`. -```cs +```csharp public class HomeController : Controller { private readonly IHttpClientFactory _httpClientFactory; @@ -157,11 +177,13 @@ public class HomeController : Controller There are three extension methods on the HTTP context that simplify interaction with the token management service: -* `GetUserAccessTokenAsync` - returns an access token representing the user. If the current access token is expired, it will be refreshed. -* `GetClientAccessTokenAsync` - returns an access token representing the client. If the current access token is expired, a new one will be requested +* `GetUserAccessTokenAsync` - returns an access token representing the user. If the current access token is expired, it + will be refreshed. +* `GetClientAccessTokenAsync` - returns an access token representing the client. If the current access token is expired, + a new one will be requested * `RevokeRefreshTokenAsync` - revokes the refresh token -```cs +```csharp public async Task CallApi() { var token = await HttpContext.GetUserAccessTokenAsync(); @@ -176,9 +198,11 @@ public async Task CallApi() ### HTTP Client Factory -Last but not least, if you registered clients with the factory, you can use them. They will try to make sure that a current access token is always sent along. If that is not possible, ultimately a 401 will be returned to the calling code. +Last but not least, if you registered clients with the factory, you can use them. They will try to make sure that a +current access token is always sent along. If that is not possible, ultimately a 401 will be returned to the calling +code. -```cs +```csharp public async Task CallApi() { var client = _httpClientFactory.CreateClient("invoices"); @@ -191,7 +215,7 @@ public async Task CallApi() ...or for a typed client: -```cs +```csharp public async Task CallApi([FromServices] InvoiceClient client) { var response = await client.GetList(); diff --git a/src/content/docs/accesstokenmanagement/workers.md b/src/content/docs/accesstokenmanagement/workers.md index eb6609eb5..954ebb679 100644 --- a/src/content/docs/accesstokenmanagement/workers.md +++ b/src/content/docs/accesstokenmanagement/workers.md @@ -1,7 +1,9 @@ --- -title: Workers +title: Service Workers and Background Tasks +date: 2024-10-12 description: Learn how to manage OAuth access tokens in worker applications and background tasks using Duende.AccessTokenManagement sidebar: + label: Service Workers order: 2 redirect_from: - /foss/accesstokenmanagement/workers/ @@ -13,15 +15,20 @@ The access tokens need to be requested and cached (either locally or shared betw The actual business code should not need to be aware of this. -Have a look for the `Worker` project in the [samples folder](https://github.com/DuendeSoftware/foss/tree/main/access-token-management/samples/) for running code. +Have a look for the [`Worker` project in the samples folder](https://github.com/DuendeSoftware/foss/tree/main/access-token-management/samples/) for running code. ## Setup Start by adding a reference to the `Duende.AccessTokenManagement` NuGet package to your application. +```bash +dotnet add package Duende.AccessTokenManagement +``` + You can add the necessary services to the ASP.NET Core service provider by calling `AddClientCredentialsTokenManagement()`. After that you can add one or more named client definitions by calling `AddClient`. -```cs +```csharp +// Program.cs // default cache services.AddDistributedMemoryCache(); @@ -52,7 +59,8 @@ You can register HTTP clients with the factory that will automatically use the a The following code registers an HTTP client called `invoices` to automatically use the `invoice.client` definition: -```cs +```csharp +// Program.cs services.AddClientCredentialsHttpClient("invoices", "invoice.client", client => { client.BaseAddress = new Uri("https://apis.company.com/invoice/"); @@ -61,7 +69,8 @@ services.AddClientCredentialsHttpClient("invoices", "invoice.client", client => You can also set up a typed HTTP client to use a token client definition, e.g.: -```cs +```csharp +// Program.cs services.AddHttpClient(client => { client.BaseAddress = new Uri("https://apis.company.com/catalog/"); @@ -77,7 +86,8 @@ There are two fundamental ways to interact with token management - manually, or You can retrieve the current access token for a given token client via `IClientCredentialsTokenManagementService.GetAccessTokenAsync`. -```cs +```csharp +// WorkerManual.cs public class WorkerManual : BackgroundService { private readonly IHttpClientFactory _clientFactory; @@ -114,7 +124,8 @@ You can customize some of the per-request parameters by passing in an instance o If you have set up HTTP clients in the HTTP factory, then no token related code is needed at all, e.g.: -```cs +```csharp +// WorkerHttpClient.cs public class WorkerHttpClient : BackgroundService { private readonly ILogger _logger; @@ -139,4 +150,4 @@ public class WorkerHttpClient : BackgroundService } ``` -**remark** The clients in the factory have a message handler attached to them that automatically re-tries the request in case of a 401 response code. The request get re-sent with a newly requested access token. If this still results in a 401, the response is returned to the caller. \ No newline at end of file +**remark** The clients in the factory have a message handler attached to them that automatically re-tries the request in case of a `401` response code. The request get re-sent with a newly requested access token. If this still results in a `401`, the response is returned to the caller. \ No newline at end of file diff --git a/src/content/docs/identitymodel-oidcclient/manual.md b/src/content/docs/identitymodel-oidcclient/manual.md index 6c999d46a..925a92230 100644 --- a/src/content/docs/identitymodel-oidcclient/manual.md +++ b/src/content/docs/identitymodel-oidcclient/manual.md @@ -45,4 +45,6 @@ var result = await client.ProcessResponseAsync(data, state); ``` When using this manual mode, and processing the response, the `ProcessResponseAsync` method will return a -[`LoginResult`](https://github.com/DuendeSoftware/foss/blob/19370c6d4820a684d41d1d40b8192ee8b873b8f0/identity-model-oidc-client/src/IdentityModel.OidcClient/LoginResult.cs) which will contain a `ClaimsPrincipal` with the user's claims along with the `IdentityToken` and `AccessToken`. +[`LoginResult`][login-result-cs] which will contain a `ClaimsPrincipal` with the user's claims along with the `IdentityToken` and `AccessToken`. + +[login-result-cs]: https://github.com/DuendeSoftware/foss/blob/19370c6d4820a684d41d1d40b8192ee8b873b8f0/identity-model-oidc-client/src/IdentityModel.OidcClient/LoginResult.cs \ No newline at end of file diff --git a/src/content/docs/identitymodel/utils/base64.md b/src/content/docs/identitymodel/utils/base64.md index 5b29f6ae4..67ac704ee 100644 --- a/src/content/docs/identitymodel/utils/base64.md +++ b/src/content/docs/identitymodel/utils/base64.md @@ -1,7 +1,9 @@ --- title: Base64 URL Encoding +date: 2024-04-17 description: Documentation for Base64 URL encoding and decoding utilities in IdentityModel, used for JWT token serialization sidebar: + label: Base64 URL Encoding order: 2 redirect_from: - /foss/identitymodel/utils/base64/ @@ -9,12 +11,13 @@ redirect_from: :::note ASP.NET Core has built-in support for Base64 encoding and decoding via -[WebEncoders.Base64UrlEncode](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.webutilities.webencoders.base64urlencode) -and -[WebEncoders.Base64UrlDecode](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.webutilities.webencoders.base64urldecode). +[WebEncoders.Base64UrlEncode][ms-b64-encode] and [WebEncoders.Base64UrlDecode][ms-b64-decode]. ::: -JWT serialization involves transforming the three core components of a JWT (Header, Payload, Signature) into a single, compact, URL-safe string. [Base64 URL encoding](https://tools.ietf.org/html/rfc4648#section-5) is used instead of standard Base64 because it doesn't include characters like `+`, `/`, or `=`, making it safe to use directly in URLs and HTTP headers without requiring further encoding. +JWT serialization involves transforming the three core components of a JWT (Header, Payload, Signature) into a single, +compact, URL-safe string. [Base64 URL encoding](https://tools.ietf.org/html/rfc4648#section-5) is used instead of +standard Base64 because it doesn't include characters like `+`, `/`, or `=`, making it safe to use directly in URLs and +HTTP headers without requiring further encoding. ## WebEncoders Encode and Decode @@ -41,7 +44,7 @@ Console.WriteLine(text); ## IdentityModel's Base64Url -IdentityModel includes the *Base64Url* class to help with +IdentityModel includes the `Base64Url` class to help with encoding/decoding: ```csharp @@ -56,3 +59,7 @@ bytes = Base64Url.Decode(b64url); var text = Encoding.UTF8.GetString(bytes); Console.WriteLine(text); ``` + +[ms-b64-encode]: https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.webutilities.webencoders.base64urlencode + +[ms-b64-decode]: https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.webutilities.webencoders.base64urldecode diff --git a/src/content/docs/identitymodel/utils/epoch-time.md b/src/content/docs/identitymodel/utils/epoch-time.md index b3eecd95b..9ca83e433 100644 --- a/src/content/docs/identitymodel/utils/epoch-time.md +++ b/src/content/docs/identitymodel/utils/epoch-time.md @@ -1,7 +1,9 @@ --- title: Epoch Time Conversion +date: 2024-04-17 description: Learn about converting between DateTime and Unix/Epoch time formats in IdentityModel for JWT tokens sidebar: + label: "Epoch Time" order: 3 redirect_from: - /foss/identitymodel/utils/epoch_time/ @@ -15,15 +17,16 @@ and [DateTimeOffset.ToUnixTimeSeconds](https://docs.microsoft.com/en-us/dotnet/api/system.datetimeoffset.tounixtimeseconds). ::: -JWT tokens use so-called [Epoch or Unix -time](https://en.wikipedia.org/wiki/Unix_time) to represent date/times. +JSON Web Token (JWT) tokens use so-called [Epoch or Unix time](https://en.wikipedia.org/wiki/Unix_time) to represent +date/times, which is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT). ## DateTimeOffset To Epoch Time -In .NET you can convert `DateTimeOffset` to Unix time via the two methods -of `ToUnixTimeSeconds` and `ToUnixTimeMilliseconds`: +In .NET, you can convert `DateTimeOffset` to Unix time via the two methods of `ToUnixTimeSeconds` and +`ToUnixTimeMilliseconds`: ```csharp +// EpochTimeExamples.cs var seconds = DateTimeOffset.UtcNow.ToUnixTimeSeconds(); var milliseconds = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(); ``` @@ -34,11 +37,11 @@ IdentityModel contains extensions methods for `DateTime` to convert to/from Unix time: ```csharp +// DateTimeExtensionExample.cs var dt = DateTime.UtcNow; +// The time returned is in seconds var unix = dt.ToEpochTime(); ``` -The time returned is in seconds. - diff --git a/src/content/docs/identityserver/apis/aspnetcore/authorization.md b/src/content/docs/identityserver/apis/aspnetcore/authorization.md index 971e78567..470698191 100644 --- a/src/content/docs/identityserver/apis/aspnetcore/authorization.md +++ b/src/content/docs/identityserver/apis/aspnetcore/authorization.md @@ -3,6 +3,7 @@ title: "Authorization based on Scopes and Claims" description: "Guide for implementing authorization using scope claims and ASP.NET Core authorization policies with IdentityServer access tokens" date: 2020-09-10T08:22:12+02:00 sidebar: + label: Authorization order: 30 redirect_from: - /identityserver/v5/apis/aspnetcore/authorization/ diff --git a/src/content/docs/identityserver/apis/aspnetcore/confirmation.md b/src/content/docs/identityserver/apis/aspnetcore/confirmation.md index 6c8a0ff18..a4ecee35c 100644 --- a/src/content/docs/identityserver/apis/aspnetcore/confirmation.md +++ b/src/content/docs/identityserver/apis/aspnetcore/confirmation.md @@ -3,6 +3,7 @@ title: "Validating Proof-of-Possession" description: "Guide for validating Proof-of-Possession (PoP) access tokens in ASP.NET Core using mTLS or DPoP mechanisms" date: 2020-09-10T08:22:12+02:00 sidebar: + label: Validate PoP order: 40 redirect_from: - /identityserver/v5/apis/aspnetcore/confirmation/ diff --git a/src/content/docs/identityserver/apis/aspnetcore/jwt.md b/src/content/docs/identityserver/apis/aspnetcore/jwt.md index 810467c47..69c907d52 100644 --- a/src/content/docs/identityserver/apis/aspnetcore/jwt.md +++ b/src/content/docs/identityserver/apis/aspnetcore/jwt.md @@ -1,8 +1,9 @@ --- -title: "Using JWTs" +title: "Using JSON Web Tokens (JWTs)" description: "Guide for validating JWT bearer tokens in ASP.NET Core applications using the JWT authentication handler" date: 2020-09-10T08:22:12+02:00 sidebar: + label: JWTs order: 10 redirect_from: - /identityserver/v5/apis/aspnetcore/jwt/ @@ -12,7 +13,7 @@ redirect_from: On ASP.NET Core, you typically use the [JWT authentication handler](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.JwtBearer) for validating JWT bearer tokens. -## Validating A JWT token +## Validating A JWT First you need to add a reference to the authentication handler in your API project: @@ -47,7 +48,7 @@ In OAuth there are two complementary mechanisms to embed more information about If you designed your APIs around the concept of [API resources](/identityserver/fundamentals/resources/api-resources/), your IdentityServer will emit the `aud` claim by default (`api1` in this example): -```json +```text { "typ": "at+jwt", "kid": "123" diff --git a/src/content/docs/identityserver/apis/aspnetcore/reference.md b/src/content/docs/identityserver/apis/aspnetcore/reference.md index 72467a1aa..12b97aacb 100644 --- a/src/content/docs/identityserver/apis/aspnetcore/reference.md +++ b/src/content/docs/identityserver/apis/aspnetcore/reference.md @@ -1,8 +1,9 @@ --- -title: "Using Reference Tokens" +title: "Reference Tokens" description: "Guide for implementing reference token validation in ASP.NET Core APIs using OAuth 2.0 token introspection" date: 2020-09-10T08:22:12+02:00 sidebar: + label: Reference Tokens order: 20 redirect_from: - /identityserver/v5/apis/aspnetcore/reference/ diff --git a/src/content/docs/identityserver/data/ef.md b/src/content/docs/identityserver/data/ef.md index 3e2fdb38b..046beb9d8 100644 --- a/src/content/docs/identityserver/data/ef.md +++ b/src/content/docs/identityserver/data/ef.md @@ -1,7 +1,8 @@ --- -title: "Entity Framework Integration" +title: "Entity Framework Core Integration" description: "Documentation for using Entity Framework with IdentityServer to store configuration and operational data in any EF-supported database" sidebar: + label: EF Core order: 50 redirect_from: - /identityserver/v5/data/ef/ diff --git a/src/content/docs/identityserver/overview/specs.md b/src/content/docs/identityserver/overview/specs.md index 48f2b58d6..da5bbfb66 100644 --- a/src/content/docs/identityserver/overview/specs.md +++ b/src/content/docs/identityserver/overview/specs.md @@ -3,6 +3,7 @@ title: "Supported Specifications" description: "A comprehensive list of supported OpenID Connect and OAuth 2.x specifications implemented in Duende IdentityServer" date: 2020-09-10T08:22:12+02:00 sidebar: + label: Specifications order: 3 redirect_from: - /identityserver/v5/overview/specs/ diff --git a/src/content/docs/identityserver/quickstarts/1-client-credentials.md b/src/content/docs/identityserver/quickstarts/1-client-credentials.md index 1c241b870..1325e578d 100644 --- a/src/content/docs/identityserver/quickstarts/1-client-credentials.md +++ b/src/content/docs/identityserver/quickstarts/1-client-credentials.md @@ -380,9 +380,9 @@ endpoint addresses can be read from the metadata. Add the following to the client's Program.cs in the `src/Client/Program.cs` directory: ```cs -using IdentityModel.Client; +using Duende.IdentityModel.Client; -// discover endpoints from metadata +// discovery endpoints from metadata var client = new HttpClient(); var disco = await client.GetDiscoveryDocumentAsync("https://localhost:5001"); if (disco.IsError) diff --git a/src/content/docs/identityserver/reference/endpoints/authorize.md b/src/content/docs/identityserver/reference/endpoints/authorize.md index 14923a726..d320b3388 100644 --- a/src/content/docs/identityserver/reference/endpoints/authorize.md +++ b/src/content/docs/identityserver/reference/endpoints/authorize.md @@ -3,6 +3,7 @@ title: "Authorize Endpoint" description: "Documentation for the authorize endpoint which handles browser-based token and authorization code requests, including authentication and consent flows." date: 2020-09-10T08:22:12+02:00 sidebar: + label: Authorize order: 2 redirect_from: - /identityserver/v5/reference/endpoints/authorize/ diff --git a/src/content/docs/identityserver/reference/endpoints/ciba.md b/src/content/docs/identityserver/reference/endpoints/ciba.md index 5a2ac9957..9cff79581 100644 --- a/src/content/docs/identityserver/reference/endpoints/ciba.md +++ b/src/content/docs/identityserver/reference/endpoints/ciba.md @@ -2,6 +2,7 @@ title: "Backchannel Authentication Endpoint" description: "Documentation for the CIBA endpoint which allows clients to initiate backchannel authentication requests for users without browser interaction" sidebar: + label: Backchannel Authentication order: 9 redirect_from: - /identityserver/v5/reference/endpoints/ciba/ @@ -82,7 +83,7 @@ required to implement the `IBackchannelAuthenticationUserValidator` interface. instead of providing all parameters as individual parameters, you can provide all them as a JWT -```text +```http request POST /connect/ciba client_id=client1& @@ -93,7 +94,7 @@ POST /connect/ciba And a successful response will look something like: -```text +```http request HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store @@ -107,11 +108,11 @@ Cache-Control: no-store ## .NET Client Library -You can use the [Duende IdentityModel](../../../identitymodel) client library to programmatically interact with +You can use the [Duende IdentityModel](/identitymodel/index.mdx) client library to programmatically interact with the protocol endpoint from .NET code. ```cs -using IdentityModel.Client; +using Duende.IdentityModel.Client; var client = new HttpClient(); diff --git a/src/content/docs/identityserver/reference/endpoints/device-authorization.md b/src/content/docs/identityserver/reference/endpoints/device-authorization.md index 9f5c75756..3866ce3d8 100644 --- a/src/content/docs/identityserver/reference/endpoints/device-authorization.md +++ b/src/content/docs/identityserver/reference/endpoints/device-authorization.md @@ -3,6 +3,7 @@ title: "Device Authorization Endpoint" description: "Documentation for the device authorization endpoint which handles device flow authentication requests and issues device and user codes for authorization." date: 2020-09-10T08:22:12+02:00 sidebar: + label: Device Authorization order: 8 redirect_from: - /identityserver/v5/reference/endpoints/device_authorization/ @@ -35,11 +36,11 @@ POST /connect/deviceauthorization ## .NET Client Library -You can use the [Duende IdentityModel](../../../identitymodel) client library to programmatically interact with +You can use the [Duende IdentityModel](/identitymodel/index.mdx) client library to programmatically interact with the protocol endpoint from .NET code. ```cs -using IdentityModel.Client; +using Duende.IdentityModel.Client; var client = new HttpClient(); diff --git a/src/content/docs/identityserver/reference/endpoints/discovery.md b/src/content/docs/identityserver/reference/endpoints/discovery.md index dadf3c2e5..88f8190bf 100644 --- a/src/content/docs/identityserver/reference/endpoints/discovery.md +++ b/src/content/docs/identityserver/reference/endpoints/discovery.md @@ -3,6 +3,7 @@ title: "Discovery Endpoint" description: "Learn about the discovery endpoint that provides metadata about your IdentityServer configuration, including issuer name, key material, and supported scopes." date: 2020-09-10T08:22:12+02:00 sidebar: + label: Discovery order: 1 redirect_from: - /identityserver/v5/reference/endpoints/discovery/ diff --git a/src/content/docs/identityserver/reference/endpoints/end-session.md b/src/content/docs/identityserver/reference/endpoints/end-session.md index a4dbfbe73..b344d28ac 100644 --- a/src/content/docs/identityserver/reference/endpoints/end-session.md +++ b/src/content/docs/identityserver/reference/endpoints/end-session.md @@ -3,6 +3,7 @@ title: "End Session Endpoint" description: "The end session endpoint enables single sign-out functionality in OpenID Connect, allowing users to terminate their sessions across multiple client applications." date: 2020-09-10T08:22:12+02:00 sidebar: + label: End Session order: 7 redirect_from: - /identityserver/v5/reference/endpoints/end_session/ diff --git a/src/content/docs/identityserver/reference/endpoints/introspection.md b/src/content/docs/identityserver/reference/endpoints/introspection.md index 980094109..8eec2b401 100644 --- a/src/content/docs/identityserver/reference/endpoints/introspection.md +++ b/src/content/docs/identityserver/reference/endpoints/introspection.md @@ -3,6 +3,7 @@ title: "Introspection Endpoint" description: "Documentation for the RFC 7662 compliant introspection endpoint used to validate reference tokens, JWTs, and refresh tokens." date: 2020-09-10T08:22:12+02:00 sidebar: + label: Introspection order: 5 redirect_from: - /identityserver/v5/reference/endpoints/introspection/ @@ -54,11 +55,11 @@ An invalid request will return a 400, an unauthorized request 401. ## .NET Client Library -You can use the [Duende IdentityModel](../../../identitymodel) client library to programmatically interact with +You can use the [Duende IdentityModel](/identitymodel/index.mdx) client library to programmatically interact with the protocol endpoint from .NET code. ```cs -using IdentityModel.Client; +using Duende.IdentityModel.Client; var client = new HttpClient(); diff --git a/src/content/docs/identityserver/reference/endpoints/revocation.md b/src/content/docs/identityserver/reference/endpoints/revocation.md index 5941a1719..4877b1cd8 100644 --- a/src/content/docs/identityserver/reference/endpoints/revocation.md +++ b/src/content/docs/identityserver/reference/endpoints/revocation.md @@ -3,6 +3,7 @@ title: "Revocation Endpoint" description: "Learn about the revocation endpoint that allows invalidating access and refresh tokens according to RFC 7009 specification." date: 2020-09-10T08:22:12+02:00 sidebar: + label: Revocation order: 6 redirect_from: - /identityserver/v5/reference/endpoints/revocation/ @@ -32,11 +33,11 @@ token=...&token_type_hint=refresh_token ## .NET Client Library -You can use the [Duende IdentityModel](../../../identitymodel) client library to programmatically interact with +You can use the [Duende IdentityModel](/identitymodel/index.mdx) client library to programmatically interact with the protocol endpoint from .NET code. ```cs -using IdentityModel.Client; +using Duende.IdentityModel.Client; var client = new HttpClient(); diff --git a/src/content/docs/identityserver/reference/endpoints/token.md b/src/content/docs/identityserver/reference/endpoints/token.md index b95775d8f..15b05cb16 100644 --- a/src/content/docs/identityserver/reference/endpoints/token.md +++ b/src/content/docs/identityserver/reference/endpoints/token.md @@ -3,6 +3,7 @@ title: "Token Endpoint" description: "Documentation for the token endpoint that enables programmatic token requests using various grant types and parameters in Duende IdentityServer." date: 2020-09-10T08:22:12+02:00 sidebar: + label: Token order: 3 redirect_from: - /identityserver/v5/reference/endpoints/token/ @@ -99,11 +100,11 @@ CONTENT-TYPE application/x-www-form-urlencoded ## .NET Client Library -You can use the [Duende IdentityModel](../../../identitymodel) client library to programmatically interact with +You can use the [Duende IdentityModel](/identitymodel/index.mdx) client library to programmatically interact with the protocol endpoint from .NET code. ```cs -using IdentityModel.Client; +using Duende.IdentityModel.Client; var client = new HttpClient(); diff --git a/src/content/docs/identityserver/reference/endpoints/userinfo.md b/src/content/docs/identityserver/reference/endpoints/userinfo.md index 4ec822368..179e8c799 100644 --- a/src/content/docs/identityserver/reference/endpoints/userinfo.md +++ b/src/content/docs/identityserver/reference/endpoints/userinfo.md @@ -3,6 +3,7 @@ title: "UserInfo Endpoint" description: "Reference documentation for the UserInfo endpoint, which allows retrieval of authenticated user claims using a valid access token." date: 2020-09-10T08:22:12+02:00 sidebar: + label: UserInfo order: 4 redirect_from: - /identityserver/v5/reference/endpoints/userinfo/ @@ -36,17 +37,31 @@ Content-Type: application/json ## .NET Client Library -You can use the [Duende IdentityModel](../../../identitymodel) client library to programmatically interact with +You can use the [Duende IdentityModel](/identitymodel/index.mdx) client library to programmatically interact with the protocol endpoint from .NET code. ```cs -using IdentityModel.Client; +using Duende.IdentityModel.Client; var client = new HttpClient(); -var response = await client.GetUserInfoAsync(new UserInfoRequest +var disco = await client.GetDiscoveryDocumentAsync("https://localhost:5001"); + +var token = await client.RequestAuthorizationCodeTokenAsync(new AuthorizationCodeTokenRequest +{ + Address = disco.TokenEndpoint, + + ClientId = "client", + ClientSecret = "secret", + + Code = "...", + CodeVerifier = "...", + RedirectUri = "https://app.com/callback" +}); + +var userInfo = await client.GetUserInfoAsync(new UserInfoRequest { Address = disco.UserInfoEndpoint, - Token = token + Token = token.AccessToken }); ``` \ No newline at end of file diff --git a/src/content/docs/identityserver/reference/options.md b/src/content/docs/identityserver/reference/options.md index 2a05ca758..03a924cfb 100644 --- a/src/content/docs/identityserver/reference/options.md +++ b/src/content/docs/identityserver/reference/options.md @@ -2,6 +2,7 @@ title: "IdentityServer Options" description: Documentation of all configuration options in Duende IdentityServer, including settings for key management, endpoints, authentication, events, logging, CORS, Content Security Policy, device flow, mutual TLS, dynamic providers, CIBA, server-side sessions, validation and other core features. sidebar: + label: Options order: 10 redirect_from: - /identityserver/v5/reference/options/ diff --git a/src/content/docs/identityserver/reference/services/ciba-interaction-service.md b/src/content/docs/identityserver/reference/services/ciba-interaction-service.md index fa9cff97b..258518134 100644 --- a/src/content/docs/identityserver/reference/services/ciba-interaction-service.md +++ b/src/content/docs/identityserver/reference/services/ciba-interaction-service.md @@ -2,6 +2,7 @@ title: "Backchannel Authentication Interaction Service" description: Documentation for the IBackchannelAuthenticationInteractionService interface which provides services for accessing and completing CIBA login requests. sidebar: + label: Backchannel Authentication Interaction order: 80 redirect_from: - /identityserver/v5/reference/services/ciba_interaction_service/ diff --git a/src/content/docs/identityserver/reference/services/ciba-user-notification.md b/src/content/docs/identityserver/reference/services/ciba-user-notification.md index 861ca5d7e..62ee6e4a5 100644 --- a/src/content/docs/identityserver/reference/services/ciba-user-notification.md +++ b/src/content/docs/identityserver/reference/services/ciba-user-notification.md @@ -2,6 +2,7 @@ title: "Backchannel Authentication User Notification Service" description: Documentation for the IBackchannelAuthenticationUserNotificationService interface which is used to notify users when a CIBA login request has been made. sidebar: + label: Backchannel Authentication User Notification order: 90 redirect_from: - /identityserver/v5/reference/services/ciba_user_notification/ diff --git a/src/content/docs/identityserver/reference/services/device-flow-interaction-service.md b/src/content/docs/identityserver/reference/services/device-flow-interaction-service.md index 685f3be61..d9f49a80a 100644 --- a/src/content/docs/identityserver/reference/services/device-flow-interaction-service.md +++ b/src/content/docs/identityserver/reference/services/device-flow-interaction-service.md @@ -3,6 +3,7 @@ title: "Device Flow Interaction Service" description: Documentation for the IDeviceFlowInteractionService interface which provides services for user interfaces to communicate with IdentityServer during device flow authorization. date: 2020-09-10T08:22:12+02:00 sidebar: + label: Device Flow Interaction order: 65 redirect_from: - /identityserver/v5/reference/services/device_flow_interaction_service/ diff --git a/src/content/docs/identityserver/reference/services/interaction-service.md b/src/content/docs/identityserver/reference/services/interaction-service.md index 8962edd5e..96ab7feba 100644 --- a/src/content/docs/identityserver/reference/services/interaction-service.md +++ b/src/content/docs/identityserver/reference/services/interaction-service.md @@ -3,6 +3,7 @@ title: "IdentityServer Interaction Service" description: Documentation for the IIdentityServerInteractionService interface which provides services for user interfaces to communicate with IdentityServer for authorization, consent, logout, and other user interactions. date: 2020-09-10T08:22:12+02:00 sidebar: + label: IdentityServer Interaction order: 60 redirect_from: - /identityserver/v5/reference/services/interaction_service/ diff --git a/src/content/docs/identityserver/reference/services/persisted-grant-service.md b/src/content/docs/identityserver/reference/services/persisted-grant-service.md index 143c43621..6f51b86e4 100644 --- a/src/content/docs/identityserver/reference/services/persisted-grant-service.md +++ b/src/content/docs/identityserver/reference/services/persisted-grant-service.md @@ -2,6 +2,7 @@ title: "Persisted Grant Service" description: Documentation for the IPersistedGrantService interface which provides access to a user's grants for managing consent and authorization data. sidebar: + label: Persisted Grant order: 43 redirect_from: - /identityserver/v5/reference/services/persisted_grant_service/ diff --git a/src/content/docs/identityserver/reference/services/profile-service.md b/src/content/docs/identityserver/reference/services/profile-service.md index 9a7518e1d..02da05690 100644 --- a/src/content/docs/identityserver/reference/services/profile-service.md +++ b/src/content/docs/identityserver/reference/services/profile-service.md @@ -3,6 +3,7 @@ title: "Profile Service" description: Documentation for the IProfileService interface which encapsulates retrieval of user claims and determines if users are active for token issuance. date: 2020-09-10T08:22:12+02:00 sidebar: + label: Profile order: 40 redirect_from: - /identityserver/v5/reference/services/ diff --git a/src/content/docs/identityserver/reference/services/refresh-token-service.md b/src/content/docs/identityserver/reference/services/refresh-token-service.md index bfde7bd5f..56efee999 100644 --- a/src/content/docs/identityserver/reference/services/refresh-token-service.md +++ b/src/content/docs/identityserver/reference/services/refresh-token-service.md @@ -2,6 +2,7 @@ title: "Refresh Token Service" description: Documentation for the IRefreshTokenService interface which handles validation, creation, and updating of refresh tokens with customization options for handling consumed tokens. sidebar: + label: Refresh Token order: 50 redirect_from: - /identityserver/v5/reference/services/refresh_token_service/ diff --git a/src/content/docs/identityserver/reference/services/session-management-service.md b/src/content/docs/identityserver/reference/services/session-management-service.md index 688865ed8..82ce60661 100644 --- a/src/content/docs/identityserver/reference/services/session-management-service.md +++ b/src/content/docs/identityserver/reference/services/session-management-service.md @@ -2,6 +2,7 @@ title: "Session Management Service" description: Documentation for the ISessionManagementService interface which provides administrative features to query and terminate server-side sessions, including associated tokens and consents. sidebar: + label: Session Management order: 57 redirect_from: - /identityserver/v5/reference/services/session_management_service/ diff --git a/src/content/docs/identityserver/reference/services/token-creation-service.md b/src/content/docs/identityserver/reference/services/token-creation-service.md index 9ff040266..a4b4b99b9 100644 --- a/src/content/docs/identityserver/reference/services/token-creation-service.md +++ b/src/content/docs/identityserver/reference/services/token-creation-service.md @@ -2,6 +2,7 @@ title: "Token Creation Service" description: Documentation for the ITokenCreationService interface which is responsible for creating security tokens by converting Token models into JWTs with customization options. sidebar: + label: Token Creation order: 50 redirect_from: - /identityserver/v5/reference/services/token_creation_service/ diff --git a/src/content/docs/identityserver/reference/services/user-session-service.md b/src/content/docs/identityserver/reference/services/user-session-service.md index ff0ff6e0d..fec0b44f3 100644 --- a/src/content/docs/identityserver/reference/services/user-session-service.md +++ b/src/content/docs/identityserver/reference/services/user-session-service.md @@ -2,6 +2,7 @@ title: "User Session Service" description: Documentation for the IUserSession interface which manages user sessions and tracks participating client applications for authentication and logout coordination. sidebar: + label: User Session order: 55 redirect_from: - /identityserver/v5/reference/services/user_sesion_service/ diff --git a/src/content/docs/identityserver/reference/stores/backchannel-auth-request-store.md b/src/content/docs/identityserver/reference/stores/backchannel-auth-request-store.md index 7bc3ef906..edb95b5ce 100644 --- a/src/content/docs/identityserver/reference/stores/backchannel-auth-request-store.md +++ b/src/content/docs/identityserver/reference/stores/backchannel-auth-request-store.md @@ -2,6 +2,7 @@ title: "Backchannel Authentication Request Store" description: Documentation for the IBackChannelAuthenticationRequestStore interface which is used to store and manage backchannel authentication requests for CIBA flows. sidebar: + label: Backchannel Authentication Request order: 80 redirect_from: - /identityserver/v5/reference/stores/backchannel_auth_request_store/ @@ -14,125 +15,125 @@ redirect_from: Used to store backchannel login requests (for [CIBA](/identityserver/ui/ciba)). ```cs +/// +/// Interface for the backchannel authentication request store +/// +public interface IBackChannelAuthenticationRequestStore +{ /// - /// Interface for the backchannel authentication request store - /// - public interface IBackChannelAuthenticationRequestStore - { - /// - /// Creates the request. - /// - Task CreateRequestAsync(BackChannelAuthenticationRequest request); - - /// - /// Gets the requests. - /// - Task> GetLoginsForUserAsync(string subjectId, string clientId = null); - - /// - /// Gets the request. - /// - Task GetByAuthenticationRequestIdAsync(string requestId); - - /// - /// Gets the request. - /// - Task GetByInternalIdAsync(string id); - - /// - /// Removes the request. - /// - Task RemoveByInternalIdAsync(string id); - - /// - /// Updates the request. - /// - Task UpdateByInternalIdAsync(string id, BackChannelAuthenticationRequest request); - } + /// Creates the request. + /// + Task CreateRequestAsync(BackChannelAuthenticationRequest request); + + /// + /// Gets the requests. + /// + Task> GetLoginsForUserAsync(string subjectId, string clientId = null); + + /// + /// Gets the request. + /// + Task GetByAuthenticationRequestIdAsync(string requestId); + + /// + /// Gets the request. + /// + Task GetByInternalIdAsync(string id); + + /// + /// Removes the request. + /// + Task RemoveByInternalIdAsync(string id); + + /// + /// Updates the request. + /// + Task UpdateByInternalIdAsync(string id, BackChannelAuthenticationRequest request); +} ``` #### BackChannelAuthenticationRequest ```cs +/// +/// Models a backchannel authentication request. +/// +public class BackChannelAuthenticationRequest +{ + /// + /// The identifier for this request in the store. + /// + public string InternalId { get; set; } + + /// + /// Gets or sets the creation time. + /// + public DateTime CreationTime { get; set; } + + /// + /// Gets or sets the life time in seconds. + /// + public int Lifetime { get; set; } + + /// + /// Gets or sets the ID of the client. + /// + public string ClientId { get; set; } + + /// + /// Gets or sets the subject. + /// + public ClaimsPrincipal Subject { get; set; } + + /// + /// Gets or sets the requested scopes. + /// + public IEnumerable RequestedScopes { get; set; } + + /// + /// Gets or sets the requested resource indicators. + /// + public IEnumerable RequestedResourceIndicators { get; set; } + + /// + /// Gets or sets the authentication context reference classes. + /// + public ICollection AuthenticationContextReferenceClasses { get; set; } + + /// + /// Gets or sets the tenant. + /// + public string Tenant { get; set; } + + /// + /// Gets or sets the idp. + /// + public string IdP { get; set; } + + /// + /// Gets or sets the binding message. + /// + public string BindingMessage { get; set; } + + + /// + /// Gets or sets a value indicating whether this instance has been completed. + /// + public bool IsComplete { get; set; } + /// - /// Models a backchannel authentication request. - /// - public class BackChannelAuthenticationRequest - { - /// - /// The identifier for this request in the store. - /// - public string InternalId { get; set; } - - /// - /// Gets or sets the creation time. - /// - public DateTime CreationTime { get; set; } - - /// - /// Gets or sets the life time in seconds. - /// - public int Lifetime { get; set; } - - /// - /// Gets or sets the ID of the client. - /// - public string ClientId { get; set; } - - /// - /// Gets or sets the subject. - /// - public ClaimsPrincipal Subject { get; set; } - - /// - /// Gets or sets the requested scopes. - /// - public IEnumerable RequestedScopes { get; set; } - - /// - /// Gets or sets the requested resource indicators. - /// - public IEnumerable RequestedResourceIndicators { get; set; } - - /// - /// Gets or sets the authentication context reference classes. - /// - public ICollection AuthenticationContextReferenceClasses { get; set; } - - /// - /// Gets or sets the tenant. - /// - public string Tenant { get; set; } - - /// - /// Gets or sets the idp. - /// - public string IdP { get; set; } - - /// - /// Gets or sets the binding message. - /// - public string BindingMessage { get; set; } - - - /// - /// Gets or sets a value indicating whether this instance has been completed. - /// - public bool IsComplete { get; set; } - - /// - /// Gets or sets the authorized scopes. - /// - public IEnumerable AuthorizedScopes { get; set; } - - /// - /// Gets or sets the session identifier from which the user approved the request. - /// - public string SessionId { get; set; } - - /// - /// Gets the description the user assigned to the client being authorized. - /// - public string Description { get; set; } - } + /// Gets or sets the authorized scopes. + /// + public IEnumerable AuthorizedScopes { get; set; } + + /// + /// Gets or sets the session identifier from which the user approved the request. + /// + public string SessionId { get; set; } + + /// + /// Gets the description the user assigned to the client being authorized. + /// + public string Description { get; set; } +} ``` diff --git a/src/content/docs/identityserver/reference/stores/client-store.md b/src/content/docs/identityserver/reference/stores/client-store.md index bfc981e0d..6ab16dc63 100644 --- a/src/content/docs/identityserver/reference/stores/client-store.md +++ b/src/content/docs/identityserver/reference/stores/client-store.md @@ -2,6 +2,7 @@ title: "Client Store" description: Documentation for the IClientStore interface which is used to dynamically load client configuration by client ID. sidebar: + label: Client order: 36 redirect_from: - /identityserver/v5/reference/stores/client_store/ @@ -14,16 +15,16 @@ redirect_from: Used to dynamically load client configuration. ```cs +/// +/// Retrieval of client configuration +/// +public interface IClientStore +{ /// - /// Retrieval of client configuration + /// Finds a client by id /// - public interface IClientStore - { - /// - /// Finds a client by id - /// - /// The client id - /// The client - Task FindClientByIdAsync(string clientId); - } + /// The client id + /// The client + Task FindClientByIdAsync(string clientId); +} ``` diff --git a/src/content/docs/identityserver/reference/stores/cors-policy-service.md b/src/content/docs/identityserver/reference/stores/cors-policy-service.md index 86039ac2e..4fa0f1dfa 100644 --- a/src/content/docs/identityserver/reference/stores/cors-policy-service.md +++ b/src/content/docs/identityserver/reference/stores/cors-policy-service.md @@ -2,6 +2,7 @@ title: "CORS Policy Service" description: Documentation for the ICorsPolicyService interface which determines if CORS requests from specific origins are allowed to access protocol endpoints. sidebar: + label: CORS Policy order: 36 redirect_from: - /identityserver/v5/reference/stores/cors_policy_service/ @@ -14,16 +15,16 @@ redirect_from: Used to determine if CORS requests are allowed to certain protocol endpoints. ```cs +/// +/// Service that determines if CORS is allowed. +/// +public interface ICorsPolicyService +{ /// - /// Service that determines if CORS is allowed. + /// Determines whether origin is allowed. /// - public interface ICorsPolicyService - { - /// - /// Determines whether origin is allowed. - /// - /// The origin. - /// - Task IsOriginAllowedAsync(string origin); - } + /// The origin. + /// + Task IsOriginAllowedAsync(string origin); +} ``` diff --git a/src/content/docs/identityserver/reference/stores/device-flow-store.md b/src/content/docs/identityserver/reference/stores/device-flow-store.md index 3557aac50..3fa7f6672 100644 --- a/src/content/docs/identityserver/reference/stores/device-flow-store.md +++ b/src/content/docs/identityserver/reference/stores/device-flow-store.md @@ -2,6 +2,7 @@ title: "Device Flow Store" description: Documentation for the IDeviceFlowStore interface which manages storage of authorization grants for the device flow authentication process. sidebar: + label: Device Flow order: 43 redirect_from: - /identityserver/v5/reference/stores/device_flow_store/ @@ -14,134 +15,134 @@ redirect_from: Models storage of grants for the device flow. ```cs +/// +/// Interface for the device flow store +/// +public interface IDeviceFlowStore +{ /// - /// Interface for the device flow store + /// Stores the device authorization request. /// - public interface IDeviceFlowStore - { - /// - /// Stores the device authorization request. - /// - /// The device code. - /// The user code. - /// The data. - /// - Task StoreDeviceAuthorizationAsync(string deviceCode, string userCode, DeviceCode data); - - /// - /// Finds device authorization by user code. - /// - /// The user code. - /// - Task FindByUserCodeAsync(string userCode); - - /// - /// Finds device authorization by device code. - /// - /// The device code. - Task FindByDeviceCodeAsync(string deviceCode); - - /// - /// Updates device authorization, searching by user code. - /// - /// The user code. - /// The data. - Task UpdateByUserCodeAsync(string userCode, DeviceCode data); - - /// - /// Removes the device authorization, searching by device code. - /// - /// The device code. - Task RemoveByDeviceCodeAsync(string deviceCode); - } + /// The device code. + /// The user code. + /// The data. + /// + Task StoreDeviceAuthorizationAsync(string deviceCode, string userCode, DeviceCode data); + + /// + /// Finds device authorization by user code. + /// + /// The user code. + /// + Task FindByUserCodeAsync(string userCode); + + /// + /// Finds device authorization by device code. + /// + /// The device code. + Task FindByDeviceCodeAsync(string deviceCode); + + /// + /// Updates device authorization, searching by user code. + /// + /// The user code. + /// The data. + Task UpdateByUserCodeAsync(string userCode, DeviceCode data); + + /// + /// Removes the device authorization, searching by device code. + /// + /// The device code. + Task RemoveByDeviceCodeAsync(string deviceCode); +} ``` #### DeviceCode ```cs +/// +/// Represents data needed for device flow. +/// +public class DeviceCode +{ + /// + /// Gets or sets the creation time. + /// + /// + /// The creation time. + /// + public DateTime CreationTime { get; set; } + + /// + /// Gets or sets the lifetime. + /// + /// + /// The lifetime. + /// + public int Lifetime { get; set; } + + /// + /// Gets or sets the client identifier. + /// + /// + /// The client identifier. + /// + public string ClientId { get; set; } + + /// + /// Gets the description the user assigned to the device being authorized. + /// + /// + /// The description. + /// + public string Description { get; set; } + + /// + /// Gets or sets a value indicating whether this instance is open identifier. + /// + /// + /// true if this instance is open identifier; otherwise, false. + /// + public bool IsOpenId { get; set; } + + /// + /// Gets or sets a value indicating whether this instance is authorized. + /// + /// + /// true if this instance is authorized; otherwise, false. + /// + public bool IsAuthorized { get; set; } + + /// + /// Gets or sets the requested scopes. + /// + /// + /// The authorized scopes. + /// + public IEnumerable RequestedScopes { get; set; } + + /// + /// Gets or sets the authorized scopes. + /// + /// + /// The authorized scopes. + /// + public IEnumerable AuthorizedScopes { get; set; } + + /// + /// Gets or sets the subject. + /// + /// + /// The subject. + /// + public ClaimsPrincipal Subject { get; set; } + /// - /// Represents data needed for device flow. + /// Gets or sets the session identifier. /// - public class DeviceCode - { - /// - /// Gets or sets the creation time. - /// - /// - /// The creation time. - /// - public DateTime CreationTime { get; set; } - - /// - /// Gets or sets the lifetime. - /// - /// - /// The lifetime. - /// - public int Lifetime { get; set; } - - /// - /// Gets or sets the client identifier. - /// - /// - /// The client identifier. - /// - public string ClientId { get; set; } - - /// - /// Gets the description the user assigned to the device being authorized. - /// - /// - /// The description. - /// - public string Description { get; set; } - - /// - /// Gets or sets a value indicating whether this instance is open identifier. - /// - /// - /// true if this instance is open identifier; otherwise, false. - /// - public bool IsOpenId { get; set; } - - /// - /// Gets or sets a value indicating whether this instance is authorized. - /// - /// - /// true if this instance is authorized; otherwise, false. - /// - public bool IsAuthorized { get; set; } - - /// - /// Gets or sets the requested scopes. - /// - /// - /// The authorized scopes. - /// - public IEnumerable RequestedScopes { get; set; } - - /// - /// Gets or sets the authorized scopes. - /// - /// - /// The authorized scopes. - /// - public IEnumerable AuthorizedScopes { get; set; } - - /// - /// Gets or sets the subject. - /// - /// - /// The subject. - /// - public ClaimsPrincipal Subject { get; set; } - - /// - /// Gets or sets the session identifier. - /// - /// - /// The session identifier. - /// - public string SessionId { get; set; } - } + /// + /// The session identifier. + /// + public string SessionId { get; set; } +} ``` diff --git a/src/content/docs/identityserver/reference/stores/idp-store.md b/src/content/docs/identityserver/reference/stores/idp-store.md index 39ba1fac4..64dc19603 100644 --- a/src/content/docs/identityserver/reference/stores/idp-store.md +++ b/src/content/docs/identityserver/reference/stores/idp-store.md @@ -2,6 +2,7 @@ title: "Identity Provider Store" description: Documentation for the IIdentityProviderStore interface which dynamically loads identity provider configurations for external authentication. sidebar: + label: Identity Provider order: 36 redirect_from: - /identityserver/v5/reference/stores/idp_store/ @@ -14,23 +15,23 @@ redirect_from: Used to dynamically load [identity provider configuration](/identityserver/reference/models/idp). ```cs +/// +/// Interface to model storage of identity providers. +/// +public interface IIdentityProviderStore +{ /// - /// Interface to model storage of identity providers. + /// Gets all identity providers name. /// - public interface IIdentityProviderStore - { - /// - /// Gets all identity providers name. - /// - Task> GetAllSchemeNamesAsync(); + Task> GetAllSchemeNamesAsync(); - /// - /// Gets the identity provider by scheme name. - /// - /// - /// - Task GetBySchemeAsync(string scheme); - } + /// + /// Gets the identity provider by scheme name. + /// + /// + /// + Task GetBySchemeAsync(string scheme); +} ``` The `IdentityProvider` is intended to be a base class to model arbitrary identity providers. diff --git a/src/content/docs/identityserver/reference/stores/persisted-grant-store.md b/src/content/docs/identityserver/reference/stores/persisted-grant-store.md index 30820d8b1..563878615 100644 --- a/src/content/docs/identityserver/reference/stores/persisted-grant-store.md +++ b/src/content/docs/identityserver/reference/stores/persisted-grant-store.md @@ -2,6 +2,7 @@ title: "Persisted Grant Store" description: Documentation for the IPersistedGrantStore interface which manages storage and retrieval of authorization grants such as refresh tokens, reference tokens, and user consent. sidebar: + label: Persisted Grant order: 42 redirect_from: - /identityserver/v5/reference/stores/persisted_grant_store/ @@ -153,43 +154,43 @@ one-time use semantics are appropriate for the grant. #### PersistedGrantFilter ```cs +/// +/// Represents a filter used when accessing the persisted grants store. +/// Setting multiple properties is interpreted as a logical 'AND' to further filter the query. +/// At least one value must be supplied. +/// +public class PersistedGrantFilter +{ /// - /// Represents a filter used when accessing the persisted grants store. - /// Setting multiple properties is interpreted as a logical 'AND' to further filter the query. - /// At least one value must be supplied. + /// Subject id of the user. /// - public class PersistedGrantFilter - { - /// - /// Subject id of the user. - /// - public string SubjectId { get; set; } - - /// - /// Session id used for the grant. - /// - public string SessionId { get; set; } - - /// - /// Client id the grant was issued to. - /// - public string ClientId { get; set; } - - /// - /// Client ids the grant was issued to. - /// - public IEnumerable ClientIds { get; set; } - - /// - /// The type of grant. - /// - public string Type { get; set; } - - /// - /// The types of grants. - /// - public IEnumerable Types { get; set; } - } + public string SubjectId { get; set; } + + /// + /// Session id used for the grant. + /// + public string SessionId { get; set; } + + /// + /// Client id the grant was issued to. + /// + public string ClientId { get; set; } + + /// + /// Client ids the grant was issued to. + /// + public IEnumerable ClientIds { get; set; } + + /// + /// The type of grant. + /// + public string Type { get; set; } + + /// + /// The types of grants. + /// + public IEnumerable Types { get; set; } +} ``` #### PersistedGrantTypes @@ -197,14 +198,14 @@ one-time use semantics are appropriate for the grant. The types of persisted grants are defined by the `IdentityServerConstants.PersistedGrantTypes` constants: ```cs - public static class PersistedGrantTypes - { - public const string AuthorizationCode = "authorization_code"; - public const string BackChannelAuthenticationRequest = "ciba"; - public const string ReferenceToken = "reference_token"; - public const string RefreshToken = "refresh_token"; - public const string UserConsent = "user_consent"; - public const string DeviceCode = "device_code"; - public const string UserCode = "user_code"; - } +public static class PersistedGrantTypes +{ + public const string AuthorizationCode = "authorization_code"; + public const string BackChannelAuthenticationRequest = "ciba"; + public const string ReferenceToken = "reference_token"; + public const string RefreshToken = "refresh_token"; + public const string UserConsent = "user_consent"; + public const string DeviceCode = "device_code"; + public const string UserCode = "user_code"; +} ``` diff --git a/src/content/docs/identityserver/reference/stores/pushed-authorization-request-store.md b/src/content/docs/identityserver/reference/stores/pushed-authorization-request-store.md index f42817a8e..62db616fa 100644 --- a/src/content/docs/identityserver/reference/stores/pushed-authorization-request-store.md +++ b/src/content/docs/identityserver/reference/stores/pushed-authorization-request-store.md @@ -2,6 +2,7 @@ title: "Pushed Authorization Request Store" description: Interface for managing pushed authorization requests storage in OAuth PAR flow. sidebar: + label: Pushed Authorization Request order: 110 redirect_from: - /identityserver/v5/reference/stores/pushed_authorization_request_store/ diff --git a/src/content/docs/identityserver/reference/stores/resource-store.md b/src/content/docs/identityserver/reference/stores/resource-store.md index 31ebaa72c..293b2fb33 100644 --- a/src/content/docs/identityserver/reference/stores/resource-store.md +++ b/src/content/docs/identityserver/reference/stores/resource-store.md @@ -2,6 +2,7 @@ title: "Resource Store" description: Documentation for the IResourceStore interface which dynamically loads identity resources, API scopes, and API resources for authorization decisions. sidebar: + label: Resource order: 32 redirect_from: - /identityserver/v5/reference/stores/resource_store/ @@ -14,34 +15,34 @@ redirect_from: Used to dynamically load resource configuration. ```cs +/// +/// Resource retrieval +/// +public interface IResourceStore +{ /// - /// Resource retrieval + /// Gets identity resources by scope name. /// - public interface IResourceStore - { - /// - /// Gets identity resources by scope name. - /// - Task> FindIdentityResourcesByScopeNameAsync(IEnumerable scopeNames); + Task> FindIdentityResourcesByScopeNameAsync(IEnumerable scopeNames); - /// - /// Gets API scopes by scope name. - /// - Task> FindApiScopesByNameAsync(IEnumerable scopeNames); + /// + /// Gets API scopes by scope name. + /// + Task> FindApiScopesByNameAsync(IEnumerable scopeNames); - /// - /// Gets API resources by scope name. - /// - Task> FindApiResourcesByScopeNameAsync(IEnumerable scopeNames); + /// + /// Gets API resources by scope name. + /// + Task> FindApiResourcesByScopeNameAsync(IEnumerable scopeNames); - /// - /// Gets API resources by API resource name. - /// - Task> FindApiResourcesByNameAsync(IEnumerable apiResourceNames); + /// + /// Gets API resources by API resource name. + /// + Task> FindApiResourcesByNameAsync(IEnumerable apiResourceNames); - /// - /// Gets all resources. - /// - Task GetAllResourcesAsync(); - } + /// + /// Gets all resources. + /// + Task GetAllResourcesAsync(); +} ``` diff --git a/src/content/docs/identityserver/reference/stores/server-side-sessions.md b/src/content/docs/identityserver/reference/stores/server-side-sessions.md index 4922d1739..79f491f67 100644 --- a/src/content/docs/identityserver/reference/stores/server-side-sessions.md +++ b/src/content/docs/identityserver/reference/stores/server-side-sessions.md @@ -2,6 +2,7 @@ title: "Server-Side Session Store" description: "Documentation for the IServerSideSessionStore interface and related models for managing server-side user authentication session data." sidebar: + label: Server-Side Sessions order: 100 redirect_from: - /identityserver/v5/reference/stores/server_side_sessions/ diff --git a/src/content/docs/identityserver/reference/stores/signing-key-store.md b/src/content/docs/identityserver/reference/stores/signing-key-store.md index cf1baa717..3bc81c385 100644 --- a/src/content/docs/identityserver/reference/stores/signing-key-store.md +++ b/src/content/docs/identityserver/reference/stores/signing-key-store.md @@ -2,6 +2,7 @@ title: "Signing Key Store" description: Documentation for the ISigningKeyStore interface which manages the storage, retrieval, and deletion of cryptographic keys used for signing tokens. sidebar: + label: Signing Key order: 90 redirect_from: - /identityserver/v5/reference/stores/signing_key_store/ @@ -14,76 +15,76 @@ redirect_from: Used to dynamically load client configuration. ```cs +/// +/// Interface to model storage of serialized keys. +/// +public interface ISigningKeyStore +{ /// - /// Interface to model storage of serialized keys. + /// Returns all the keys in storage. /// - public interface ISigningKeyStore - { - /// - /// Returns all the keys in storage. - /// - /// - Task> LoadKeysAsync(); + /// + Task> LoadKeysAsync(); - /// - /// Persists new key in storage. - /// - /// - /// - Task StoreKeyAsync(SerializedKey key); + /// + /// Persists new key in storage. + /// + /// + /// + Task StoreKeyAsync(SerializedKey key); - /// - /// Deletes key from storage. - /// - /// - /// - Task DeleteKeyAsync(string id); - } + /// + /// Deletes key from storage. + /// + /// + /// + Task DeleteKeyAsync(string id); +} ``` #### SerializedKey ```cs +/// +/// Serialized key. +/// +public class SerializedKey +{ /// - /// Serialized key. + /// Version number of serialized key. /// - public class SerializedKey - { - /// - /// Version number of serialized key. - /// - public int Version { get; set; } + public int Version { get; set; } - /// - /// Key identifier. - /// - public string Id { get; set; } + /// + /// Key identifier. + /// + public string Id { get; set; } - /// - /// Date key was created. - /// - public DateTime Created { get; set; } + /// + /// Date key was created. + /// + public DateTime Created { get; set; } - /// - /// The algorithm. - /// - public string Algorithm { get; set; } + /// + /// The algorithm. + /// + public string Algorithm { get; set; } - /// - /// Contains X509 certificate. - /// - public bool IsX509Certificate { get; set; } + /// + /// Contains X509 certificate. + /// + public bool IsX509Certificate { get; set; } - /// - /// Serialized data for key. - /// - public string Data { get; set; } + /// + /// Serialized data for key. + /// + public string Data { get; set; } - /// - /// Indicates if data is protected. - /// - public bool DataProtected { get; set; } - } + /// + /// Indicates if data is protected. + /// + public bool DataProtected { get; set; } +} ``` :::note diff --git a/src/content/docs/identityserver/reference/validators/ciba-user-validator.md b/src/content/docs/identityserver/reference/validators/ciba-user-validator.md index ebe9d1067..997743f98 100644 --- a/src/content/docs/identityserver/reference/validators/ciba-user-validator.md +++ b/src/content/docs/identityserver/reference/validators/ciba-user-validator.md @@ -2,6 +2,7 @@ title: "Backchannel Authentication User Validator" description: Documentation for the IBackchannelAuthenticationUserValidator interface which is used to validate request hints and identify the user for CIBA authentication requests. sidebar: + label: Backchannel Authentication User order: 30 redirect_from: - /identityserver/v5/reference/validators/ciba_user_validator/ diff --git a/src/content/docs/identityserver/reference/validators/custom-authorize-request-validator.md b/src/content/docs/identityserver/reference/validators/custom-authorize-request-validator.md index 310be1436..4db03a0cc 100644 --- a/src/content/docs/identityserver/reference/validators/custom-authorize-request-validator.md +++ b/src/content/docs/identityserver/reference/validators/custom-authorize-request-validator.md @@ -2,6 +2,7 @@ title: "Custom Authorize Request Validator" description: Documentation for the ICustomAuthorizeRequestValidator interface which allows inserting custom validation logic into the authorization request pipeline. sidebar: + label: Custom Authorize Request order: 10 redirect_from: - /identityserver/v5/reference/validators/ diff --git a/src/content/docs/identityserver/reference/validators/custom-token-request-validator.md b/src/content/docs/identityserver/reference/validators/custom-token-request-validator.md index 40908d07f..1860430e3 100644 --- a/src/content/docs/identityserver/reference/validators/custom-token-request-validator.md +++ b/src/content/docs/identityserver/reference/validators/custom-token-request-validator.md @@ -2,6 +2,7 @@ title: "Custom Token Request Validator" description: Documentation for the ICustomTokenRequestValidator interface which allows inserting custom validation logic into token requests with the ability to modify request parameters and response fields. sidebar: + label: Custom Token Request order: 20 redirect_from: - /identityserver/v5/reference/validators/custom_token_request_validator/ diff --git a/src/content/docs/identityserver/reference/validators/dpop-proof-validator.md b/src/content/docs/identityserver/reference/validators/dpop-proof-validator.md index 8c7ae8c6e..e668ec490 100644 --- a/src/content/docs/identityserver/reference/validators/dpop-proof-validator.md +++ b/src/content/docs/identityserver/reference/validators/dpop-proof-validator.md @@ -2,6 +2,7 @@ title: "DPoP Proof Validator" description: Documentation for the IDPoPProofValidator interface which validates Demonstrating Proof of Possession (DPoP) tokens to ensure secure binding between access tokens and client key pairs. sidebar: + label: DPoP Proof order: 40 redirect_from: - /identityserver/v5/reference/validators/dpop_proof_validator/ diff --git a/src/content/docs/identityserver/reference/validators/extension-grant-validator.md b/src/content/docs/identityserver/reference/validators/extension-grant-validator.md index d711fd476..87c72b79d 100644 --- a/src/content/docs/identityserver/reference/validators/extension-grant-validator.md +++ b/src/content/docs/identityserver/reference/validators/extension-grant-validator.md @@ -2,6 +2,7 @@ title: "Extension Grant Validator" description: Documentation for the IExtensionGrantValidator interface which enables custom OAuth grant types by handling validation of extension grant requests. sidebar: + label: Extension Grant order: 80 redirect_from: - /identityserver/v5/reference/validators/extension_grant_validator/ diff --git a/src/content/docs/identityserver/tokens/client-authentication.md b/src/content/docs/identityserver/tokens/client-authentication.md index bfc7274a5..4b54c5b02 100644 --- a/src/content/docs/identityserver/tokens/client-authentication.md +++ b/src/content/docs/identityserver/tokens/client-authentication.md @@ -3,6 +3,7 @@ title: "Client Authentication" description: "A comprehensive guide to client authentication methods in Duende IdentityServer, including shared secrets, private key JWTs, and mutual TLS client certificates, with implementation examples and security considerations." date: 2020-09-10T08:22:12+02:00 sidebar: + label: Client Authentication order: 140 redirect_from: - /identityserver/v5/tokens/client_authentication/ @@ -85,7 +86,7 @@ The following secret parsers are part of Duende IdentityServer: ### Secret Validation -It is the job of implementations of the [ISecretValidator](/identityserver/reference/models/secrets#duendeidentityservermodelparsedsecret) interface to validate the extracted credentials. +It is the job of implementations of the [ISecretValidator](/identityserver/reference/models/secrets.md#duendeidentityservermodelparsedsecret) interface to validate the extracted credentials. You can add secret validators by calling the `AddSecretValidator()` service provider extension method. @@ -153,7 +154,7 @@ var compromisedSecret = new Secret("just for demos, not prod!".Sha256()); You can either send the client id/secret combination as part of the POST body:: -``` +```http request POST /connect/token Content-type: application/x-www-form-urlencoded @@ -168,7 +169,7 @@ Content-type: application/x-www-form-urlencoded ...or as a basic authentication header:: -``` +```http request POST /connect/token Content-type: application/x-www-form-urlencoded @@ -181,11 +182,11 @@ Authorization: Basic xxxxx ### .NET Client Library -You can use the [Duende IdentityModel](../../../identitymodel) client library to programmatically interact with +You can use the [Duende IdentityModel](/identitymodel/index.mdx) client library to programmatically interact with the protocol endpoint from .NET code. ```cs -using IdentityModel.Client; +using Duende.IdentityModel.Client; var client = new HttpClient(); @@ -252,7 +253,7 @@ You can share the same key for client authentication and [signed authorize reque On the client side, the caller must first generate the JWT, and then send it on the `assertion` body field: -``` +```http request POST /connect/token Content-type: application/x-www-form-urlencoded @@ -298,7 +299,7 @@ private static string CreateClientToken(SigningCredentials credential, string cl protocol endpoint from .NET code. ```cs -using IdentityModel.Client; +using Duende.IdentityModel.Client; static async Task RequestTokenAsync(SigningCredentials credential) { diff --git a/src/content/docs/identityserver/tokens/cors.md b/src/content/docs/identityserver/tokens/cors.md index d832672de..2551644b1 100644 --- a/src/content/docs/identityserver/tokens/cors.md +++ b/src/content/docs/identityserver/tokens/cors.md @@ -2,6 +2,7 @@ title: "Calling Endpoints from JavaScript" date: 2020-09-10T08:22:12+02:00 sidebar: + label: CORS order: 200 redirect_from: - /identityserver/v5/tokens/cors/ diff --git a/src/content/docs/identityserver/tokens/dynamic-validation.md b/src/content/docs/identityserver/tokens/dynamic-validation.md index fc42ac723..1876c6c2b 100644 --- a/src/content/docs/identityserver/tokens/dynamic-validation.md +++ b/src/content/docs/identityserver/tokens/dynamic-validation.md @@ -3,6 +3,7 @@ title: "Dynamic Request Validation and Customization" description: "A guide to implementing the ICustomTokenRequestValidator interface to extend the token request pipeline with additional validation logic, custom processing, response parameter additions, and on-the-fly parameter modifications." date: 2020-09-10T08:22:12+02:00 sidebar: + label: "Custom Validation" order: 50 redirect_from: - /identityserver/v5/tokens/dynamic_validation/ diff --git a/src/content/docs/identityserver/tokens/extension-grants.md b/src/content/docs/identityserver/tokens/extension-grants.md index 89b696f08..4caaf1332 100644 --- a/src/content/docs/identityserver/tokens/extension-grants.md +++ b/src/content/docs/identityserver/tokens/extension-grants.md @@ -3,6 +3,7 @@ title: Extension Grants description: "A guide to implementing OAuth extension grants in IdentityServer for non-standard token issuance scenarios, with a focus on token exchange for impersonation and delegation using the IExtensionGrantValidator interface." date: 2020-09-10T08:20:20+02:00 sidebar: + label: Extension Grants order: 40 redirect_from: - /identityserver/v5/tokens/extension_grants/ diff --git a/src/content/docs/identityserver/tokens/internal.md b/src/content/docs/identityserver/tokens/internal.md index ad80c115b..2e57204c8 100644 --- a/src/content/docs/identityserver/tokens/internal.md +++ b/src/content/docs/identityserver/tokens/internal.md @@ -3,6 +3,7 @@ title: "Issuing Internal Tokens" description: "A guide to using the IIdentityServerTools interface for creating JWT tokens internally within IdentityServer's extensibility code, without going through the protocol endpoints." date: 2020-09-10T08:22:12+02:00 sidebar: + label: Internal Tokens order: 60 redirect_from: - /identityserver/v5/tokens/internal/ diff --git a/src/content/docs/identityserver/tokens/jar.md b/src/content/docs/identityserver/tokens/jar.md index dc3d73319..a7009ae97 100644 --- a/src/content/docs/identityserver/tokens/jar.md +++ b/src/content/docs/identityserver/tokens/jar.md @@ -1,7 +1,9 @@ --- title: "Signed Authorize Requests" -description: "A guide to implementing JWT Secured Authorization Requests (JAR) in IdentityServer, allowing authorization parameters to be packaged in signed JWTs for tamperproof requests and front-channel client authentication." +description: "JWT Secured Authorization Request (JAR) is a security enhancement that allows authorization parameters to be packaged in signed JWTs, providing tamperproof requests and front-channel client authentication in IdentityServer." +date: 2024-01-20 sidebar: + label: "Signed Requests" order: 150 redirect_from: - /identityserver/v5/tokens/jar/ diff --git a/src/content/docs/identityserver/tokens/par.md b/src/content/docs/identityserver/tokens/par.md index bfeb56bfa..0e8d5a264 100644 --- a/src/content/docs/identityserver/tokens/par.md +++ b/src/content/docs/identityserver/tokens/par.md @@ -2,6 +2,7 @@ title: Pushed Authorization Requests description: "Pushed Authorization Requests (PAR) in IdentityServer, an OAuth standard that enhances security by moving authorization parameters from the front channel to the back channel." sidebar: + label: Pushed Authorization Requests order: 175 redirect_from: - /identityserver/v5/tokens/par/ diff --git a/src/content/docs/identityserver/tokens/password-grant.md b/src/content/docs/identityserver/tokens/password-grant.md index 8465a7973..b92f81920 100644 --- a/src/content/docs/identityserver/tokens/password-grant.md +++ b/src/content/docs/identityserver/tokens/password-grant.md @@ -1,8 +1,9 @@ --- -title: "Issuing Tokens based on User Passwords" +title: "Issuing Tokens Based On User Passwords" description: "A guide to implementing the deprecated password grant type in IdentityServer for legacy applications, covering token requests, client library usage, and custom validation of user credentials." date: 2020-09-10T08:22:12+02:00 sidebar: + label: Password Grants order: 30 redirect_from: - /identityserver/v5/tokens/password_grant/ @@ -39,12 +40,13 @@ password=password ### .NET Client Library -On .NET you can use the [Duende IdentityModel](../../../identitymodel) client library -to [request](../../../identitymodel/endpoints/token) tokens using the `password` grant type, +On .NET you can use the [Duende IdentityModel](/identitymodel/index.mdx) client library +to [request](/identitymodel/endpoints/token.md) tokens using the `password` grant type, e.g.: -```cs -using IdentityModel.Client; +```csharp +// Program.cs +using Duende.IdentityModel.Client; var client = new HttpClient(); @@ -68,7 +70,8 @@ credentials is included. To add support for it, you need to implement and [register](/identityserver/reference/di#additional-services) an implementation of the `IResourceOwnerPasswordValidator` interface: -```cs +```csharp +// IResourceOwnerPasswordValidator.cs public interface IResourceOwnerPasswordValidator { /// @@ -82,4 +85,4 @@ public interface IResourceOwnerPasswordValidator The context contains parsed protocol parameters like `UserName` and `Password` and the raw request. It is the job of the validator to implement the password validation and set the `Result` property on the context -accordingly (see the [Grant Validation Result](/identityserver/reference/models/grant-validation-result/) reference). +accordingly (see the [Grant Validation Result](/identityserver/reference/models/grant-validation-result.md) reference). diff --git a/src/content/docs/identityserver/tokens/pop.md b/src/content/docs/identityserver/tokens/pop.md index 0d8645c3b..e650d27d2 100644 --- a/src/content/docs/identityserver/tokens/pop.md +++ b/src/content/docs/identityserver/tokens/pop.md @@ -3,6 +3,7 @@ title: "Proof-of-Possession Access Tokens" description: "Documentation for Proof-of-Possession (PoP) tokens, which enhance security by cryptographically binding tokens to clients, including both Mutual TLS and DPoP implementations." date: 2020-09-10T08:22:12+02:00 sidebar: + label: Proof-of-Possession order: 100 redirect_from: - /identityserver/apis/aspnetcore/dpop/ diff --git a/src/content/docs/identityserver/tokens/reference.md b/src/content/docs/identityserver/tokens/reference.md index 47e329fb7..575c3bf19 100644 --- a/src/content/docs/identityserver/tokens/reference.md +++ b/src/content/docs/identityserver/tokens/reference.md @@ -3,6 +3,7 @@ title: "Reference Tokens" description: "Documentation about reference tokens in Duende IdentityServer, including how they are stored, accessed, and configured for both clients and APIs." date: 2020-09-10T08:22:12+02:00 sidebar: + label: Reference Tokens order: 100 redirect_from: - /identityserver/v5/tokens/reference/ diff --git a/src/content/docs/identityserver/tokens/refresh.md b/src/content/docs/identityserver/tokens/refresh.md index f5b0ad5c8..3c0fce86c 100644 --- a/src/content/docs/identityserver/tokens/refresh.md +++ b/src/content/docs/identityserver/tokens/refresh.md @@ -3,6 +3,7 @@ title: "Refreshing a Token" description: "Documentation for refresh token management in IdentityServer, including requesting, using and securing refresh tokens for long-lived access to resources" date: 2020-09-10T08:22:12+02:00 sidebar: + label: Refreshes order: 20 redirect_from: - /identityserver/v5/tokens/refresh/ @@ -16,7 +17,7 @@ access token. This can be done with an API call and does not require any user in Since this is a privileged operation, the clients needs to be explicitly authorized to be able to use refresh tokens by setting the `AllowOfflineAccess` property to `true`. See -the [client reference](/identityserver/reference/models/client#refresh-token) section for additional refresh token +the [client reference](/identityserver/reference/models/client.md#refresh-token) section for additional refresh token related settings. Refresh tokens are supported for the following flows: authorization code, hybrid and resource owner password credential @@ -44,11 +45,11 @@ POST /connect/token #### .NET Client Library -On .NET you can leverage the [Duende IdentityModel](../../../identitymodel) client library -to [request](../../../identitymodel/endpoints/token) refresh tokens, e.g.: +On .NET you can leverage the [Duende IdentityModel](/identitymodel/index.mdx) client library +to [request](/identitymodel/endpoints/token.md) refresh tokens, e.g.: ```cs -using IdentityModel.Client; +using Duende.IdentityModel.Client; var client = new HttpClient(); @@ -76,7 +77,7 @@ are issued to and the client is required to authenticate itself in order to do s token issued to a confidential client cannot use it without the client's credentials. Refresh tokens issued to public clients are not bound to the client in the same way, since the client cannot -authenticate itself. We recommend that such refresh tokens be sender-constrained using [Proof of Possession](/identityserver/tokens/pop/) +authenticate itself. We recommend that such refresh tokens be sender-constrained using [Proof of Possession](/identityserver/tokens/pop.md) instead. You can further reduce the attack surface of refresh tokens using the following techniques. @@ -123,7 +124,7 @@ to produce a new token, but the response containing the new refresh token is los application has no way to recover without the user logging in again. Reusable refresh tokens do not have this problem. Reusable tokens may have better performance in -the [persisted grants store](/identityserver/reference/stores/persisted-grant-store/). One-time use refresh tokens +the [persisted grants store](/identityserver/reference/stores/persisted-grant-store.md). One-time use refresh tokens require additional records to be written to the store whenever a token is refreshed. Using reusable refresh tokens avoids those writes. @@ -174,4 +175,4 @@ replay detection. The `PersistentGrantOptions.DeleteOneTimeOnlyRefreshTokensOnUs used tokens persist and can be used to detect replays. The cleanup job should also be configured to not delete consumed tokens. -See also: The [IRefreshTokenService](/identityserver/reference/services/refresh-token-service/) reference. +See also: The [IRefreshTokenService](/identityserver/reference/services/refresh-token-service.md) reference. diff --git a/src/content/docs/identityserver/tokens/requesting.md b/src/content/docs/identityserver/tokens/requesting.md index 9f5d0e715..325a89b9e 100644 --- a/src/content/docs/identityserver/tokens/requesting.md +++ b/src/content/docs/identityserver/tokens/requesting.md @@ -3,6 +3,7 @@ title: "Requesting a Token" description: "Guide explaining how to request tokens for both machine-to-machine communication and interactive applications, including code examples for .NET implementations" date: 2020-09-10T08:22:12+02:00 sidebar: + label: Requesting order: 10 redirect_from: - /identityserver/v5/tokens/requesting/ @@ -10,21 +11,25 @@ redirect_from: - /identityserver/v7/tokens/requesting/ --- -A typical architecture is composed of two application (aka client) [types](/identityserver/overview/terminology#client) - machine to machine calls and interactive applications. +A typical architecture is composed of two application (aka +client) [types](/identityserver/overview/terminology.md#client) - machine-to-machine calls and interactive applications. -## Machine to Machine Communication +## Machine-to-machine Communication -In this scenario a headless application with no interactive user (e.g. a server daemon, batch job etc.) wants to call an API. +In this scenario a headless application with no interactive user (e.g. a server daemon, batch job etc.) wants to call an +API. Prerequisites are: -* define a [client](/identityserver/fundamentals/clients) for the *client credentials* grant type -* define an [API scope](/identityserver/fundamentals/resources/api-scopes/) (and optionally a resource) -* grant the client access to the scope via the [`AllowedScopes`](/identityserver/reference/models/client#basics) property +* define a [client](/identityserver/fundamentals/clients.md) for the *client credentials* grant type +* define an [API scope](/identityserver/fundamentals/resources/api-scopes.md) (and optionally a resource) +* grant the client access to the scope via the [`AllowedScopes`](/identityserver/reference/models/client.md#basics) + property -According to the OAuth [specification](https://tools.ietf.org/html/rfc6749#section-4.4), you request a token by posting to the token endpoint: +According to the OAuth [specification](https://tools.ietf.org/html/rfc6749#section-4.4), you request a token by posting +to the token endpoint: -``` +```http request POST /connect/token CONTENT-TYPE application/x-www-form-urlencoded @@ -36,7 +41,7 @@ CONTENT-TYPE application/x-www-form-urlencoded In the success case, this will return a JSON response containing the access token: -``` +```http request HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store @@ -50,12 +55,15 @@ Pragma: no-cache ``` ### .NET Client Library -In .NET you can use the [Duende IdentityModel](../../../identitymodel) client library to [request](../../../identitymodel/endpoints/token) tokens. + +In .NET you can use the [Duende IdentityModel](../../../identitymodel) client library +to [request](../../../identitymodel/endpoints/token) tokens. The above token request would look like this in C#: -```cs -using IdentityModel.Client; +```csharp +// Program.cs +using Duende.IdentityModel.Client; var client = new HttpClient(); @@ -71,12 +79,15 @@ var response = await client.RequestClientCredentialsTokenAsync(new ClientCredent ### Automating Token Requests In ASP.NET Core And Worker Applications -The [Duende.AccessTokenManagement](/accesstokenmanagement) library can automate client credential request and token lifetime management for you. +The [Duende.AccessTokenManagement](/accesstokenmanagement) library can automate client credential request and token +lifetime management for you. Using this library, you can enable access token management for an HTTP client provided by `IHttpClientFactory`. -You can add the necessary services to ASP.NET Core's service provider by calling `AddClientCredentialsTokenManagement()`. One or more named client definitions need to be registered by calling `AddClient()`. +You can add the necessary services to ASP.NET Core's service provider by calling +`AddClientCredentialsTokenManagement()`. One or more named client definitions need to be registered by calling +`AddClient()`. -```cs +```csharp // Program.cs builder.Services.AddClientCredentialsTokenManagement() .AddClient("client", client => @@ -89,9 +100,10 @@ builder.Services.AddClientCredentialsTokenManagement() }); ``` -You can then register named HTTP clients with `IHttpClientFactory`. These named clients will automatically use the above client definitions to request and use access tokens. +You can then register named HTTP clients with `IHttpClientFactory`. These named clients will automatically use the above +client definitions to request and use access tokens. -```cs +```csharp // Program.cs builder.Services.AddClientAccessTokenHttpClient("client", configureClient: client => { @@ -101,7 +113,7 @@ builder.Services.AddClientAccessTokenHttpClient("client", configureClient: clien In your application code, you can then use the named HTTP client with automatic token management to call the API: -```cs +```csharp // DataController.cs public class DataController : Controller { @@ -123,23 +135,30 @@ public class DataController : Controller ## Interactive Applications -In this scenario, an interactive application like a web application or mobile/desktop app wants to call an API in the context of an authenticated user (see spec [here](https://openid.net/specs/openid-connect-core-1_0.html#codeflowauth)). +In this scenario, an interactive application like a web application or mobile/desktop app wants to call an API in the +context of an authenticated user (see spec [here](https://openid.net/specs/openid-connect-core-1_0.html#codeflowauth)). -You will receive three tokens - an identity token containing details about the end-user authentication, the access token to call the API, and a refresh token for access token lifetime management. The access token will also contain some information about the end-user (e.g. the user ID), so that the API can do authorization based on the user's identity. +You will receive three tokens - an identity token containing details about the end-user authentication, the access token +to call the API, and a refresh token for access token lifetime management. The access token will also contain some +information about the end-user (e.g. the user ID), so that the API can do authorization based on the user's identity. -In this scenario you typically use the authorization code flow which first involves a call to the authorize endpoint for all human interactions (e.g. login and/or consent). This returns a code, which you then redeem at the token endpoint to retrieve identity and access tokens. +In this scenario you typically use the authorization code flow which first involves a call to the authorize endpoint for +all human interactions (e.g. login and/or consent). This returns a code, which you then redeem at the token endpoint to +retrieve identity and access tokens. Prerequisites are: -* define a [client](/identityserver/fundamentals/clients/) for the *authorization code* grant type -* define an [identity](/identityserver/fundamentals/resources/identity/) resource, e.g. `openid` -* define an [API scope](/identityserver/fundamentals/resources/api-scopes/) (and optionally a resource) -* grant the client access to both scopes via the [`AllowedScopes`](/identityserver/reference/models/client#basics) property +* define a [client](/identityserver/fundamentals/clients.md) for the *authorization code* grant type +* define an [identity](/identityserver/fundamentals/resources/identity.md) resource, e.g. `openid` +* define an [API scope](/identityserver/fundamentals/resources/api-scopes.md) (and optionally a resource) +* grant the client access to both scopes via the [`AllowedScopes`](/identityserver/reference/models/client.md#basics) + property ### Front-channel + The call to the authorize endpoint is done using a redirect in the browser: -``` +```http request GET /connect/authorize? client_id=client1& scope=openid api1& @@ -147,18 +166,20 @@ GET /connect/authorize? redirect_uri=https://myapp/callback& ``` -On success, the browser will ultimately redirect to the callback endpoint transmitting the authorization code (and other parameters like the granted scopes): +On success, the browser will ultimately redirect to the callback endpoint transmitting the authorization code (and other +parameters like the granted scopes): -``` +```http request GET /callback? code=abc& scope=openid api1 ``` ### Back-channel + The client then opens a back-channel communication to the token service to retrieve the tokens: -``` +```http request POST /connect/token CONTENT-TYPE application/x-www-form-urlencoded @@ -171,7 +192,7 @@ CONTENT-TYPE application/x-www-form-urlencoded In this scenario, the token response will contain three tokens: -``` +```http request HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store @@ -187,26 +208,33 @@ Pragma: no-cache ``` :::note -See the refresh token section for more information on how to deal with [refresh tokens](/identityserver/tokens/refresh). +See the refresh token section for more information on how to deal with [refresh tokens](/identityserver/tokens/refresh.md). ::: ### .NET Client Library -The most common client library for .NET is the OpenID Connect [authentication](https://docs.microsoft.com/en-us/aspnet/core/security/authentication) handler for ASP.NET Core. This library handles the complete front- and back-channel interaction and coordination. + +The most common client library for .NET is the OpenID +Connect [authentication](https://docs.microsoft.com/en-us/aspnet/core/security/authentication) handler for ASP.NET Core. +This library handles the complete front- and back-channel interaction and coordination. You only need to configure it in your startup code: ```cs +// Program.cs +using Microsoft.IdentityModel.Tokens; + +var builder = WebApplication.CreateBuilder(args); builder.Services.AddAuthentication(options => -{ - options.DefaultScheme = "cookie"; - options.DefaultChallengeScheme = "duende"; -}) + { + options.DefaultScheme = "cookie"; + options.DefaultChallengeScheme = "duende"; + }) .AddCookie("cookie") .AddOpenIdConnect("duende", "IdentityServer", options => { options.Authority = "https://demo.duendesoftware.com"; options.ClientId = "interactive.confidential"; - + options.ResponseType = "code"; options.ResponseMode = "query"; options.SaveTokens = true; @@ -215,7 +243,7 @@ builder.Services.AddAuthentication(options => options.Scope.Add("openid"); options.Scope.Add("api"); options.Scope.Add("offline_access"); - + options.TokenValidationParameters = new TokenValidationParameters { NameClaimType = "name", @@ -228,4 +256,6 @@ builder.Services.AddAuthentication(options => ``` ### Automating Token Management In ASP.NET Core -The [Duende.AccessTokenManagement](/accesstokenmanagement) library can also be used to automate token lifetime management in ASP.NET Core applications for you. + +The [Duende.AccessTokenManagement](/accesstokenmanagement/index.mdx) library can also be used to automate token lifetime +management in ASP.NET Core applications for you. diff --git a/src/content/docs/identityserver/ui/ciba.md b/src/content/docs/identityserver/ui/ciba.md index 97fece22f..efc33a07f 100644 --- a/src/content/docs/identityserver/ui/ciba.md +++ b/src/content/docs/identityserver/ui/ciba.md @@ -2,6 +2,7 @@ title: "Client Initiated Backchannel Authentication (CIBA)" description: "Documentation for implementing CIBA in IdentityServer, a workflow that allows users to authenticate on a trusted device while accessing services from a different device." sidebar: + label: CIBA order: 7 redirect_from: - /identityserver/v5/ui/ciba/ diff --git a/src/content/docs/identityserver/ui/login/external.md b/src/content/docs/identityserver/ui/login/external.md index f64a40040..1813bc927 100644 --- a/src/content/docs/identityserver/ui/login/external.md +++ b/src/content/docs/identityserver/ui/login/external.md @@ -2,6 +2,7 @@ title: "Integrating with External Providers" description: "Guide to integrating external identity providers with IdentityServer, including registration of authentication handlers, triggering authentication flows, and processing callbacks from social or corporate login systems." sidebar: + label: External Providers order: 60 redirect_from: - /identityserver/v5/ui/login/external/ diff --git a/src/content/docs/identityserver/ui/login/local.md b/src/content/docs/identityserver/ui/login/local.md index 88e441a11..7d30d82a0 100644 --- a/src/content/docs/identityserver/ui/login/local.md +++ b/src/content/docs/identityserver/ui/login/local.md @@ -2,6 +2,7 @@ title: "Accepting Local Credentials" description: "Guide to implementing a local login page in IdentityServer that validates username/password credentials, issues authentication cookies, and includes a sample Razor Page implementation." sidebar: + label: Local Credentials order: 50 redirect_from: - /identityserver/v5/ui/login/local/ diff --git a/src/content/docs/identityserver/ui/login/redirect.md b/src/content/docs/identityserver/ui/login/redirect.md index cc2f0d5c6..a90193528 100644 --- a/src/content/docs/identityserver/ui/login/redirect.md +++ b/src/content/docs/identityserver/ui/login/redirect.md @@ -1,7 +1,8 @@ --- -title: "Redirecting back to the client" +title: "Redirecting Back To The Client" description: "Guide to safely redirecting users back to client applications after login in IdentityServer, using the returnUrl parameter while protecting against open-redirect attacks and maintaining state throughout the authentication workflow." sidebar: + label: Redirects order: 30 redirect_from: - /identityserver/v5/ui/login/redirect/ diff --git a/src/content/docs/identityserver/ui/logout/client-redirect.md b/src/content/docs/identityserver/ui/logout/client-redirect.md index ad1b9a0c4..9e8864d5c 100644 --- a/src/content/docs/identityserver/ui/logout/client-redirect.md +++ b/src/content/docs/identityserver/ui/logout/client-redirect.md @@ -2,6 +2,7 @@ title: "Returning to the Client" description: "Guide to properly redirecting users back to client applications after logout in IdentityServer, ensuring front-channel notifications are processed correctly." sidebar: + label: Client Return order: 60 redirect_from: - /identityserver/v5/ui/logout/client_redirect/ diff --git a/src/content/docs/identityserver/ui/logout/external-notification.md b/src/content/docs/identityserver/ui/logout/external-notification.md index 6adde3730..76b6efb5a 100644 --- a/src/content/docs/identityserver/ui/logout/external-notification.md +++ b/src/content/docs/identityserver/ui/logout/external-notification.md @@ -2,6 +2,7 @@ title: "External Logout Notification" description: "Documentation on federated sign-out in IdentityServer, explaining how external identity provider logout notifications are automatically processed to sign users out across all connected applications." sidebar: + label: External Logout Notification order: 80 redirect_from: - /identityserver/v5/ui/logout/external_notification/ diff --git a/src/content/docs/identityserver/ui/logout/external.md b/src/content/docs/identityserver/ui/logout/external.md index 0bbb5a528..34f617cf5 100644 --- a/src/content/docs/identityserver/ui/logout/external.md +++ b/src/content/docs/identityserver/ui/logout/external.md @@ -2,6 +2,7 @@ title: "External Logout" description: "Guide to implementing logout from external identity providers in IdentityServer, including detecting provider usage, redirecting users for sign-out, and maintaining state across the redirect flow." sidebar: + label: External Logout order: 70 redirect_from: - /identityserver/v5/ui/logout/external/ diff --git a/src/content/docs/identityserver/ui/logout/session-cleanup.md b/src/content/docs/identityserver/ui/logout/session-cleanup.md index 083a6fdd2..7ada4c2bd 100644 --- a/src/content/docs/identityserver/ui/logout/session-cleanup.md +++ b/src/content/docs/identityserver/ui/logout/session-cleanup.md @@ -1,7 +1,8 @@ --- -title: "Ending the Session" +title: "Session Cleanup and Logout" description: "Guide to correctly ending a session in IdentityServer, including removing authentication cookies, handling external logins, and revoking client tokens during logout." sidebar: + label: End Sessions order: 20 redirect_from: - /identityserver/v5/ui/logout/session_cleanup/ @@ -17,19 +18,27 @@ To remove the authentication cookie, use the ASP.NET Core `SignOutAsync` extensi You will need to pass the scheme used (which is provided by `IdentityServerConstants.DefaultCookieAuthenticationScheme` unless you have changed it): -```cs -await HttpContext.SignOutAsync(IdentityServerConstants.DefaultCookieAuthenticationScheme); +```csharp +// LogOut.cshtml.cs +await HttpContext.SignOutAsync( + Duende + .IdentityServer + .IdentityServerConstants + .DefaultCookieAuthenticationScheme +); ``` Or you can use the overload that will sign out of the default authentication scheme: -```cs +```csharp +// LogOut.cshtml.cs await HttpContext.SignOutAsync(); ``` If you are integrating with ASP.NET Identity, sign out using its `SignInManager` instead: -```cs +```csharp +// LogOut.cshtml.cs await _signInManager.SignOutAsync(); ```