Duende IdentityServer

https://docs.duendesoftware.com/identityserver/
Admin
Duende IdentityServer is a highly extensible, standards-compliant framework for implementing OpenID...
Tokens:557,030
Snippets:4,206
Trust Score:9.4
Update:5 hours ago
Show doc for...
Tokens:
Raw
### Install Duende.Templates

Source: https://docs.duendesoftware.com/identityserver/quickstarts/0-overview/

Installs the Duende.Templates package, which serves as the starting point for the quickstart tutorials.

```terminal
dotnet new install Duende.Templates
```

--------------------------------

### Install Duende Storage NuGet packages with dotnet CLI

Source: https://docs.duendesoftware.com/identityserver/data/providers/duende-storage/getting-started/

Use these commands to install the IdentityServer preview package and the SQLite storage provider. The --prerelease flag is required to get the preview versions.

```bash
dotnet add package Duende.IdentityServer --prerelease
dotnet add package Duende.Storage.Sqlite --prerelease
```

--------------------------------

### ConfigureServices method in Startup.cs

Source: https://docs.duendesoftware.com/identityserver/quickstarts/1-client-credentials/

Minimal ConfigureServices method that configures IdentityServer with in-memory API scopes and clients. This is the required setup for the client credentials quickstart. The method is called from Program.cs and returns the built WebApplication.

```csharp
public static WebApplication ConfigureServices(this WebApplicationBuilder builder)
{
    // Can also be found in Program.cs
    builder.Services.AddIdentityServer()
        .AddInMemoryApiScopes(Config.ApiScopes)
        .AddInMemoryClients(Config.Clients);

    return builder.Build();
}
```

--------------------------------

### Create solution directory structure

Source: https://docs.duendesoftware.com/identityserver/quickstarts/1-client-credentials/

Creates the quickstart root directory, a src subdirectory, and a solution file named Quickstart. Run from the console.

```bash
mkdir quickstart
cd quickstart
mkdir src
dotnet new sln -n Quickstart
```

--------------------------------

### Install mkcert binary on Linux

Source: https://docs.duendesoftware.com/identityserver/tokens/mtls-setup/

Download the mkcert binary and install it to /usr/local/bin.

```shell
sudo install mkcert-v*-linux-amd64 /usr/local/bin/mkcert
```

--------------------------------

### Install Duende.Spaces Packages

Source: https://docs.duendesoftware.com/identityserver/spaces/getting-started/

Run these dotnet CLI commands to add the required NuGet packages for Spaces with SQLite storage. Use the --prerelease flag to get the latest prerelease versions.

```bash
dotnet add package Duende.IdentityServer --prerelease
dotnet add package Duende.Storage.Sqlite --prerelease
dotnet add package Duende.Spaces --prerelease
```

--------------------------------

### Create IdentityServer project with isempty template

Source: https://docs.duendesoftware.com/identityserver/quickstarts/1-client-credentials/

Uses the duende-is-empty template to create a web project named IdentityServer with the IdentityServer package installed and minimal configuration. Run from the quickstart directory.

```bash
cd src
dotnet new duende-is-empty -n IdentityServer
```

--------------------------------

### Architecture Diagram for MCP Quickstart

Source: https://docs.duendesoftware.com/identityserver/quickstarts/8-mcp/

Shows the architecture of the quickstart: the client signs in through IdentityServer and calls the MCP server.

```mermaid
architecture-beta
    service mcpServer(server)[MCP Server]
    service client(server)[Client]
    service is(server)[IdentityServer]

    is:L -- R:mcpServer
    mcpServer:R -- L:client
```

--------------------------------

### Add IdentityServer project to solution

Source: https://docs.duendesoftware.com/identityserver/quickstarts/1-client-credentials/

Adds the IdentityServer project to the Quickstart solution. Run from the quickstart directory after creating the project.

```bash
cd ..
dotnet sln add ./src/IdentityServer
```

--------------------------------

### Install Duende.Storage.MsSql package

Source: https://docs.duendesoftware.com/identityserver/identity/user-management/fundamentals/storage/

Run this command to install the SQL Server storage package for IdentityServer User Management.

```bash
dotnet add package Duende.Storage.MsSql
```

--------------------------------

### Add Quickstart UI with dotnet new duende-is-ui

Source: https://docs.duendesoftware.com/identityserver/quickstarts/2-interactive/

Run this command from the src/IdentityServer directory to add the Razor Pages-based quickstart UI to the project. This UI provides login, logout, consent, and error pages.

```bash
dotnet new duende-is-ui
```

--------------------------------

### Install Duende.IdentityServer.ConformanceReport NuGet package

Source: https://docs.duendesoftware.com/identityserver/diagnostics/conformance-report/

Run this command to install the Duende.IdentityServer.ConformanceReport NuGet package, which provides the conformance report feature.

```bash
dotnet add package Duende.IdentityServer.ConformanceReport
```

--------------------------------

### Install NuGet packages for BFF and OIDC

Source: https://docs.duendesoftware.com/identityserver/quickstarts/javascript-clients/js-with-backend/

Run these commands from the src/JavaScriptClient directory to install the required packages for OpenID Connect, BFF, and YARP.

```terminal
dotnet add package Microsoft.AspNetCore.Authentication.OpenIdConnect
dotnet add package Duende.BFF
dotnet add package Duende.BFF.Yarp
```

--------------------------------

### Install Duende.Storage.PostgreSql Package

Source: https://docs.duendesoftware.com/identityserver/identity/user-management/fundamentals/storage/

Installs the PostgreSQL storage package via the .NET CLI. Required before configuring PostgreSQL storage.

```bash
dotnet add package Duende.Storage.PostgreSql
```

--------------------------------

### Install EF Core CLI and Design Package

Source: https://docs.duendesoftware.com/identityserver/quickstarts/4-entity-framework/

Run these commands from the src/IdentityServer directory to install the Entity Framework Core CLI tool globally and add the Microsoft.EntityFrameworkCore.Design NuGet package to the IdentityServer project.

```bash
dotnet tool install --global dotnet-ef
dotnet add package Microsoft.EntityFrameworkCore.Design
```

--------------------------------

### TOTP Setup Flow Sequence Diagram

Source: https://docs.duendesoftware.com/identityserver/identity/user-management/authentication/totp/

Sequence diagram illustrating the two-step setup flow: generating and displaying the secret, then verifying the user's authenticator app. Shows interactions between the user, app, and user management service.

```mermaid
sequenceDiagram
    actor User
    participant App
    participant UserManagement as User Management

    User->>App: Request to enable TOTP
    App->>UserManagement: Generate TOTP secret key
    UserManagement-->>App: Secret key + QR code URI
    App-->>User: Display QR code
    User->>User: Scan QR code with authenticator app
    User->>App: Enter verification code
    App->>UserManagement: TryAddTotpDeviceAsync(subjectId, name, key, code)
    UserManagement-->>App: Success
    App->>UserManagement: TryCreateRecoveryCodesAsync()
    UserManagement-->>App: Recovery codes
    App-->>User: Show recovery codes
```

--------------------------------

### Add Serilog.Sinks.Seq package

Source: https://docs.duendesoftware.com/identityserver/diagnostics/events/

Command to install the Serilog.Sinks.Seq package into the host project. Required for the SeqEventSink example.

```bash
dotnet add package Serilog.Sinks.Seq
```

--------------------------------

### Create Directory for MCP Quickstart Projects

Source: https://docs.duendesoftware.com/identityserver/quickstarts/8-mcp/

Commands to create and enter the directory that will hold the three projects.

```bash
mkdir mcp-quickstart
cd mcp-quickstart
```

--------------------------------

### Add Azure Key Vault and Azure Identity packages

Source: https://docs.duendesoftware.com/identityserver/fundamentals/key-management/

Install the required NuGet packages for using Azure Key Vault with IdentityServer's asynchronous signing example.

```bash
dotnet add package Azure.Security.KeyVault.Keys
dotnet add package Azure.Identity
```

--------------------------------

### Create Client Console Application

Source: https://docs.duendesoftware.com/identityserver/quickstarts/8-mcp/

Creates a new console project named McpQuickStart.Client in its own directory.

```bash
dotnet new console --name "McpQuickStart.Client"
```

--------------------------------

### Create solution and add projects for Visual Studio or Rider

Source: https://docs.duendesoftware.com/identityserver/quickstarts/7-blazor/

If using Visual Studio or Rider, create a solution file named BlazorQuickstart and add both the BlazorWasm and BFF projects to it.

```bash
dotnet new sln -n BlazorQuickstart
dotnet sln add BlazorWasm/BlazorWasm.csproj
dotnet sln add BFF/BFF.csproj
```

--------------------------------

### Add and configure the client configuration store

Source: https://docs.duendesoftware.com/identityserver/configuration/dcr/

Install the Entity Framework Core implementation package and register it with AddClientConfigurationStore, then configure the connection string for the configuration store.

```bash
dotnet add package Duende.IdentityServer.Configuration.EntityFramework
```

--------------------------------

### End Session Endpoint URL Example

Source: https://docs.duendesoftware.com/identityserver/reference/v8/endpoints/end-session/

Shows the HTTP GET request to the end session endpoint with `id_token_hint` and `post_logout_redirect_uri` query parameters. The `post_logout_redirect_uri` must match a pre-configured `PostLogoutRedirectUris` value.

```http
GET /connect/endsession?id_token_hint=...&post_logout_redirect_uri=http%3A%2F%2Flocalhost%3A7017%2Findex.html
```

--------------------------------

### Basic SQL Server storage setup in Program.cs

Source: https://docs.duendesoftware.com/identityserver/identity/user-management/fundamentals/storage/

Registers the SQL Server connection factory and selects the SQL Server provider for the default storage instance. Initializes the database schema on startup using MigrateAsync, which is convenient for development but not recommended for production.

```csharp
using Duende.IdentityServer;
using Duende.Storage.Schema;
using Duende.Storage.MsSql;
using Microsoft.Data.SqlClient;

var builder = WebApplication.CreateBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("mssql")!;
builder.Services.AddSingleton<CreateSqlConnection>(() => new SqlConnection(connectionString));

builder.Services
    .AddIdentityServer()
    .AddStorage(storage => storage.AddMsSql(options => { }))
    .AddUserManagement(um => { /* ... */ });

var app = builder.Build();

// Initialize the database schema on startup.
using (var scope = app.Services.CreateScope())
{
    var schemaFactory = scope.ServiceProvider.GetRequiredService<IStorageInstanceSchemaFactory>();
    var schema = await schemaFactory.GetStorageInstanceSchema(CancellationToken.None);
    await schema.MigrateAsync(CancellationToken.None);
}

app.Run();
```

--------------------------------

### Initial Program.cs setup for BFF

Source: https://docs.duendesoftware.com/identityserver/quickstarts/7-blazor/

Sets up the minimal BFF application that serves the Blazor app. The call to MapFallbackToFile renders the Blazor entry point. Both projects must run on the same site because the session cookie uses samesite=strict to protect against CSRF attacks.

```csharp
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapStaticAssets();
app.MapFallbackToFile("index.html");
app.Run();
```

--------------------------------

### Configure all OpenID Connect handlers with AddOidcStateDataFormatterCache

Source: https://docs.duendesoftware.com/identityserver/ui/login/external/

Call AddOidcStateDataFormatterCache without parameters to configure all OpenID Connect handlers to persist state in the server-side IDistributedCache. This example shows the setup with three handlers: demoidsrv, aad, and adfs.

```csharp
// configures the OpenIdConnect handlers to persist the state parameter into the server-side IDistributedCache.
builder.Services.AddOidcStateDataFormatterCache();

builder.Services.AddAuthentication()
    .AddOpenIdConnect("demoidsrv", "IdentityServer", options =>
    {
        // ...
    })
    .AddOpenIdConnect("aad", "Azure AD", options =>
    {
        // ...
    })
    .AddOpenIdConnect("adfs", "ADFS", options =>
    {
        // ...
    });
```

--------------------------------

### InitializeDatabase method to create and seed database

Source: https://docs.duendesoftware.com/identityserver/quickstarts/4-entity-framework/

Add this method to HostingExtensions.cs to create the database from migrations and seed it with configuration data from Config.Clients, Config.IdentityResources, and Config.ApiScopes. It uses PersistedGrantDbContext and ConfigurationDbContext. The method is intended for quickstart setup; consider removing the call once the database is populated.

```csharp
private static void InitializeDatabase(IApplicationBuilder app)
{
    using (var serviceScope = app.ApplicationServices.GetService<IServiceScopeFactory>()!.CreateScope())
    {
        serviceScope.ServiceProvider.GetRequiredService<PersistedGrantDbContext>().Database.Migrate();

        var context = serviceScope.ServiceProvider.GetRequiredService<ConfigurationDbContext>();
        context.Database.Migrate();
        if (!context.Clients.Any())
        {
            foreach (var client in Config.Clients)
            {
                context.Clients.Add(client.ToEntity());
            }
            context.SaveChanges();
        }

        if (!context.IdentityResources.Any())
        {
            foreach (var resource in Config.IdentityResources)
            {
                context.IdentityResources.Add(resource.ToEntity());
            }
            context.SaveChanges();
        }

        if (!context.ApiScopes.Any())
        {
            foreach (var resource in Config.ApiScopes)
            {
                context.ApiScopes.Add(resource.ToEntity());
            }
            context.SaveChanges();
        }
    }
}
```

--------------------------------

### Install Duende CLI and Run Storage Migrations

Source: https://docs.duendesoftware.com/identityserver/data/providers/duende-storage/getting-started/

Install the Duende CLI globally, set the connection string, and run storage migrations for SQL Server. Use --dry-run to review SQL without applying changes. For other providers, use postgresql or sqlite. Add --schema for non-default schemas.

```bash
# Terminal
dotnet tool install --global Duende.Cli --prerelease
$env:DUENDE_STORAGE_CONNECTION_STRING = "<deployment-connection-string>"

duende storage migrate --provider mssql --dry-run
duende storage migrate --provider mssql
```

--------------------------------

### Configure Operational Store with AddOperationalStore

Source: https://docs.duendesoftware.com/identityserver/data/providers/entityframework-core/

Use the AddOperationalStore extension method after AddIdentityServer to configure the operational store. The example sets up SQL Server with a migrations assembly, enables token cleanup, and sets the cleanup interval to 3600 seconds. Note that starting with IdentityServer 8.1.0-preview.4, this method is named AddEntityFrameworkOperationalStore and AddOperationalStore is marked obsolete.

```csharp
const string connectionString = @"Data Source=(LocalDb)\MSSQLLocalDB;database=YourIdentityServerDatabase;trusted_connection=yes;";
var migrationsAssembly = typeof(Program).GetTypeInfo().Assembly.GetName().Name;

builder.Services.AddIdentityServer()
    // this adds the operational data from DB (codes, tokens, consents)
    .AddOperationalStore(options =>
    {
        options.ConfigureDbContext = builder =>
            builder.UseSqlServer(connectionString,
                sql => sql.MigrationsAssembly(migrationsAssembly));

        // this enables automatic token cleanup. this is optional.
        options.EnableTokenCleanup = true;
        options.TokenCleanupInterval = 3600; // interval in seconds (default is 3600)
    });
```

--------------------------------

### Install mkcert via Homebrew

Source: https://docs.duendesoftware.com/identityserver/tokens/mtls-setup/

Install mkcert on macOS using Homebrew.

```shell
brew install mkcert
```

--------------------------------

### Install mkcert via Chocolatey

Source: https://docs.duendesoftware.com/identityserver/tokens/mtls-setup/

Install mkcert on Windows using Chocolatey package manager.

```shell
choco install mkcert
```

--------------------------------

### McpQuickStart.McpServer.csproj with NuGet packages

Source: https://docs.duendesoftware.com/identityserver/quickstarts/8-mcp/

The .csproj file after adding the latest versions of Microsoft.AspNetCore.Authentication.JwtBearer and ModelContextProtocol.AspNetCore NuGet packages. Includes Microsoft.AspNetCore.OpenApi.

```xml
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.10" />
    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.10"  />
    <PackageReference Include="ModelContextProtocol.AspNetCore" Version="2.1.0" />
  </ItemGroup>
</Project>
```

--------------------------------

### Install mkcert via WinGet

Source: https://docs.duendesoftware.com/identityserver/tokens/mtls-setup/

Install mkcert on Windows using WinGet package manager.

```shell
winget install FiloSottile.mkcert
```

--------------------------------

### Custom Validator Example

Source: https://docs.duendesoftware.com/identityserver/saml/extensibility/

Example of extending DefaultSamlServiceProviderConfigurationValidator to require the 'openid' scope for all service providers.

```APIDOC
## Custom Validator Example

### Description
Extends `DefaultSamlServiceProviderConfigurationValidator` by overriding `ValidateAllowedScopesAsync` to require that every SP includes the `openid` scope.

### Example
```csharp
public class CustomSamlServiceProviderConfigurationValidator : DefaultSamlServiceProviderConfigurationValidator
{
    protected override async Task ValidateAllowedScopesAsync(SamlServiceProviderConfigurationValidationContext context)
    {
        // Run the default scope check first
        await base.ValidateAllowedScopesAsync(context);
        if (!context.IsValid)
            return;

        // Custom rule: all SPs must include the "openid" scope
        if (!context.ServiceProvider.AllowedScopes.Contains("openid"))
        {
            context.SetError("AllowedScopes must include 'openid'.");
        }
    }
}
```

```

--------------------------------

### Install NSS tools via apt

Source: https://docs.duendesoftware.com/identityserver/tokens/mtls-setup/

Install NSS tools on Linux for browser and Firefox trust.

```shell
sudo apt install libnss3-tools
```

--------------------------------

### Create a new empty web application project

Source: https://docs.duendesoftware.com/identityserver/configuration/dcr/

Use the .NET CLI to create a new empty web application named 'Configuration'.

```bash
dotnet new web -n Configuration
```

--------------------------------

### Install NSS tools via Homebrew

Source: https://docs.duendesoftware.com/identityserver/tokens/mtls-setup/

Install NSS tools on macOS for Firefox trust support.

```shell
brew install nss
```

--------------------------------

### Sample output of dotnet list package

Source: https://docs.duendesoftware.com/identityserver/upgrades/identityserver4-to-duende-identityserver-v8/

Example output showing IdentityServer4 and IdentityServer4.EntityFramework packages with version 3.1.4.

```text
   > IdentityServer4                            3.1.4       3.1.4
   > IdentityServer4.EntityFramework            3.1.4       3.1.4
```

--------------------------------

### Create WebClient project and add to solution

Source: https://docs.duendesoftware.com/identityserver/quickstarts/2-interactive/

Run these commands from the src directory to create a new ASP.NET web app named WebClient and add it to the solution.

```bash
dotnet new webapp -n WebClient
cd ..
dotnet sln add ./src/WebClient
```

--------------------------------

### Create ASP.NET Web API project for MCP server

Source: https://docs.duendesoftware.com/identityserver/quickstarts/8-mcp/

Run this command in a terminal to create a new ASP.NET Web API project named 'McpQuickStart.McpServer' in its own directory inside 'mcp-quickstart'.

```bash
dotnet new webapi --name "McpQuickStart.McpServer"
```

--------------------------------

### Install Duende.IdentityServer.EntityFramework NuGet package

Source: https://docs.duendesoftware.com/identityserver/data/providers/entityframework-core/

Use this command to add the EntityFramework integration package to your project.

```bash
dotnet add package Duende.IdentityServer.EntityFramework
```

--------------------------------

### Authorize Request URL Example

Source: https://docs.duendesoftware.com/identityserver/reference/v8/endpoints/authorize/

Example of an authorize request URL with required and optional parameters, including client_id, scope, response_type, redirect_uri, state, and nonce.

```http
GET /connect/authorize?
    client_id=client1&
    scope=openid email api1&
    response_type=id_token token&
    redirect_uri=https://myapp/callback&
    state=abc&
    nonce=xyz
```
Tokens:
Raw