Authentication complete

You can close this window now.

` container used to show messages to the user
* a `
  

```

*`app.js`*

The app.js file will contain the client-side code for your application.

First, add a helper function to display messages in the `
`:

```js
function log() {
  document.getElementById("results").innerText = "";


  Array.prototype.forEach.call(arguments, function (msg) {
    if (typeof msg !== "undefined") {
      if (msg instanceof Error) {
        msg = "Error: " + msg.message;
      } else if (typeof msg !== "string") {
        msg = JSON.stringify(msg, null, 2);
      }
      document.getElementById("results").innerText += msg + "\r\n";
    }
  });
}
```

Next, you can use the BFF `user` management endpoint to query if the user is logged in or not. Notice the `userClaims` variable is global; it will be needed elsewhere.

```js
let userClaims = null;


(async function () {
  var req = new Request("/bff/user", {
    headers: new Headers({
      "X-CSRF": "1",
    }),
  });


  try {
    var resp = await fetch(req);
    if (resp.ok) {
      userClaims = await resp.json();


      log("user logged in", userClaims);
    } else if (resp.status === 401) {
      log("user not logged in");
    }
  } catch (e) {
    log("error checking user status");
  }
})();
```

Next, register `click` event handlers on the buttons:

```js
document.getElementById("login").addEventListener("click", login, false);
document.getElementById("local").addEventListener("click", localApi, false);
document.getElementById("remote").addEventListener("click", remoteApi, false);
document.getElementById("logout").addEventListener("click", logout, false);
```

Next, implement the `login` and `logout` functions.

Login is simple - just redirect the user to the BFF `login` endpoint.

```js
function login() {
  window.location = "/bff/login";
}
```

Logout is more involved, as you need to redirect the user to the BFF `logout` endpoint, which requires an anti-forgery token to prevent cross site request forgery attacks. The `userClaims` that you populated earlier contain that token and the full logout URL in its `bff:logout_url` claim, so redirect to that url:

```plaintext
function logout() {
  if (userClaims) {
    var logoutUrl = userClaims.find(
      (claim) => claim.type === "bff:logout_url"
    ).value;
    window.location = logoutUrl;
  } else {
    window.location = "/bff/logout";
  }
}
```

Finally, add empty stubs for the other button event handler functions. You will implement those after you get login and logout working.

```js
async function localApi() {}


async function remoteApi() {}
```

## Add JavaScript Client Registration To IdentityServer

[Section titled “Add JavaScript Client Registration To IdentityServer”](#add-javascript-client-registration-to-identityserver)

Now that the client application is ready to go, you need to define a configuration entry in IdentityServer for the new JavaScript client.

In the IdentityServer project locate the client configuration in `src/IdentityServer/Config.cs`. Add a new `Client` to the list for your new JavaScript application. Because this client uses the BFF pattern, the configuration will be very similar to the Web client. In addition, requesting the offline\_access scope should be allowed for this client. It should have the configuration listed below:

```csharp
// JavaScript BFF client
new Client
{
    ClientId = "bff",
    ClientSecrets = { new Secret("secret".Sha256()) },


    AllowedGrantTypes = GrantTypes.Code,


    // where to redirect to after login
    RedirectUris = { "https://localhost:5003/signin-oidc" },


    // where to redirect to after logout
    PostLogoutRedirectUris = { "https://localhost:5003/signout-callback-oidc" },
    AllowOfflineAccess = true,


    AllowedScopes = new List
    {
        IdentityServerConstants.StandardScopes.OpenId,
        IdentityServerConstants.StandardScopes.Profile,
        "api1"
    }
}
```

## Run And Test Login And Logout

[Section titled “Run And Test Login And Logout”](#run-and-test-login-and-logout)

At this point, you should be able to run the `JavaScriptClient` application. You should see that the user is not logged in initially.

![A simple javascript client with multiple action buttons](/_astro/jsbff_not_logged_in.CdU2CJD4_ZC2tC7.webp)

When you click the login button, you’ll be redirected to IdentityServer to login. After you log in, you’ll be redirected back to the `JavaScriptClient` application, where you’ll be signed in with the Cookies authentication scheme with your tokens saved in the session.

The app loads again, but this time it has a session cookie. So, when it makes the HTTP request to get userClaims, that cookie is included in the request. This allows the BFF middleware to authenticate the user and return user info. Once the `JavaScriptClient` application receives the response, the user should appear logged in and their claims should be displayed.

![showing claims after the login action is invoked](/_astro/jsbff_logged_in.Dmunfv6t_peHEJ.webp)

Finally, the logout button should successfully get the user logged out.

![showing the logout view on IdentityServer](/_astro/jsbff_signed_out.C6LecfKJ_Z2vDWkI.webp)

## Add API Support

[Section titled “Add API Support”](#add-api-support)

Now that you have login and logout working, you will add support to invoke both local and remote APIs.

A local API is an endpoint that is hosted in the same backend as the `JavaScriptClient` application. Local APIs are intended to be APIs that only exist to support the JavaScript frontend, typically by providing UI specific data or aggregating data from other sources. Local APIs are authenticated with the user’s session cookie.

A remote API is an API running in some other host than the `JavaScriptClient` application. This is useful for APIs that are shared by many different applications (e.g. mobile app, other web apps, etc.). Remote APIs are authenticated with an access token. Fortunately, the `JavaScriptClient` application has an access token stored in the user’s session. You will use the BFF proxy feature to accept a call from the JavaScript running in the browser authenticated with the user’s session cookie, retrieve the access token for the user from the user’s session, and then proxy the call to the remote API, sending the access token for authentication.

### Define A Local API

[Section titled “Define A Local API”](#define-a-local-api)

Local APIs can be defined using controllers or with [Minimal API Route Handlers](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis?view=aspnetcore-8.0#route-handlers). For simplicity, this quickstart uses a minimal API with its handler defined directly in `Program.cs`, but you can organize your Local APIs however you like.

Add a handler to `src/JavaScriptClient/Program.cs` for the local API:

```csharp
[Authorize]
static IResult LocalIdentityHandler(ClaimsPrincipal user)
{
    var name = user.FindFirst("name")?.Value ?? user.FindFirst("sub")?.Value;
    return Results.Json(new { message = "Local API Success!", user = name });
}
```

Note

Local APIs often make requests to remote APIs that are authorized with the user’s access token. To get the access token, call the `GetUserAccessTokenAsync` extension method on the `HttpContext`. For example: *var token = await HttpContext.GetUserAccessTokenAsync();*

### Update Routing To Accept Local And Remote API Calls

[Section titled “Update Routing To Accept Local And Remote API Calls”](#update-routing-to-accept-local-and-remote-api-calls)

Next, you need to register both the local API and the BFF proxy for the remote API in the ASP.NET Core routing system. Add the code below to the endpoint configuration code in `src/JavaScriptClient/Program.cs`.

```csharp
  app.MapBffManagementEndpoints();


  // Uncomment this for Controller support
  // app.MapControllers()
  //     .AsBffApiEndpoint();


  app.MapGet("/local/identity", LocalIdentityHandler)
      .AsBffApiEndpoint();


  app.MapRemoteBffApiEndpoint("/remote", new Uri("https://localhost:6001"))
      .WithAccessToken(RequiredTokenType.User);
```

The call to the `AsBffApiEndpoint()` fluent helper method adds BFF support to the local APIs. This includes anti-forgery protection and suppressing login redirects on authentication failures and instead returning 401 and 403 status codes under the appropriate circumstances.

`MapRemoteBffApiEndpoint()` registers the BFF proxy for the remote API and configures it to pass the user’s access token.

### Call The APIs From JavaScript

[Section titled “Call The APIs From JavaScript”](#call-the-apis-from-javascript)

Back in `src/JavaScriptClient/wwwroot/app.js`, implement the two API button event handlers like this:

```js
async function localApi() {
  var req = new Request("/local/identity", {
    headers: new Headers({
      "X-CSRF": "1",
    }),
  });


  try {
    var resp = await fetch(req);


    let data;
    if (resp.ok) {
      data = await resp.json();
    }
    log("Local API Result: " + resp.status, data);
  } catch (e) {
    log("error calling local API");
  }
}


async function remoteApi() {
  var req = new Request("/remote/identity", {
    headers: new Headers({
      "X-CSRF": "1",
    }),
  });


  try {
    var resp = await fetch(req);


    let data;
    if (resp.ok) {
      data = await resp.json();
    }
    log("Remote API Result: " + resp.status, data);
  } catch (e) {
    log("error calling remote API");
  }
}
```

The path for the local API is exactly what you set in the call to `MapGet` in `src/JavaScriptClient/Program.cs`.

The path for the remote API uses a “/remote” prefix to indicate that the BFF proxy should be used, and the remaining path is what’s then passed when invoking the remote API (“/identity” in this case).

Notice both API calls require an *‘X-CSRF’: ‘1’* header, which acts as the anti-forgery token.

Note

See the [client credentials quickstart](/identityserver/quickstarts/1-client-credentials/) for information on how to create the remote API used in the code above.

## Run And Test The API Calls

[Section titled “Run And Test The API Calls”](#run-and-test-the-api-calls)

At this point, you should be able to run the `JavaScriptClient` application and invoke the APIs. The local API should return something like this:

![showing a successful JavaScript fetch call to an API endpoint](/_astro/jsbff_local_api.D6JHzKis_2gRn2k.webp)

And the remote API should return something like this:

![showing a successful JavaScript call to a remote api hosted in BFF](/_astro/jsbff_remote_api.BmDJGtvt_Z20u7nQ.webp)

You now have the start of a JavaScript client application that uses IdentityServer for sign-in, sign-out, and authenticating calls to local and remote APIs, using `Duende.BFF`.
-----
# JavaScript Applications Without A Backend

> Learn how to build a client-side JavaScript application that interacts directly with IdentityServer for authentication and API access without a backend server.

Note

We recommend you do the quickstarts in order. If you’d like to start here, begin from a copy of the [reference implementation of Quickstart 3](https://github.com/DuendeSoftware/Samples/tree/main/IdentityServer/v8/Quickstarts/3_AspNetCoreAndApis). Throughout this quickstart, paths are written relative to the base `quickstart` directory created in part 1, which is the root directory of the reference implementation. You will also need to [install the IdentityServer templates](/identityserver/quickstarts/0-overview/#preparation).

This quickstart will show how to build a browser-based JavaScript client application without a backend. This means your application has no server-side code that can support the frontend application code, and thus all OpenID Connect/OAuth protocol interactions occur from the JavaScript code running in the browser. Also, invoking the API will be performed directly from the JavaScript in the browser.

**This design has security concerns. It is no longer recommended.** See [overview](/identityserver/quickstarts/javascript-clients/) for details. The current best practice uses the [“BFF” pattern](/identityserver/quickstarts/javascript-clients/js-with-backend/).

In this quickstart the user will log in to IdentityServer, invoke an API with an access token issued by IdentityServer, and logout of IdentityServer. All of this will be driven from the JavaScript running in the browser.

## New Project For The JavaScript Client

[Section titled “New Project For The JavaScript Client”](#new-project-for-the-javascript-client)

Create a new project for the JavaScript application. Beyond being able to serve your application’s HTML and javascript, there are no requirements on the backend. You could use anything from an empty ASP.NET Core application to a Node.js application. This quickstart will use an ASP.NET Core application.

Create a new ASP.NET Core web application and add it to the solution by running the following commands from the `src` directory:

```console
dotnet new web -n JavaScriptClient
cd ..
dotnet sln add ./src/JavaScriptClient
```

### Modify Hosting

[Section titled “Modify Hosting”](#modify-hosting)

Modify the `JavaScriptClient` project to run on `https://localhost:5003`. Its `Properties/launchSettings.json` should look like this:

```json
{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "JavaScriptClient": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5003",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}
```

### Add Static File Middleware

[Section titled “Add Static File Middleware”](#add-static-file-middleware)

Given that this project is designed to run client-side, all we need ASP.NET Core to do is to serve up the static HTML and JavaScript files that will make up our application. The static file middleware is designed to do this.

Register the static file middleware in `src/JavaScriptClient/Program.cs`. The entire file should look like this:

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


app.UseDefaultFiles();
app.UseStaticFiles();
app.Run();
```

This middleware will now serve up static files from the application’s `src/JavaScriptClient/wwwroot` directory. This is where we will put our HTML and JavaScript files. If that directory does not exist in your project, create it now.

### Reference oidc-client

[Section titled “Reference oidc-client”](#reference-oidc-client)

In the prior [web application quickstart](/identityserver/quickstarts/3-api-access/), we used a .NET library to handle the OpenID Connect protocol. In this quickstart, we need a similar library in the `JavaScriptClient` project, except one that works in JavaScript and is designed to run in the browser. The [oidc-client library](https://github.com/IdentityModel/oidc-client-js) is one such library. It is available via [NPM](https://github.com/IdentityModel/oidc-client-js), or as a [direct download](https://github.com/IdentityModel/oidc-client-js/tree/release/dist) from GitHub.

*`NPM`*

If you want to use NPM to download `oidc-client`, then run these commands from the `src/JavaScriptClient` directory:

```console
npm i oidc-client
copy node_modules/oidc-client/dist/* wwwroot
```

This downloads the latest `oidc-client` package locally, and then copies the relevant JavaScript files into `src/JavaScriptClient/wwwroot` so they can be served by your application.

**Manual download**

If you want to download the `oidc-client` JavaScript files manually, browse to [the GitHub repository](https://github.com/IdentityModel/oidc-client-js/tree/release/dist) and download the JavaScript files. Once downloaded, copy them into `src/JavaScriptClient/wwwroot` so they can be served by your application.

### Add HTML And JavaScript Files

[Section titled “Add HTML And JavaScript Files”](#add-html-and-javascript-files)

Next, add HTML and JavaScript files to the `src/JavaScriptClient/wwwroot` directory. You will need two HTML files and one JavaScript file (in addition to the `oidc-client.js` library). Add `index.html`, `callback.html`, and `app.js` to `wwwroot`.

*`index.html`*

This will be the main page in your application. It contains

* buttons for the user to login, logout, and call the API
* a `
` container used to show messages to the user
* `



```

*`app.js`*

This will contain the main code for your application. First, add a helper function to display messages in the `
`:

```js
function log() {
    document.getElementById("results").innerText = "";


    Array.prototype.forEach.call(arguments, function (msg) {
        if (typeof msg !== "undefined") {
            if (msg instanceof Error) {
                msg = "Error: " + msg.message;
            } else if (typeof msg !== "string") {
                msg = JSON.stringify(msg, null, 2);
            }
            document.getElementById("results").innerText += msg + "\r\n";
        }
    });
}
```

Next, add code to register `click` event handlers to the three buttons:

```js
document.getElementById("login").addEventListener("click", login, false);
document.getElementById("api").addEventListener("click", api, false);
document.getElementById("logout").addEventListener("click", logout, false);
```

Next, you will set up the `UserManager` class from the `oidc-client` library to manage the OpenID Connect protocol. It requires similar configuration that was necessary in the `WebClient` (albeit with different values). Add this code to configure and instantiate the `UserManager`:

```js
var config = {
    authority: "https://localhost:5001",
    client_id: "js",
    redirect_uri: "https://localhost:5003/callback.html",
    response_type: "code",
    scope: "openid profile api1",
    post_logout_redirect_uri: "https://localhost:5003/index.html",
};
var mgr = new Oidc.UserManager(config);
```

Next, use the `UserManager.getUser` function to determine if the user is logged into the JavaScript application. It uses a JavaScript `Promise` to return the results asynchronously. The returned `User` object has a `profile` property which contains the claims for the user. There’s also an event called `UserSignedOut` that can be handled to detect if the user signs out of the token server while the SPA application is being used (presumably in a different tab). Add this code to detect the user’s session status in the JavaScript application:

```js
mgr.events.addUserSignedOut(function () {
    log("User signed out of IdentityServer");
});


mgr.getUser().then(function (user) {
    if (user) {
        log("User logged in", user.profile);
    } else {
        log("User not logged in");
    }
});
```

Next, implement the `login`, `api`, and `logout` functions. The `UserManager` provides a `signinRedirect` to log the user in, and a `signoutRedirect` to log the user out. The `User` object that we obtained above also has an `access_token` property which can be used to authenticate to a web API. The `access_token` will be passed to the web API via the `Authorization` header with the `Bearer` scheme. Add this code to implement those three functions in your application:

```js
function login() {
    mgr.signinRedirect();
}


function api() {
    mgr.getUser().then(function (user) {
        var url = "https://localhost:6001/identity";


        var xhr = new XMLHttpRequest();
        xhr.open("GET", url);
        xhr.onload = function () {
            log(xhr.status, JSON.parse(xhr.responseText));
        };
        xhr.setRequestHeader("Authorization", "Bearer " + user.access_token);
        xhr.send();
    });
}


function logout() {
    mgr.signoutRedirect();
}
```

Note

See the [client credentials quickstart](/identityserver/quickstarts/1-client-credentials/) for information on how to create the remote API used in the code above.

*`callback.html`*

This HTML file is the designated `redirect_uri` page once the user has logged into IdentityServer. It will complete the OpenID Connect protocol sign-in handshake with IdentityServer. The code for this is all provided by the `UserManager` class we used earlier. Once the sign-in is complete, we can then redirect the user back to the main `index.html` page. Add this code to complete the signin process:

```html



    
    






```

## Add JavaScript Client Registration To IdentityServer

[Section titled “Add JavaScript Client Registration To IdentityServer”](#add-javascript-client-registration-to-identityserver)

Now that the client application is ready to go, you need to define a configuration entry in IdentityServer for the new JavaScript client.

In the IdentityServer project locate the client configuration in `src/IdentityServer/Config.cs`. Add a new `Client` to the list for your new JavaScript application. It should have the configuration listed below:

```csharp
// JavaScript Client
new Client
{
    ClientId = "js",
    ClientName = "JavaScript Client",
    AllowedGrantTypes = GrantTypes.Code,
    RequireClientSecret = false,


    RedirectUris =           { "https://localhost:5003/callback.html" },
    PostLogoutRedirectUris = { "https://localhost:5003/index.html" },
    AllowedCorsOrigins =     { "https://localhost:5003" },


    AllowedScopes =
    {
        IdentityServerConstants.StandardScopes.OpenId,
        IdentityServerConstants.StandardScopes.Profile,
        "api1"
    }
}
```

## Allowing Ajax Calls To The Web API With CORS

[Section titled “Allowing Ajax Calls To The Web API With CORS”](#allowing-ajax-calls-to-the-web-api-with-cors)

One last bit of configuration that is necessary is to configure CORS in the `Api` project. This will allow Ajax calls to be made from `https://localhost:5003` to `https://localhost:6001`.

**Configure CORS**

Add the CORS service to the dependency injection system in `src/Api/Program.cs`:

Program.cs

```csharp
builder.Services.AddCors(options =>
{
    // this defines a CORS policy called "default"
    options.AddPolicy("default", policy =>
    {
        policy.WithOrigins("https://localhost:5003")
            .AllowAnyHeader()
            .AllowAnyMethod();
    });
});
```

Then add the CORS middleware to the pipeline in `src/Api/Program.cs`.

Program.cs

```csharp
app.UseHttpsRedirection();
app.UseCors("default");
```

## Run The JavaScript Application

[Section titled “Run The JavaScript Application”](#run-the-javascript-application)

Now you should be able to run the JavaScript client application:

![Showing a user is not logged in to a JavaScript client](/_astro/jsclient_not_logged_in.Cf2cwMl__Z1P5MVv.webp)

Click the “Login” button to sign the user in. Once the user is returned back to the JavaScript application, you should see their profile information:

![Showing claims after a client has logged in](/_astro/jsclient_logged_in.4rNpJI6d_jlHrN.webp)

And click the “API” button to invoke the web API:

![Showing the API results from a JavaScript fetch](/_astro/jsclient_api_results.rd6LEavw_ZJdfFC.webp)

And finally click “Logout” to sign the user out.

![Showing the IdentityServer Logged Out view](/_astro/jsclient_signed_out.DI52Y-Hj_HinB.webp)

You now have the start of a JavaScript client application that uses IdentityServer for sign-in, sign-out, and authenticating calls to web APIs.

Note

Some browsers limit cross-site interactions (especially in iframes). In Safari, Firefox, or Brave you will notice that some important features will not work such as silent token renewal and check session monitoring.
-----
# Models

> Reference documentation for the models and interfaces used in Dynamic Client Registration (DCR), including request/response objects and validation context.

## DynamicClientRegistrationRequest

[Section titled “DynamicClientRegistrationRequest”](#dynamicclientregistrationrequest)

Represents a dynamic client registration request. The parameters that are supported include a subset of the parameters [defined by IANA](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#client-metadata), and custom properties needed by IdentityServer.

```csharp
public class DynamicClientRegistrationRequest
```

#### Public Members

[Section titled “Public Members”](#public-members)

| name                                                  | description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `AbsoluteRefreshTokenLifetime { get; set; }`          | The absolute lifetime of refresh tokens, in seconds. This property is an extension to the Dynamic Client Registration Protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `AccessTokenLifetime { get; set; }`                   | The lifetime of access tokens, in seconds. This property is an extension to the Dynamic Client Registration Protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `AccessTokenType { get; set; }`                       | The type of access tokens this client will create. Either “Jwt” or “Reference”. This property is an extension to the Dynamic Client Registration Protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `AllowedCorsOrigins { get; set; }`                    | List of allowed CORS origins for JavaScript clients. This property is an extension to the Dynamic Client Registration Protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `AllowedIdentityTokenSigningAlgorithms { get; set; }` | List of signing algorithms to use when signing identity tokens. If not set, will use the server’s default signing algorithm. This property is an extension to the Dynamic Client Registration Protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `AllowRememberConsent { get; set; }`                  | Boolean value specifying whether a user’s consent can be remembered in flows initiated by this client. This property is an extension to the Dynamic Client Registration Protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `AuthorizationCodeLifetime { get; set; }`             | The lifetime of authorization codes, in seconds. This property is an extension to the Dynamic Client Registration Protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `BackChannelLogoutSessionRequired { get; set; }`      | Boolean value specifying whether the RP requires that a `sid` (session ID) claim should be included in the Logout Token to identify the RP session with the OP when using the `backchannel_logout_uri`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `BackChannelLogoutUri { get; set; }`                  | RP URL that will cause the RP to log itself out when receiving a Logout Token from the OP.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `ClientName { get; set; }`                            | Human-readable string name of the client to be presented to the end-user during authorization.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `ClientUri { get; set; }`                             | Web page providing information about the client.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `ConsentLifetime { get; set; }`                       | The lifetime of consent, in seconds. This property is an extension to the Dynamic Client Registration Protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `CoordinateLifetimeWithUserSession { get; set; }`     | When enabled, the client’s token lifetimes (e.g. refresh tokens) will be tied to the user’s session lifetime. This means when the user logs out, any revokable tokens will be removed. When using server-side sessions, expired sessions will also remove any revokable tokens, and backchannel logout will be triggered. This client’s setting overrides the global `CoordinateClientLifetimesWithUserSession` configuration setting. This property is an extension to the Dynamic Client Registration Protocol.                                                                                                                                                                                                                                                                          |
| `DefaultMaxAge { get; set; }`                         | Default maximum authentication age. This is stored as the `UserSsoLifetime` property of the IdentityServer client model.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `EnableLocalLogin { get; set; }`                      | Boolean value specifying if local logins are enabled when this client uses interactive flows. This property is an extension to the Dynamic Client Registration Protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `Extensions { get; set; }`                            | Custom client metadata fields to include in the serialization.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `FrontChannelLogoutSessionRequired { get; set; }`     | Boolean value specifying whether the RP requires that a `sid` (session ID) query parameter should be included to identify the RP session with the OP when using the `frontchannel_logout_uri`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `FrontChannelLogoutUri { get; set; }`                 | RP URL that will cause the RP to log itself out when rendered in an iframe by the OP.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `GrantTypes { get; set; }`                            | List of OAuth 2.0 grant type strings that the client can use at the token endpoint. Valid values are `"authorization_code"`, `"client_credentials"`, `"refresh_token"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `IdentityProviderRestrictions { get; set; }`          | List of external IdPs that can be used with this client. If the list is empty, all IdPs are allowed. Defaults to empty. This property is an extension to the Dynamic Client Registration Protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `IdentityTokenLifetime { get; set; }`                 | The lifetime of identity tokens, in seconds. This property is an extension to the Dynamic Client Registration Protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `InitiateLoginUri { get; set; }`                      | URI using the https scheme that a third party can use to initiate a login by the relying party.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `Jwks { get; set; }`                                  | JWK Set document which contains the client’s public keys. The `JwksUri` and `Jwks` parameters MUST NOT both be present in the same request or response.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `JwksUri { get; set; }`                               | URL to a JWK Set document which contains the client’s public keys. The `JwksUri` and `Jwks` parameters MUST NOT both be present in the same request or response. The default validator must be extended to make use of the `JwksUri`. The default implementation ignores this property.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `LogoUri { get; set; }`                               | Logo for the client. If present, the server should display this image to the end-user during approval.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `PostLogoutRedirectUris { get; set; }`                | List of post-logout redirection URIs for use in the end session endpoint.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `RedirectUris { get; set; }`                          | List of redirection URI strings for use in redirect-based flows such as the authorization code flow. Clients using flows with redirection must register their redirection URI values.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `RefreshTokenExpiration { get; set; }`                | The type of expiration for refresh tokens. Either `"sliding"` or `"absolute"`. This property is an extension to the Dynamic Client Registration Protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `RefreshTokenUsage { get; set; }`                     | The usage type for refresh tokens. Either `"OneTimeOnly"` or `"ReUse"`. This property is an extension to the Dynamic Client Registration Protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `RequireClientSecret { get; set; }`                   | Boolean value specifying if a client secret is needed to request tokens at the token endpoint. This property is an extension to the Dynamic Client Registration Protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `RequireConsent { get; set; }`                        | Boolean value specifying whether consent is required in user-centric flows initiated by this client. This property is an extension to the Dynamic Client Registration Protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `RequireSignedRequestObject { get; set; }`            | Boolean value specifying whether authorization requests must be protected as signed request objects and provided through either the request or request\_uri parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `Scope { get; set; }`                                 | String containing a space-separated list of scope values that the client can use when requesting access tokens. If omitted, the configuration API will register a client with the scopes set by the `DynamicClientRegistrationValidator.SetDefaultScopes` method, which defaults to no scopes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `SlidingRefreshTokenLifetime { get; set; }`           | The sliding lifetime of refresh tokens, in seconds. This property is an extension to the Dynamic Client Registration Protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `SoftwareId { get; set; }`                            | A unique identifier string (e.g., a Universally Unique Identifier (UUID)) assigned by the client developer or software publisher used by registration endpoints to identify the client software to be dynamically registered. Unlike `"client_id"`, which is issued by the authorization server and SHOULD vary between instances, the `"software_id"` SHOULD remain the same for all instances of the client software. The `"software_id"` SHOULD remain the same across multiple updates or versions of the same piece of software. The value of this field is not intended to be human-readable and is usually opaque to the client and authorization server. The default validator must be extended to make use of the `SoftwareId`. The default implementation ignores this property. |
| `SoftwareStatement { get; set; }`                     | A software statement containing client metadata values about the client software as claims. This is a string value containing the entire signed JWT. The default validator must be extended to make use of the software statement. The default implementation ignores this property.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `SoftwareVersion { get; set; }`                       | A version identifier string for the client software identified by `"software_id"`. The value of the `"software_version"` SHOULD change on any update to the client software identified by the same `"software_id"`. The value of this field is intended to be compared using string equality matching and no other comparison semantics are defined by this specification. The default validator must be extended to make use of the `SoftwareVersion`. The default implementation ignores this property.                                                                                                                                                                                                                                                                                  |
| `TokenEndpointAuthenticationMethod { get; set; }`     | Requested Client Authentication method for the Token Endpoint. The supported options are `"client_secret_post"`, `"client_secret_basic"`, `"client_secret_jwt"`, `"private_key_jwt"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `UpdateAccessTokenClaimsOnRefresh { get; set; }`      | Boolean value specifying whether access token claims are updated during token refresh. This property is an extension to the Dynamic Client Registration Protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

## DynamicClientRegistrationResponse

[Section titled “DynamicClientRegistrationResponse”](#dynamicclientregistrationresponse)

Represents the response to a successful dynamic client registration request. This class extends the registration request by adding additional properties that are generated server side and not set by the client.

```csharp
public class DynamicClientRegistrationResponse : DynamicClientRegistrationRequest, IDynamicClientRegistrationResponse
```

#### Public Members

[Section titled “Public Members”](#public-members-1)

| name                                  | description                                                                                        |
| ------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `ClientId { get; set; }`              | Gets or sets the client ID.                                                                        |
| `ClientSecret { get; set; }`          | Gets or sets the client secret.                                                                    |
| `ClientSecretExpiresAt { get; set; }` | Gets or sets the expiration time of the client secret.                                             |
| `ResponseTypes { get; set; }`         | List of the OAuth 2.0 response type strings that the client can use at the authorization endpoint. |

## DynamicClientRegistrationContext

[Section titled “DynamicClientRegistrationContext”](#dynamicclientregistrationcontext)

Represents the context of a dynamic client registration request, including the original DCR request, the client model that is built up through validation and processing, the caller who made the DCR request, and other contextual information.

```csharp
public class DynamicClientRegistrationContext
```

#### Public Members

[Section titled “Public Members”](#public-members-2)

| name                    | description                                                                                                                                               |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Caller { get; set; }`  | The ClaimsPrincipal that made the DCR request.                                                                                                            |
| `Client { get; set; }`  | The client model that is built up through validation and processing.                                                                                      |
| `Items { get; set; }`   | A collection where additional contextual information may be stored. This is intended as a place to pass additional custom state between validation steps. |
| `Request { get; set; }` | The original dynamic client registration request.                                                                                                         |

## DynamicClientRegistrationError

[Section titled “DynamicClientRegistrationError”](#dynamicclientregistrationerror)

Represents an error that occurred during validation of a dynamic client registration request. This class implements the appropriate [marker interfaces](#marker-interfaces) so that it can be returned from various points in the validator or processor.

```csharp
public class DynamicClientRegistrationValidationError : IStepResult, IDynamicClientRegistrationResponse, IDynamicClientRegistrationValidationResult
```

#### Public Members

[Section titled “Public Members”](#public-members-3)

| name                             | description                                                                                                                                                                         |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Error { get; set; }`            | Gets or sets the error code for the error that occurred during validation. Error codes defined by RFC 7591 are defined as constants in the `DynamicClientRegistrationErrors` class. |
| `ErrorDescription { get; set; }` | Gets or sets a human-readable description of the error that occurred during validation.                                                                                             |

## Marker Interfaces

[Section titled “Marker Interfaces”](#marker-interfaces)

#### IDynamicClientRegistrationResponse

[Section titled “IDynamicClientRegistrationResponse”](#idynamicclientregistrationresponse)

Marker interface for the response to a dynamic client registration request. This interface has two implementations; [`DynamicClientRegistrationResponse`](#dynamicclientregistrationresponse) indicates success, while [`DynamicClientRegistrationError`](#dynamicclientregistrationerror) indicates failure.

#### IDynamicClientRegistrationValidationResult

[Section titled “IDynamicClientRegistrationValidationResult”](#idynamicclientregistrationvalidationresult)

Marker interface for the result of validating a dynamic client registration request. This interface has two implementations; [`DynamicClientRegistrationValidatedRequest`](#successfulstep) indicates success, while [`DynamicClientRegistrationError`](#dynamicclientregistrationerror) indicates failure. Note that the `DynamicClientRegistrationError` implements multiple interfaces and can be used throughout the pipeline to convey errors.

#### IStepResult

[Section titled “IStepResult”](#istepresult)

Marker interface for the result of a step in the dynamic client registration validator or processor. This interface has two implementations; [`SuccessfulStep`](#successfulstep) indicates success, while [`DynamicClientRegistrationError`](#dynamicclientregistrationerror) indicates failure. Note that the `DynamicClientRegistrationError` implements multiple interfaces and can be used throughout the pipeline to convey errors.

### IStepResult Convenience Functions

[Section titled “IStepResult Convenience Functions”](#istepresult-convenience-functions)

Your validation or processing steps can return a call to convenience functions in the static class `StepResult` to conveniently construct a success or failure from a step wrapped in a task.

| name                                                                      | description                                                                                                                            |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `static Task Success()`                                      | Indicates that the validation step was completed was completed successfully                                                            |
| `static Task Failure(string errorDescription)`               | Indicates that the validation step failed with the specified error description and the default error code of invalid\_client\_metadata |
| `static Task Failure(string errorDescription, string error)` | Indicates that the validation step failed with the specified error description and error code                                          |

## DynamicClientRegistrationValidatedRequest

[Section titled “DynamicClientRegistrationValidatedRequest”](#dynamicclientregistrationvalidatedrequest)

Represents a successfully validated dynamic client registration request.

```csharp
public class DynamicClientRegistrationValidatedRequest : DynamicClientRegistrationValidationResult
```

## SuccessfulStep

[Section titled “SuccessfulStep”](#successfulstep)

Represents a successful validation step.

```csharp
public class SuccessfulStep : IStepResult
```
-----
# Options

> Reference documentation for the IdentityServer configuration options related to dynamic client registration and secret lifetimes.

The page describes the `IdentityServerConfigurationOptions` class, which provides top-level configuration options for IdentityServer, including the `DynamicClientRegistrationOptions` class for managing dynamic client registration and secret lifetimes.

## IdentityServerConfigurationOptions

[Section titled “IdentityServerConfigurationOptions”](#identityserverconfigurationoptions)

Top-level options for IdentityServer configuration.

```csharp
public class IdentityServerConfigurationOptions
```

### Public Members

[Section titled “Public Members”](#public-members)

| name                                                                           | description                             |
| ------------------------------------------------------------------------------ | --------------------------------------- |
| [`DynamicClientRegistration { get; set; }`](#dynamicclientregistrationoptions) | Options for Dynamic Client Registration |

## DynamicClientRegistrationOptions

[Section titled “DynamicClientRegistrationOptions”](#dynamicclientregistrationoptions)

Options for dynamic client registration.

```csharp
public class DynamicClientRegistrationOptions
```

### Public Members

[Section titled “Public Members”](#public-members-1)

| name                           | description                                                                                                                                               |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SecretLifetime { get; set; }` | Gets or sets the lifetime of secrets generated for clients. If unset, generated secrets will have no expiration. Defaults to null (secrets never expire). |
-----
# Request Processing

> Understand how dynamic client registration requests are processed, including client ID and secret generation, through the IDynamicClientRegistrationRequestProcessor contract and its default implementation.

The page explains the `IDynamicClientRegistrationRequestProcessor` contract, its default implementation ( `DynamicClientRegistrationRequestProcessor`), and the steps involved in processing a dynamic client registration request, including methods for generating client IDs, secrets, and customizing secret generation.

## IDynamicClientRegistrationRequestProcessor

[Section titled “IDynamicClientRegistrationRequestProcessor”](#idynamicclientregistrationrequestprocessor)

The `IDynamicClientRegistrationValidator` is the contract for the service that processes a dynamic client registration request. It contains a single `ProcessAsync(...)` method.

Conceptually, the request processing step is responsible for setting properties on the `Client` model that are generated by the Configuration API itself. In contrast, the `IDynamicClientRegistrationRequestProcessor` is responsible for checking the validity of the metadata supplied in the registration request, and using that metadata to set properties of a `Client` model. The request processor is also responsible for passing the finished `Client` to the [store](/identityserver/reference/v7/dcr/store/)

### Members

[Section titled “Members”](#members)

| name              | description                                                                                                                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ProcessAsync(…)` | Processes a valid dynamic client registration request, setting properties of the client that are not specified in the request, and storing the new client in the IClientConfigurationStore. |

## DynamicClientRegistrationRequestProcessor

[Section titled “DynamicClientRegistrationRequestProcessor”](#dynamicclientregistrationrequestprocessor)

The `DynamicClientRegistrationRequestProcessor` is the default implementation of the `IDynamicClientRegistrationRequestProcessor`. If you need to customize some aspect of Dynamic Client Registration request processing, we recommend that you extend this class and override the appropriate virtual methods.

```csharp
public class DynamicClientRegistrationRequestProcessor : IDynamicClientRegistrationRequestProcessor
```

## Request Processing Steps

[Section titled “Request Processing Steps”](#request-processing-steps)

Each of these virtual methods represents one step of request processing. Each step is passed a [DynamicClientRegistrationContext](/identityserver/reference/v7/dcr/models/#dynamicclientregistrationcontext) and returns a task that returns an [`IStepResult`](/identityserver/reference/v7/dcr/models/#istepresult). The `DynamicClientRegistrationContext` includes the client model that will have its properties set, the DCR request, and other contextual information. The `IStepResult` either represents that the step succeeded or failed.

| name                      | description                                                               |
| ------------------------- | ------------------------------------------------------------------------- |
| `virtual AddClientId`     | Generates a client ID and adds it to the validatedRequest’s client model. |
| `virtual AddClientSecret` | Adds a client secret to a dynamic client registration request.            |

## Secret Generation

[Section titled “Secret Generation”](#secret-generation)

The `AddClientSecret` method is responsible for adding the client’s secret and plaintext of that secret to the context’s `Items` dictionary for later use. If you want to customize secret generation, you can override the GenerateSecret method, which only needs to return a tuple containing the secret and its plaintext.

| name                     | description                                                   |
| ------------------------ | ------------------------------------------------------------- |
| `virtual GenerateSecret` | Generates a secret for a dynamic client registration request. |
-----
# Response Generation

> Reference documentation for dynamic client registration response generation, including interfaces and implementations for handling HTTP responses in the registration process.

## IDynamicClientRegistrationResponseGenerator

[Section titled “IDynamicClientRegistrationResponseGenerator”](#idynamicclientregistrationresponsegenerator)

The `IDynamicClientRegistrationResponseGenerator` interface defines the contract for a service that generates dynamic client registration responses.

```csharp
public interface IDynamicClientRegistrationResponseGenerator
```

### Members

[Section titled “Members”](#members)

| name                       | description                                                              |
| -------------------------- | ------------------------------------------------------------------------ |
| `WriteBadRequestError(…)`  | Writes a bad request error to the HTTP context.                          |
| `WriteContentTypeError(…)` | Writes a content type error to the HTTP response.                        |
| `WriteProcessingError(…)`  | Writes a processing error to the HTTP context.                           |
| `WriteResponse(…)`         | Writes a response object to the HTTP context with the given status code. |
| `WriteSuccessResponse(…)`  | Writes a success response to the HTTP context.                           |
| `WriteValidationError(…)`  | Writes a validation error to the HTTP context.                           |

## DynamicClientRegistrationResponseGenerator

[Section titled “DynamicClientRegistrationResponseGenerator”](#dynamicclientregistrationresponsegenerator)

The `DynamicClientRegistrationResponseGenerator` is the default implementation of the `IDynamicClientRegistrationResponseGenerator`. If you wish to customize a particular aspect of response generation, you can extend this class and override the appropriate methods. You can also set JSON serialization options by overriding its `SerializerOptions` property.

### Members

[Section titled “Members”](#members-1)

| name                              | description                                         |
| --------------------------------- | --------------------------------------------------- |
| `SerializerOptions { get; set; }` | The options used for serializing json in responses. |
-----
# Store

> Reference documentation for the Dynamic Client Registration (DCR) store interfaces and implementations used to manage client configurations in IdentityServer

## IClientConfigurationStore

[Section titled “IClientConfigurationStore”](#iclientconfigurationstore)

The `IClientConfigurationStore` interface defines the contract for a service that communicates with the client configuration data store. It contains a single `AddAsync` method.

```csharp
public interface IClientConfigurationStore
```

### Members

[Section titled “Members”](#members)

| name          | description                               |
| ------------- | ----------------------------------------- |
| `AddAsync(…)` | Adds a client to the configuration store. |

## ClientConfigurationStore

[Section titled “ClientConfigurationStore”](#clientconfigurationstore)

The `ClientConfigurationStore` is the default implementation of the `IClientConfigurationStore`. It uses Entity Framework to communicate with the client configuration store, and is intended to be used when IdentityServer is configured to use the Entity Framework based configuration stores.
-----
# Validation

> Reference documentation for Dynamic Client Registration (DCR) validation process, including validation steps, interfaces, and client property configuration.

## IDynamicClientRegistrationValidator

[Section titled “IDynamicClientRegistrationValidator”](#idynamicclientregistrationvalidator)

The `IDynamicClientRegistrationValidator` is the contract for the service that validates a dynamic client registration request. It contains a single `ValidateAsync(...)` method.

Conceptually, the validation step is responsible for checking the validity of the metadata supplied in the registration request, and using that metadata to set properties of a `Client` model. In contrast, the `IDynamicClientRegistrationRequestProcessor` is responsible for setting properties on the `Client` model that are generated by the Configuration API itself.

### IDynamicClientRegistrationValidator.ValidateAsync

[Section titled “IDynamicClientRegistrationValidator.ValidateAsync”](#idynamicclientregistrationvalidatorvalidateasync)

Validates a dynamic client registration request.

```csharp
public Task ValidateAsync(
    DynamicClientRegistrationContext context)
```

| parameter | description                                   |
| --------- | --------------------------------------------- |
| `context` | Contextual information about the DCR request. |

### Return Value

[Section titled “Return Value”](#return-value)

A task that returns an [`IDynamicClientRegistrationValidationResult`](/identityserver/reference/v7/dcr/models/#idynamicclientregistrationvalidationresult), indicating success or failure.

## DynamicClientRegistrationValidator

[Section titled “DynamicClientRegistrationValidator”](#dynamicclientregistrationvalidator)

```csharp
public class DynamicClientRegistrationValidator : IDynamicClientRegistrationValidator
```

The `DynamicClientRegistrationValidator` class is the default implementation of the `IDynamicClientRegistrationValidator`. If you need to customize some aspect of Dynamic Client Registration validation, we recommend that you extend this class and override the appropriate methods.

## Validation Steps

[Section titled “Validation Steps”](#validation-steps)

Each of these methods represents one step in the validation process. Each step is passed a [`DynamicClientRegistrationContext`](/identityserver/reference/v7/dcr/models/#dynamicclientregistrationcontext) and returns a task that returns an [`IStepResult`](/identityserver/reference/v7/dcr/models/#istepresult). The `DynamicClientRegistrationContext` includes the client model that will have its properties set, the DCR request, and other contextual information. The `IStepResult` either represents that the step succeeded or failed.

The steps are invoked in the same order as they appear in this table.

| name                                | description                                                                                                                                                                                                                                                                                                     |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ValidateSoftwareStatementAsync(…)` | Validates the software statement of the request. The default implementation does nothing, and is included as an extension point.                                                                                                                                                                                |
| `SetGrantTypesAsync(…)`             | Validates requested grant types and uses them to set the allowed grant types of the client.                                                                                                                                                                                                                     |
| `SetRedirectUrisAsync(…)`           | Validates requested redirect URIs and uses them to set the redirect URIs of the client.                                                                                                                                                                                                                         |
| `SetScopesAsync(…)`                 | Validates requested scopes and uses them to set the scopes of the client.                                                                                                                                                                                                                                       |
| `SetDefaultScopes(…)`               | Sets scopes on the client when no scopes are requested. The default implementation sets no scopes and is intended as an extension point.                                                                                                                                                                        |
| `SetSecretsAsync(…)`                | Validates the requested JSON Web Key set to set the secrets of the client.                                                                                                                                                                                                                                      |
| `SetClientNameAsync(…)`             | Validates the requested client name uses it to set the name of the client.                                                                                                                                                                                                                                      |
| `SetLogoutParametersAsync(…)`       | Validates the requested client parameters related to logout and uses them to set the corresponding properties in the client. Those parameters include the post logout redirect URIs, front channel and back channel URIs, and flags for the front and back channel URIs indicating if they require session ids. |
| `SetMaxAgeAsync(…)`                 | Validates the requested default max age and uses it to set the user SSO lifetime of the client.                                                                                                                                                                                                                 |
| `SetUserInterfaceProperties(…)`     | Validates details of the request that control the user interface, including the logo URI, client URI, initiate login URI, enable local login flag, and identity provider restrictions, and uses them to set the corresponding client properties.                                                                |
| `SetPublicClientProperties(…)`      | Validates the requested client parameters related to public clients and uses them to set the corresponding properties in the client. Those parameters include the require client secret flag and the allowed CORS origins.                                                                                      |
| `SetAccessTokenProperties(…)`       | Validates the requested client parameters related to access tokens and uses them to set the corresponding properties in the client. Those parameters include the allowed access token type and access token lifetime.                                                                                           |
| `SetIdTokenProperties(…)`           | Validates the requested client parameters related to id tokens and uses them to set the corresponding properties in the client. Those parameters include the id token lifetime and the allowed id token signing algorithms.                                                                                     |
| `SetServerSideSessionProperties(…)` | Validates the requested client parameters related to server side sessions and uses them to set the corresponding properties in the client. Those parameters include the coordinate lifetime with user session flag.                                                                                             |
-----
# Dependency Injection Extension Methods

> A comprehensive guide to IdentityServer's dependency injection extension methods for configuring services, stores, caching, signing keys and other features.

`AddIdentityServer` return a builder object that provides many extension methods to add IdentityServer specific services to the ASP.NET Core service provider. Here’s a list grouped by feature areas.

Program.cs

```csharp
var idsvrBuilder = builder.Services.AddIdentityServer();
```

Note

Many of the fundamental configuration settings can be set on the options. See the `[IdentityServerOptions](/identityserver/reference/v7/options)` reference for more details.

## Configuration Stores

[Section titled “Configuration Stores”](#configuration-stores)

Several convenience methods are provided for registering custom stores:

* **`AddClientStore`**

  Registers a custom `IClientStore` implementation.

* **`AddCorsPolicyService`**

  Registers a custom `ICorsPolicyService` implementation.

* **`AddResourceStore`**

  Registers a custom `IResourceStore` implementation.

* **`AddIdentityProviderStore`**

  Registers a custom `IIdentityProviderStore` implementation.

The [in-memory configuration stores](/identityserver/data/providers/in-memory/) can be registered in DI with the following extension methods.

* **`AddInMemoryClients`**

  Registers `IClientStore` and `ICorsPolicyService` implementations based on the in-memory collection of `Client` configuration objects.

* **`AddInMemoryIdentityResources`**

  Registers `IResourceStore` implementation based on the in-memory collection of `IdentityResource` configuration objects.

* **`AddInMemoryApiScopes`**

  Registers `IResourceStore` implementation based on the in-memory collection of `ApiScope` configuration objects.

* **`AddInMemoryApiResources`**

  Registers `IResourceStore` implementation based on the in-memory collection of `ApiResource` configuration objects.

## Caching Configuration Data

[Section titled “Caching Configuration Data”](#caching-configuration-data)

Extension methods to enable [caching for configuration data](/identityserver/data/configuration/#caching-configuration-data):

* **`AddInMemoryCaching`**

  To use any of the caches described below, an implementation of `ICache` must be registered in the ASP.NET Core service provider. This API registers a default in-memory implementation of `ICache` that’s based on ASP.NET Core’s `MemoryCache`.

* **`AddClientStoreCache`** Registers a `IClientStore` decorator implementation which will maintain an in-memory cache of `Client` configuration objects. The cache duration is configurable on the `Caching` configuration options on the `IdentityServerOptions`.

* **`AddResourceStoreCache`**

  Registers a `IResourceStore` decorator implementation which will maintain an in-memory cache of `IdentityResource` and `ApiResource` configuration objects. The cache duration is configurable on the `Caching` configuration options on the `IdentityServerOptions`.

* **`AddCorsPolicyCache`**

  Registers a `ICorsPolicyService` decorator implementation which will maintain an in-memory cache of the results of the CORS policy service evaluation. The cache duration is configurable on the `Caching` configuration options on the `IdentityServerOptions`.

* **`AddIdentityProviderStoreCache`**

  Registers a `IIdentityProviderStore` decorator implementation which will maintain an in-memory cache of `IdentityProvider` configuration objects. The cache duration is configurable on the `Caching` configuration options on the `IdentityServerOptions`.

## Test Stores

[Section titled “Test Stores”](#test-stores)

The `TestUser` class models a user, their credentials, and claims in IdentityServer.

Use of `TestUser` is similar to the use of the “in-memory” stores in that it is intended for when prototyping, developing, and/or testing. The use of `TestUser` is not recommended in production.

* **`AddTestUsers`**

  Registers `TestUserStore` based on a collection of `TestUser` objects. `TestUserStore` is e.g. used by the default quickstart UI. Also registers implementations of `IProfileService` and `IResourceOwnerPasswordValidator` that uses the test users as a backing store.

## Signing keys

[Section titled “Signing keys”](#signing-keys)

Duende IdentityServer needs key material to sign tokens. This key material can either be created and [managed automatically](/identityserver/fundamentals/key-management/#automatic-key-management) or [configured statically](/identityserver/fundamentals/key-management/#static-key-management).

Note

We recommend that you use automatic key management. This section covers the configuration methods needed for manual configuration of signing keys, which are usually only needed if your license does not include automatic key management or if you are [migrating](/identityserver/fundamentals/key-management/#migrating-from-static-keys-to-automatic-key-management) from manually managed keys to automatic key management.

Duende IdentityServer supports X.509 certificates (both raw files and a reference to the certificate store), RSA keys and EC keys for token signatures and validation. Each key can be configured with a (compatible) signing algorithm, e.g. RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384 or ES512.

You can configure the key material with the following methods:

* **`AddSigningCredential`**

  Adds a signing key that provides the specified key material to the various token creation/validation services.

* **`AddDeveloperSigningCredential`**

  Creates temporary key material at startup time. This is for dev scenarios. The generated key will be persisted in the local directory by default (or just kept in memory).

* **`AddValidationKey`**

  Adds a key for validating tokens. They will be used by the internal token validator and will show up in the discovery document.

## Additional services

[Section titled “Additional services”](#additional-services)

The following are convenient to add additional features to your IdentityServer.

* **`AddExtensionGrantValidator`**

  Adds an `IExtensionGrantValidator` implementation for use with extension grants.

* **`AddSecretParser`**

  Adds an `ISecretParser` implementation for parsing client or API resource credentials.

* **`AddSecretValidator`**

  Adds an `ISecretValidator` implementation for validating client or API resource credentials against a credential store.

* **`AddResourceOwnerValidator`**

  Adds an `IResourceOwnerPasswordValidator` implementation for validating user credentials for the resource owner password credentials grant type.

* **`AddProfileService`**

  Adds an`IProfileService` implementation. The default implementation (found in `DefaultProfileService`) relies upon the authentication cookie as the only source of claims for issuing in tokens.

* **`AddAuthorizeInteractionResponseGenerator`**

  Adds an `IAuthorizeInteractionResponseGenerator` implementation to customize logic at authorization endpoint for when a user must be shown a UI for error, login, consent, or any other custom page. The default implementation can be found in the `AuthorizeInteractionResponseGenerator` class, so consider deriving from this existing class if you need to augment the existing behavior.

* **`AddCustomAuthorizeRequestValidator`**

  Adds an `ICustomAuthorizeRequestValidator` implementation to customize request parameter validation at the authorization endpoint.

* **`AddCustomTokenRequestValidator`**

  Adds an `ICustomTokenRequestValidator` implementation to customize request parameter validation at the token endpoint.

* **`AddRedirectUriValidator`**

  Adds an `IRedirectUriValidator` implementation to customize redirect URI validation.

* **`AddAppAuthRedirectUriValidator`**

  Adds an “AppAuth” (OAuth 2.0 for Native Apps) compliant redirect URI validator (does strict validation but also allows `http://127.0.0.1` with random port).

* **`AddJwtBearerClientAuthentication`**

  Adds support for client authentication using JWT bearer assertions.

* **`AddMutualTlsSecretValidators`**

  Adds the X509 secret validators for mutual TLS.

* **`AddIdentityProviderConfigurationValidator`**

  Adds an IdentityProvider configuration validator.

* **`AddBackchannelAuthenticationUserValidator`**

  Adds the backchannel login user validator.

* **`AddBackchannelAuthenticationUserNotificationService`**

  Adds the backchannel login user validator.
-----
# Entity Framework Core Options

> Configuration options available when using Entity Framework Core as the storage implementation for IdentityServer.

If using the [Entity Framework Core store implementation](/identityserver/data/providers/entityframework-core/), you might need to configure those specific options.
-----
# Configuration Options

> Configuration options available when using Entity Framework Core as the configuration store in IdentityServer

## Duende.IdentityServer.EntityFramework.Options.ConfigurationStoreOptions

[Section titled “Duende.IdentityServer.EntityFramework.Options.ConfigurationStoreOptions”](#duendeidentityserverentityframeworkoptionsconfigurationstoreoptions)

These options are configurable when using the Entity Framework Core for the [configuration store](/identityserver/data/configuration/):

You set the options at startup time in your `AddConfigurationStore` method:

Program.cs

```csharp
var builder = services.AddIdentityServer()
    .AddConfigurationStore(options =>
    {
        // configure options here..
    })
```

### Pooling

[Section titled “Pooling”](#pooling)

Settings that affect the DbContext pooling feature of Entity Framework Core.

* **`EnablePooling`**

  Gets or set if EF DbContext pooling is enabled. Defaults to `false`.

* **`PoolSize`**

  Gets or set the pool size to use when DbContext pooling is enabled. If not set, the EF default is used.

### Schema

[Section titled “Schema”](#schema)

Settings that affect the database schema and table names.

* **`DefaultSchema`**

  Gets or sets the default schema. Defaults to `null`.

`TableConfiguration` settings for each individual table (schema and name) managed by this feature:

Identity Resource related tables:

* **`IdentityResource`**
* **`IdentityResourceClaim`**
* **`IdentityResourceProperty`**

API Resource related tables:

* **`ApiResource`**
* **`ApiResourceSecret`**
* **`ApiResourceScope`**
* **`ApiResourceClaim`**
* **`ApiResourceProperty`**

Client related tables:

* **`Client`**
* **`ClientGrantType`**
* **`ClientRedirectUri`**
* **`ClientPostLogoutRedirectUri`**
* **`ClientScopes`**
* **`ClientSecret`**
* **`ClientClaim`**
* **`ClientIdPRestriction`**
* **`ClientCorsOrigin`**
* **`ClientProperty`**

API Scope related tables:

* **`ApiScope`**
* **`ApiScopeClaim`**
* **`ApiScopeProperty`**

Identity provider related tables:

* **`IdentityProvider`**
-----
# Operational Options

> Configure Entity Framework Core operational store options including database schema, pooling settings, and cleanup parameters for persisted grants.

## Duende.IdentityServer.EntityFramework.Options.OperationalStoreOptions

[Section titled “Duende.IdentityServer.EntityFramework.Options.OperationalStoreOptions”](#duendeidentityserverentityframeworkoptionsoperationalstoreoptions)

These options are configurable when using the Entity Framework Core for the [operational store](/identityserver/data/operational/):

You set the options at startup time in your `AddOperationalStore` method:

Program.cs

```csharp
builder.Services.AddIdentityServer()
    .AddOperationalStore(options =>
    {
        // configure options here..
    })
```

### Pooling

[Section titled “Pooling”](#pooling)

Settings that affect the DbContext pooling feature of Entity Framework Core.

* **`EnablePooling`**

  Gets or set if EF DbContext pooling is enabled. Defaults to `false`.

* **`PoolSize`**

  Gets or set the pool size to use when DbContext pooling is enabled. If not set, the EF default is used.

### Schema

[Section titled “Schema”](#schema)

Settings that affect the database schema and table names.

* **`DefaultSchema`**

  Gets or sets the default schema. Defaults to `null`.

`TableConfiguration` settings for each individual table (schema and name) managed by this feature:

* **`PersistedGrants`**
* **`DeviceFlowCodes`**
* **`Keys`**
* **`ServerSideSessions`**

### Persisted Grants Cleanup

[Section titled “Persisted Grants Cleanup”](#persisted-grants-cleanup)

Settings that affect the background cleanup of expired entries (tokens) from the persisted grants table.

* **`EnableTokenCleanup`**

  Gets or sets a value indicating whether stale entries will be automatically cleaned up from the database. This is implemented by periodically connecting to the database (according to the TokenCleanupInterval) from the hosting application. Defaults to `false`.

* **`RemoveConsumedTokens`**

  Gets or sets a value indicating whether consumed tokens will be included in the automatic clean up. Defaults to `false`.

* **`TokenCleanupInterval`**

  Gets or sets the token cleanup interval (in seconds). The default is `3600` (1 hour).

* **`TokenCleanupBatchSize`**

  Gets or sets the number of records to remove per batch operation. The cleanup job will perform multiple batch operations as long as there are more records to remove than the configured `TokenCleanupBatchSize`. Defaults to `100`.

* **`FuzzTokenCleanupStart`**

  The background token cleanup job runs at a configured interval. If multiple nodes run the cleanup job at the same time there will be updated conflicts in the store. To avoid that, the startup time can be fuzzed. The first run is scheduled at a random time between the host startup and the configured TokenCleanupInterval. Subsequent runs are run on the configured TokenCleanupInterval. Defaults to `true`
-----
# Authorize Endpoint

> Documentation for the authorize endpoint which handles browser-based token and authorization code requests, including authentication and consent flows.

The authorize endpoint can be used to request tokens or authorization codes via the browser. This process typically involves authentication of the end-user and optionally consent.

IdentityServer supports a subset of the OpenID Connect and OAuth 2.0 authorize request parameters. For a full list, see [here](https://openid.net/specs/openid-connect-core-1_0.html#authrequest).

### Required Parameters

[Section titled “Required Parameters”](#required-parameters)

* **`client_id`**

  identifier of the client

* **`scope`**

  one or more registered scopes

* **`redirect_uri`**

  must exactly match one of the allowed redirect URIs for that client

* **`response_type`**

  specifies the response type

  * **`id_token`**

  * **`token`**

  * **`id_token token`**

  * **`code`**

  * **`code id_token`**

  * **`code id_token token`**

### Optional Parameters

[Section titled “Optional Parameters”](#optional-parameters)

* **`response_mode`**

  specifies the response mode

  * **`query`**

  * **`fragment`**

  * **`form_post`**

* **`state`**

  echos back the state value on the token response, this is for round tripping state between client and provider, correlating request and response and CSRF/replay protection. (recommended)

* **`nonce`**

  echos back the nonce value in the identity token (for replay protection)

  Required when identity tokens is transmitted via the browser channel

* **`prompt`**

  * **`none`**

    no UI will be shown during the request. If this is not possible (e.g. because the user has to sign in or consent) an error is returned

  * **`login`**

    the login UI will be shown, even if the user is already signed in and has a valid session

  * **`create`**

    the user registration UI will be shown, if the `UserInteraction.CreateAccountUrl` option is set (the option is null by default, which disables support for this prompt value)

* **`code_challenge`**

  sends the code challenge for PKCE

* **`code_challenge_method`**

  * **`plain`**

    indicates that the challenge is using plain text (not recommended)

  * **`S256`**

    indicates the challenge is hashed with SHA256

* **`login_hint`**

  can be used to pre-fill the username field on the login page

* **`ui_locales`**

  gives a hint about the desired display language of the login UI

* **`max_age`**

  if the user’s logon session exceeds the max age (in seconds), the login UI will be shown

* **`acr_values`**

  allows passing in additional authentication related information - IdentityServer special cases the following proprietary acr\_values:

  * **`idp:name_of_idp`**

    bypasses the login/home realm screen and forwards the user directly to the selected identity provider (if allowed per client configuration)

  * **`tenant:name_of_tenant`**

    can be used to pass a tenant name to the login UI

* **`request`**

  instead of providing all parameters as individual query string parameters, you can provide a subset or all them as a JWT

* **`request_uri`**

  URL of a pre-packaged JWT containing request parameters

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

## .NET Client Library

[Section titled “.NET Client Library”](#net-client-library)

You can use the [Duende IdentityModel](/identitymodel/) client library to programmatically create authorize request URLs from .NET code.

```csharp
var ru = new RequestUrl("https://demo.duendesoftware.com/connect/authorize");


var url = ru.CreateAuthorizeUrl(
    clientId: "client",
    responseType: "code",
    redirectUri: "https://app.com/callback",
    scope: "openid");
```
-----
# Backchannel Authentication Endpoint

> Documentation for the CIBA endpoint which allows clients to initiate backchannel authentication requests for users without browser interaction

The backchannel authentication endpoint is used by a client to initiate a [CIBA](/identityserver/ui/ciba/) request.

Clients must be configured with the `"urn:openid:params:grant-type:ciba"` grant type to use this endpoint. You can use the `OidcConstants.GrantTypes.Ciba` constant rather than hard coding the value for the CIBA grant type.

### Required Parameters

[Section titled “Required Parameters”](#required-parameters)

* **`scope`**

  one or more registered scopes

Note

The client id and a client credential is required to authenticate to the endpoint using any valid form of authentication that has been configured for it (much like the token endpoint).

### Exactly One Of These Values Is Required

[Section titled “Exactly One Of These Values Is Required”](#exactly-one-of-these-values-is-required)

* **`login_hint`**

  hint for the end user to be authenticated. the value used is implementation specific.

* **`id_token_hint`**

  a previously issued id\_token for the end user to be authenticated

* **`login_hint_token`**

  a token containing information for the end user to be authenticated. the details are implementation specific.

Note

To validate these implementation specific values and use them to identity the user that is to be authenticated, you are required to implement the `IBackchannelAuthenticationUserValidator` interface.

### Optional Parameters

[Section titled “Optional Parameters”](#optional-parameters)

* **`binding_message`**

  identifier or message intended to be displayed on both the consumption device and the authentication device

* **`user_code`**

  a secret code, such as a password or pin, that is known only to the user but verifiable by the OP

* **`requested_expiry`**

  a positive integer allowing the client to request the `expires_in` value for the `auth_req_id` the server will return. if not present, then the optional `CibaLifetime` property on the `Client` is used, and if that is not present, then the `DefaultLifetime` on the `CibaOptions` will be used.

* **`acr_values`**

  allows passing in additional authentication related information - IdentityServer special cases the following proprietary acr\_values:

  * **`idp:name_of_idp`**

    bypasses the login/home realm screen and forwards the user directly to the selected identity provider (if allowed per client configuration)

  * **`tenant:name_of_tenant`**

    can be used to pass a tenant name to the login UI

* **`resource`**

  resource indicator identifying the `ApiResource` for which the access token should be restricted to

* **`request`**

  instead of providing all parameters as individual parameters, you can provide all them as a JWT

And a successful response will look something like:

```http
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store


{
    "auth_req_id": "1C266114A1BE42528AD104986C5B9AC1",
    "expires_in": 600,
    "interval": 5
}
```

## .NET Client Library

[Section titled “.NET Client Library”](#net-client-library)

You can use the [Duende IdentityModel](/identitymodel/) client library to programmatically interact with the protocol endpoint from .NET code.

```csharp
using Duende.IdentityModel.Client;


var client = new HttpClient();


var cibaResponse = await client.RequestBackchannelAuthenticationAsync(new BackchannelAuthenticationRequest
{
    Address = "https://demo.duendesoftware.com/connect/ciba",
    ClientId = "client1",
    ClientSecret = "secret",
    Scope = "openid api1",
    LoginHint = "alice",
});
```

And with a successful response, it can be used to poll the token endpoint:

```csharp
while (true)
{
    var response = await client.RequestBackchannelAuthenticationTokenAsync(new BackchannelAuthenticationTokenRequest
    {
        Address = "https://demo.duendesoftware.com/connect/token",
        ClientId = "client1",
        ClientSecret = "secret",
        AuthenticationRequestId = cibaResponse.AuthenticationRequestId
    });


    if (response.IsError)
    {
        if (response.Error == OidcConstants.TokenErrors.AuthorizationPending || response.Error == OidcConstants.TokenErrors.SlowDown)
        {
            await Task.Delay(cibaResponse.Interval.Value * 1000);
        }
        else
        {
            throw new Exception(response.Error);
        }
    }
    else
    {
        // success! use response.IdentityToken, response.AccessToken, and response.RefreshToken (if requested)
    }
}
```
-----
# Device Authorization Endpoint

> Documentation for the device authorization endpoint which handles device flow authentication requests and issues device and user codes for authorization.

The device authorization endpoint can be used to request device and user codes. This endpoint is used to start the device flow authorization process.

* **`client_id`**

  client identifier (required)

* **`client_secret`**

  client secret either in the post body, or as a basic authentication header. Optional.

* **`scope`**

  one or more registered scopes. If not specified, a token for all explicitly allowed scopes will be issued

## .NET Client Library

[Section titled “.NET Client Library”](#net-client-library)

You can use the [Duende IdentityModel](/identitymodel/) client library to programmatically interact with the protocol endpoint from .NET code.

```csharp
using Duende.IdentityModel.Client;


var client = new HttpClient();


var response = await client.RequestDeviceAuthorizationAsync(new DeviceAuthorizationRequest
{
    Address = "https://demo.duendesoftware.com/connect/device_authorize",
    ClientId = "device"
});
```
-----
# Discovery Endpoint

> Learn about the discovery endpoint that provides metadata about your IdentityServer configuration, including issuer name, key material, and supported scopes.

The [discovery endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html) can be used to retrieve metadata about your IdentityServer - it returns information like the issuer name, key material, supported scopes etc.

The discovery endpoint is available via `/.well-known/openid-configuration` relative to the base address, e.g.:

```text
https://demo.duendesoftware.com/.well-known/openid-configuration
```

## Issuer Name and Path Base

[Section titled “Issuer Name and Path Base”](#issuer-name-and-path-base)

When your IdentityServer is hosted in an application that uses [ASP.NET Core’s `PathBaseMiddleware`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.builder.extensions.usepathbasemiddleware), the base path will be included in the issuer name and discovery document URLs. For example, if your application is configured with a path base of `/identity`, your configuration will look like this:

Program.cs

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


// 👨‍💻 configure Application Host


var app = builder.Build();
app.UseSerilogRequestLogging();


if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}


// 👋 Configuring the path base
app.UsePathBase("/identity");


app.UseStaticFiles();
app.UseRouting();


app.UseIdentityServer();
app.UseAuthorization();


app.MapRazorPages()
    .RequireAuthorization();


return app;
```

And the discovery document will look like this:

.well-known/openid-configuration

```json
{
  "issuer": "https://localhost:5001/identity",
  "jwks_uri": "https://localhost:5001/identity/.well-known/openid-configuration/jwks",
  "authorization_endpoint": "https://localhost:5001/identity/connect/authorize",
  "token_endpoint": "https://localhost:5001/identity/connect/token",
  "userinfo_endpoint": "https://localhost:5001/identity/connect/userinfo",
  "end_session_endpoint": "https://localhost:5001/identity/connect/endsession",
  "check_session_iframe": "https://localhost:5001/identity/connect/checksession",
  "revocation_endpoint": "https://localhost:5001/identity/connect/revocation",
  "introspection_endpoint": "https://localhost:5001/identity/connect/introspect",
  "device_authorization_endpoint": "https://localhost:5001/identity/connect/deviceauthorization",
  "backchannel_authentication_endpoint": "https://localhost:5001/identity/connect/ciba",
  "pushed_authorization_request_endpoint": "https://localhost:5001/identity/connect/par"
}
```

This can be helpful when configuring IdentityServer in a multi-tenant scenario where the base path is used to identify the tenant.

## .NET Client Library

[Section titled “.NET Client Library”](#net-client-library)

You can use the [Duende IdentityModel](/identitymodel/) client library to programmatically interact with the protocol endpoint from .NET code.

```csharp
var client = new HttpClient();


var disco = await client.GetDiscoveryDocumentAsync("https://demo.duendesoftware.com");
```
-----
# End Session Endpoint

> The end session endpoint enables single sign-out functionality in OpenID Connect, allowing users to terminate their sessions across multiple client applications.

The end session endpoint can be used to trigger single sign-out in the browser ( see [spec](https://openid.net/specs/openid-connect-rpinitiated-1_0.html)).

To use the end session endpoint a client application will redirect the user’s browser to the end session URL. All applications that the user has logged into via the browser during the user’s session can participate in the sign-out.

The URL for the end session endpoint is available via discovery.

* **`id_token_hint`**

  When the user is redirected to the endpoint, they will be prompted if they really want to sign-out. This prompt can be bypassed by a client sending the original `id_token` received from authentication. This is passed as a query string parameter called `id_token_hint`.

* **`post_logout_redirect_uri`**

  If a valid `id_token_hint` is passed, then the client may also send a `post_logout_redirect_uri` parameter. This can be used to allow the user to redirect back to the client after sign-out. The value must match one of the client’s pre-configured `PostLogoutRedirectUris`.

* **`state`**

  If a valid `post_logout_redirect_uri` is passed, then the client may also send a `state` parameter. This will be returned back to the client as a query string parameter after the user redirects back to the client. This is typically used by clients to roundtrip state across the redirect.

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

## .NET Client Library

[Section titled “.NET Client Library”](#net-client-library)

You can use the [Duende IdentityModel](/identitymodel/) client library to programmatically create end sessions request URLs from .NET code.

```csharp
var ru = new RequestUrl("https://demo.duendesoftware.com/connect/end_session");


var url = ru.CreateEndSessionUrl(
    idTokenHint: "...",
    postLogoutRedirectUri: "...");
```
-----
# Introspection Endpoint

> Documentation for the RFC 7662 compliant introspection endpoint used to validate reference tokens, JWTs, and refresh tokens.

The introspection endpoint is an implementation of [RFC 7662](https://tools.ietf.org/html/rfc7662).

It can be used to validate reference tokens, JWTs (if the consumer does not have support for appropriate JWT or cryptographic libraries) and refresh tokens. Refresh tokens can only be introspected by the client that requested them.

The introspection endpoint requires authentication. Since the request to the introspection endpoint is typically done by an API, which is not an OAuth client, the [`ApiResource`](/identityserver/fundamentals/resources/api-resources/) is used to configure credentials:

```csharp
new ApiResource("resource1")
{
    Scopes = { "scope1", "scope2" }, // Replace "scope1", "scope2" with the actual scopes required for your API


    ApiSecrets =
    {
        new Secret("secret".Sha256())
    }
}
```

The ID used for authentication is the name of the `ApiResource`, “resource1”, and the secret is the configured secret. The introspection endpoint uses HTTP basic auth to communicate these credentials:

```text
POST /connect/introspect
Content-Type: application/x-www-form-urlencoded
Authorization: Basic xxxyyy


token=
```

A successful response will return a status code of 200, the token claims, the token type, and a flag indicating the token is active:

```json
{
  "iss": "https://localhost:5001",
  "nbf": 1729599599,
  "iat": 1729599599,
  "exp": 1729603199,
  "client_id": "client",
  "jti": "44FD2DE9E9F8E9F4DDD141CD7C244BE9",
  "scope": "api1",
  "token_type": "access_token",
  "active": true
}
```

Unknown or expired tokens will be marked as inactive:

```json
{
  "active": false
}
```

An invalid request will return a 400, an unauthorized request 401.

## JWT Response from Introspection Endpoint v7.3

[Section titled “JWT Response from Introspection Endpoint ”v7.3](#jwt-response-from-introspection-endpoint)

IdentityServer supports [RFC 9701](https://www.rfc-editor.org/rfc/rfc9701.html) to return a JWT response from the introspection endpoint.

To return a JWT response, set the `Accept` header in the HTTP request to `application/token-introspection+jwt`:

```text
POST /connect/introspect
Content-Type: application/x-www-form-urlencoded
Accept: application/token-introspection+jwt
Authorization: Basic xxxyyy


token=
```

A successful response will return a status code of 200 and has a `Content-Type: application/token-introspection+jwt` header, indicating that the response body contains a raw JWT instead. The base64 decoded JWT will have a `typ` claim in the header with the value `token-introspection+jwt`. The token’s payload contains a `token_introspection` JSON object similar to the default response type:

```json
{
  "alg": "RS256",
  "kid": "BE9D78519A8BBCB28A65FADEECF49CBC",
  "typ": "token-introspection+jwt"
}.{
  "iss": "https://localhost:5001",
  "iat": 1729599599,
  "aud": "api1",
  "token_introspection": {
    "iss": "https://localhost:5001",
    "nbf": 1729599599,
    "iat": 1729599599,
    "exp": 1729603199,
    "aud": [ "api1" ],
    "client_id": "client",
    "jti": "44FD2DE9E9F8E9F4DDD141CD7C244BE9",
    "active": true,
    "scope": "api1"
  }
}.[Signature]
```

## .NET Client Library

[Section titled “.NET Client Library”](#net-client-library)

You can use the [Duende IdentityModel](/identitymodel/) client library to programmatically interact with the protocol endpoint from .NET code.

```csharp
using Duende.IdentityModel.Client;


var client = new HttpClient();


var response = await client.IntrospectTokenAsync(new TokenIntrospectionRequest
{
    Address = "https://demo.duendesoftware.com/connect/introspect",
    ClientId = "resource1",
    ClientSecret = "secret",


    Token = "" // Replace with the actual token
});
```
-----
# OAuth Metadata Endpoint

> Learn about the OAuth metadata endpoint that provides information about your IdentityServer configuration, including issuer name, key material, and supported scopes.

The [OAuth Metadata Endpoint](https://www.rfc-editor.org/rfc/rfc8414.html) is a standardized way to retrieve metadata about your IdentityServer.

The discovery endpoint is available via `/.well-known/oauth-authorization-server` relative to the base address, e.g.:

```text
https://demo.duendesoftware.com/.well-known/oauth-authorization-server
```

## Issuer Name and Path Base

[Section titled “Issuer Name and Path Base”](#issuer-name-and-path-base)

When hosting IdentityServer in an application that uses [ASP.NET Core’s `PathBaseMiddleware`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.builder.extensions.usepathbasemiddleware), the base path will be included in the issuer name and discovery document URLs.

Refer the [Discovery Endpoint](/identityserver/reference/v7/endpoints/discovery/#issuer-name-and-path-base) for more information.
-----
# Revocation Endpoint

> Learn about the revocation endpoint that allows invalidating access and refresh tokens according to RFC 7009 specification.

This endpoint allows revoking access tokens (reference tokens only) and refresh token. It implements the token revocation specification [(RFC 7009)](https://tools.ietf.org/html/rfc7009).

* **`token`**

  the token to revoke (required)

* **`token_type_hint`**

  either `access_token` or `refresh_token` (optional)

```text
POST /connect/revocation HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW


token=...&token_type_hint=refresh_token
```

## .NET Client Library

[Section titled “.NET Client Library”](#net-client-library)

You can use the [Duende IdentityModel](/identitymodel/) client library to programmatically interact with the protocol endpoint from .NET code.

```csharp
using Duende.IdentityModel.Client;


var client = new HttpClient();


var result = await client.RevokeTokenAsync(new TokenRevocationRequest
{
    Address = "https://demo.duendesoftware.com/connect/revocation",
    ClientId = "client",
    ClientSecret = "secret",


    Token = token
});
```
-----
# Token Endpoint

> Documentation for the token endpoint that enables programmatic token requests using various grant types and parameters in Duende IdentityServer.

The token endpoint can be used to programmatically request tokens.

Duende IdentityServer supports a subset of the OpenID Connect and OAuth 2.0 token request parameters. For a full list, see [here](https://openid.net/specs/openid-connect-core-1_0.html#tokenrequest).

### Required Parameters

[Section titled “Required Parameters”](#required-parameters)

* **`client_id`**

  client identifier; not necessary in body if it is present in the authorization header

* **`grant_type`**

  * **`authorization_code`**

  * **`client_credentials`**

  * **`password`**

  * **`refresh_token`**

  * **`urn:ietf:params:oauth:grant-type:device_code`**

  * ***extension grant***

### Optional Parameters

[Section titled “Optional Parameters”](#optional-parameters)

* **`client_secret`**

  client secret for confidential/credentials clients - either in the post body, or as a basic authentication header.

* **`scope`**

  one or more registered scopes. If not specified, a token for all explicitly allowed scopes will be issued.

* **`redirect_uri`**

  required for the `authorization_code` grant type

* **`code`**

  the authorization code (required for `authorization_code` grant type)

* **`code_verifier`**

  PKCE proof key

* **`username`**

  resource owner username (required for `password` grant type)

* **`password`**

  resource owner password (required for `password` grant type)

* **`acr_values`**

  allows passing in additional authentication related information. Duende IdentityServer special cases the following proprietary acr\_values

  * **`tenant:name_of_tenant`**

    can be used to pass a tenant name to the token endpoint

* **`refresh_token`**

  the refresh token (required for `refresh_token` grant type)

* **`device_code`**

  the device code (required for `urn:ietf:params:oauth:grant-type:device_code` grant type)

* **`auth_req_id`**

  the backchannel authentication request id (required for `urn:openid:params:grant-type:ciba` grant type)

```text
POST /connect/token
CONTENT-TYPE application/x-www-form-urlencoded


    client_id=client1&
    client_secret=secret&
    grant_type=authorization_code&
    code=hdh922&
    redirect_uri=https://myapp.com/callback
```

## .NET Client Library

[Section titled “.NET Client Library”](#net-client-library)

You can use the [Duende IdentityModel](/identitymodel/) client library to programmatically interact with the protocol endpoint from .NET code.

```csharp
using Duende.IdentityModel.Client;


var client = new HttpClient();


var response = await client.RequestAuthorizationCodeTokenAsync(new AuthorizationCodeTokenRequest
{
    Address = TokenEndpoint,


    ClientId = "client",
    ClientSecret = "secret",


    Code = "...",
    CodeVerifier = "...",
    RedirectUri = "https://app.com/callback"
});
```
-----
# UserInfo Endpoint

> Reference documentation for the UserInfo endpoint, which allows retrieval of authenticated user claims using a valid access token.

The UserInfo endpoint can be used to retrieve claims about a user ( see [spec](https://openid.net/specs/openid-connect-core-1_0.html#userinfo)).

The caller needs to send a valid access token. Depending on the granted scopes, the UserInfo endpoint will return the mapped claims (at least the `openid` scope is required).

```text
GET /connect/userinfo
Authorization: Bearer 
```

```text
HTTP/1.1 200 OK
Content-Type: application/json


{
    "sub": "248289761001",
    "name": "Bob Smith",
    "given_name": "Bob",
    "family_name": "Smith"
}
```

## .NET Client Library

[Section titled “.NET Client Library”](#net-client-library)

You can use the [Duende IdentityModel](/identitymodel/) client library to programmatically interact with the protocol endpoint from .NET code.

```csharp
using Duende.IdentityModel.Client;


var client = new HttpClient();


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.AccessToken
});
```
-----
# API Resource

> Reference documentation for the ApiResource class which models an API in Duende IdentityServer, including its properties and configuration options.

## Duende.IdentityServer.Models.ApiResource

[Section titled “Duende.IdentityServer.Models.ApiResource”](#duendeidentityservermodelsapiresource)

This class models an API.

* **`Enabled`**

  Indicates if this resource is enabled and can be requested. Defaults to true.

* **`Name`**

  The unique name of the API. This value is used for authentication with introspection and will be added to the audience of the outgoing access token.

* **`DisplayName`**

  This value can be used e.g. on the consent screen.

* **`Description`**

  This value can be used e.g. on the consent screen.

* **`RequireResourceIndicator`**

  Indicates if this API resource requires the resource indicator to request it, and expects access tokens issued to it will only ever contain this API resource as the audience.

* **`ApiSecrets`**

  The API secret is used for the introspection endpoint. The API can authenticate with introspection using the API name and secret.

* **`AllowedAccessTokenSigningAlgorithms`**

  List of allowed signing algorithms for access token. If empty, will use the server default signing algorithm.

* **`UserClaims`**

  List of associated user claim types that should be included in the access token.

* **`Scopes`**

  List of API scope names. You need to create those using [ApiScope](/identityserver/reference/v7/models/api-scope/).

## Defining API resources In appsettings.json

[Section titled “Defining API resources In appsettings.json”](#defining-api-resources-in-appsettingsjson)

The `AddInMemoryApiResource` extensions method also supports adding API resources from the ASP.NET Core configuration file:

```plaintext
"IdentityServer": {
    "IssuerUri": "urn:sso.company.com",
    "ApiResources": [
        {
            "Name": "resource1",
            "DisplayName": "Resource #1",


            "Scopes": [
                "resource1.scope1",
                "shared.scope"
            ]
        },
        {
            "Name": "resource2",
            "DisplayName": "Resource #2",


            "UserClaims": [
                "name",
                "email"
            ],


            "Scopes": [
                "resource2.scope1",
                "shared.scope"
            ]
        }
    ]
}
```

Then pass the configuration section to the `AddInMemoryApiResource` method:

Program.cs

```csharp
idsvrBuilder.AddInMemoryApiResources(configuration.GetSection("IdentityServer:ApiResources"))
```
-----
# API Scope

> Reference documentation for the ApiScope class which models an OAuth scope in Duende IdentityServer, including its properties and configuration options.

## Duende.IdentityServer.Models.ApiScope

[Section titled “Duende.IdentityServer.Models.ApiScope”](#duendeidentityservermodelsapiscope)

This class models an OAuth scope.

* **`Enabled`**

  Indicates if this resource is enabled and can be requested. Defaults to true.

* **`Name`**

  The unique name of the API. This value is used for authentication with introspection and will be added to the audience of the outgoing access token.

* **`DisplayName`**

  This value can be used e.g. on the consent screen.

* **`Description`**

  This value can be used e.g. on the consent screen.

* **`UserClaims`**

  List of associated user claim types that should be included in the access token.

## Defining API Scope In appsettings.json

[Section titled “Defining API Scope In appsettings.json”](#defining-api-scope-in-appsettingsjson)

The `AddInMemoryApiResource` extension method also supports adding clients from the ASP.NET Core configuration file:

```json
{
  "IdentityServer": {
    "IssuerUri": "urn:sso.company.com",
    "ApiScopes": [
      {
        "Name": "IdentityServerApi"
      },
      {
        "Name": "resource1.scope1"
      },
      {
        "Name": "resource2.scope1"
      },
      {
        "Name": "scope3"
      },
      {
        "Name": "shared.scope"
      },
      {
        "Name": "transaction",
        "DisplayName": "Transaction",
        "Description": "A transaction"
      }
    ]
  }
}
```

Then pass the configuration section to the `AddInMemoryApiScopes` method:

Program.cs

```csharp
idsvrBuilder.AddInMemoryApiScopes(configuration.GetSection("IdentityServer:ApiScopes"))
```
-----
# Backchannel User Login Request

> Reference documentation for the BackchannelUserLoginRequest class which models the information needed to initiate a user login request for Client Initiated Backchannel Authentication (CIBA).

## Duende.IdentityServer.Models.BackchannelUserLoginRequest

[Section titled “Duende.IdentityServer.Models.BackchannelUserLoginRequest”](#duendeidentityservermodelsbackchanneluserloginrequest)

Models the information to initiate a user login request for [CIBA](/identityserver/ui/ciba/).

* **`InternalId`**

  The identifier of the request in the store.

* **`Subject`**

  The subject for whom the login request is intended.

* **`BindingMessage`**

  The binding message used in the request.

* **`AuthenticationContextReferenceClasses`**

  The `acr_values` used in the request.

* **`Tenant`**

  The `tenant` value from the `acr_values` used in the request.

* **`IdP`**

  The `idp` value from the `acr_values` used in the request.

* **`RequestedResourceIndicators`**

  The resource indicator values used in the request.

* **`Client`**

  The client that initiated the request.

* **`ValidatedResources`**

  The validated resources (i.e. scopes) used in the request.
-----
# Client

> Reference documentation for the Client class which models an OpenID Connect or OAuth 2.0 client in Duende IdentityServer, including configuration for authentication, tokens, consent, refresh tokens, and advanced features.

## Duende.IdentityServer.Models.Client

[Section titled “Duende.IdentityServer.Models.Client”](#duendeidentityservermodelsclient)

The `Client` class models an OpenID Connect or OAuth 2.0 client - e.g. a native application, a web application or a JS-based application.

```csharp
public static IEnumerable Get()
{
    return new List
    {
        ///////////////////////////////////////////
        // machine to machine client
        //////////////////////////////////////////
        new Client
        {
            ClientId = "machine",
            ClientSecrets = { Configuration["machine.secret"] },


            AllowedGrantTypes = GrantTypes.ClientCredentials,


            AllowedScopes = machineScopes
        },


        ///////////////////////////////////////////
        // web client
        //////////////////////////////////////////
        new Client
        {
            ClientId = "web",


            ClientSecrets = { new Secret(Configuration["web.secret"]) },


            AllowedGrantTypes = GrantTypes.Code,


            RedirectUris = { "https://myapp.com:/signin-oidc" },
            PostLogoutRedirectUris = { "https://myapp.com/signout-callback-oidc" },


            BackChannelLogoutUri = "https://myapp.com/backchannel-logout",


            AllowOfflineAccess = true,
            AllowedScopes = webScopes
        }
    }
}
```

## Basics

[Section titled “Basics”](#basics)

* **`Enabled`**

  Specifies if client is enabled. Defaults to `true`.

* **`ClientId`**

  Unique ID of the client

* **`ClientSecrets`**

  List of client secrets - credentials to access the token endpoint.

* **`RequireClientSecret`**

  Specifies whether this client needs a secret to request tokens from the token endpoint (defaults to `true`)

* **`RequireRequestObject`**

  Specifies whether this client needs to wrap the authorize request parameters in a JWT (defaults to `false`)

* **`AllowedGrantTypes`**

  Specifies the grant types the client is allowed to use. Use the `GrantTypes` class for common combinations.

* **`RequirePkce`**

  Specifies whether clients using an authorization code based grant type must send a proof key (defaults to `true`).

* **`AllowPlainTextPkce`**

  Specifies whether clients using PKCE can use a plain text code challenge (not recommended - and defaults to `false`)

* **`RedirectUris`**

  Specifies the allowed URIs to return tokens or authorization codes to

* **`AllowedScopes`**

  By default, a client has no access to any resources - specify the allowed resources by adding the corresponding scopes names

* **`AllowOfflineAccess`**

  Specifies whether this client can request refresh tokens (be requesting the `offline_access` scope)

* **`AllowAccessTokensViaBrowser`**

  Specifies whether this client is allowed to receive access tokens via the browser. This is useful to harden flows that allow multiple response types (e.g. by disallowing a hybrid flow client that is supposed to use *code id\_token* to add the `token` response type and thus leaking the token to the browser).

* **`Properties`**

  Dictionary to hold any custom client-specific values as needed.

## Authentication / Session Management

[Section titled “Authentication / Session Management”](#authentication--session-management)

* **`PostLogoutRedirectUris`**

  Specifies allowed URIs to redirect to after logout.

* **`FrontChannelLogoutUri`**

  Specifies logout URI at client for HTTP based front-channel logout.

* **`FrontChannelLogoutSessionRequired`**

  Specifies if the user’s session id should be sent to the FrontChannelLogoutUri. Defaults to true.

* **`BackChannelLogoutUri`**

  Specifies logout URI at client for HTTP based back-channel logout.

* **`BackChannelLogoutSessionRequired`**

  Specifies if the user’s session id should be sent in the request to the BackChannelLogoutUri. Defaults to true.

* **`EnableLocalLogin`**

  Specifies if this client can use local accounts, or external IdPs only. Defaults to `true`.

* **`IdentityProviderRestrictions`**

  Specifies which external IdPs can be used with this client (if list is empty all IdPs are allowed). Defaults to empty.

* **`UserSsoLifetime`**

  The maximum duration (in seconds) since the last time the user authenticated. Defaults to `null`. You can adjust the lifetime of a session token to control when and how often a user is required to reenter credentials instead of being silently authenticated, when using a web application.

* **`AllowedCorsOrigins`**

  If specified, will be used by the default CORS policy service implementations (In-Memory and EF) to build a CORS policy for JavaScript clients.

* **`CoordinateLifetimeWithUserSession`** (added in v6.1)

  When enabled, the client’s token lifetimes (e.g. refresh tokens) will be tied to the user’s session lifetime. This means when the user logs out, any revokable tokens will be removed. If using server-side sessions, expired sessions will also remove any revokable tokens, and backchannel logout will be triggered. This client’s setting overrides the global `CoordinateClientLifetimesWithUserSession` configuration setting.

## Token

[Section titled “Token”](#token)

* **`IdentityTokenLifetime`**

  Lifetime to identity token in seconds (defaults to 300 seconds / 5 minutes)

* **`AllowedIdentityTokenSigningAlgorithms`**

  List of allowed signing algorithms for identity token. If empty, will use the server default signing algorithm.

* **`AccessTokenLifetime`**

  Lifetime of access token in seconds (defaults to 3600 seconds / 1 hour)

* **`AuthorizationCodeLifetime`**

  Lifetime of authorization code in seconds (defaults to 300 seconds / 5 minutes)

* **`AccessTokenType`**

  Specifies whether the access token is a reference token or a self-contained JWT token (defaults to `Jwt`).

* **`IncludeJwtId`**

  Specifies whether JWT access tokens should have an embedded unique ID (via the `jti` claim). Defaults to `true`.

* **`Claims`**

  Allows settings claims for the client (will be included in the access token).

* **`AlwaysSendClientClaims`**

  If set, the client claims will be sent for every flow. If not, only for client credentials flow (default is `false`)

* **`AlwaysIncludeUserClaimsInIdToken`**

  When requesting both an id token and access token, should the user claims always be added to the id token instead of requiring the client to use the userinfo endpoint. Default is `false`.

* **`ClientClaimsPrefix`**

  If set, the prefix client claim types will be prefixed with. Defaults to `client_`. The intent is to make sure they don’t accidentally collide with user claims.

* **`PairWiseSubjectSalt`**

  Salt value used in pair-wise subjectId generation for users of this client. Currently not implemented.

## Refresh Token

[Section titled “Refresh Token”](#refresh-token)

* **`AbsoluteRefreshTokenLifetime`**

  Maximum lifetime of a refresh token in seconds. Defaults to 2592000 seconds / 30 days.

  Setting this to 0 has the following effect:

  * When `RefreshTokenExpiration` is set to `Absolute`, the behavior is the same as when no refresh tokens are used.
  * When `RefreshTokenExpiration` is set to `Sliding`, refresh tokens only expire after the `SlidingRefreshTokenLifetime` has passed.

* **`SlidingRefreshTokenLifetime`**

  Sliding lifetime of a refresh token in seconds. Defaults to 1296000 seconds / 15 days.

* **`RefreshTokenUsage`**

  * **`ReUse`**

    the refresh token handle will stay the same when refreshing tokens. This is the default.

  * **`OneTimeOnly`**

    the refresh token handle will be updated when refreshing tokens.

* **`RefreshTokenExpiration`**

  * **`Absolute`**

    the refresh token will expire on a fixed point in time (specified by the `AbsoluteRefreshTokenLifetime`). This is the default.

  * **`Sliding`**

    when refreshing the token, the lifetime of the refresh token will be renewed (by the amount specified in `SlidingRefreshTokenLifetime`). The lifetime will not exceed `AbsoluteRefreshTokenLifetime`.

* **`UpdateAccessTokenClaimsOnRefresh`**

  Gets or sets a value indicating whether the access token (and its claims) should be updated on a refresh token request.

## Consent Screen

[Section titled “Consent Screen”](#consent-screen)

Consent screen specific settings.

* **`RequireConsent`**

  Specifies whether a consent screen is required. Defaults to `false`.

* **`AllowRememberConsent`**

  Specifies whether user can choose to store consent decisions. Defaults to `true`.

* **`ConsentLifetime`**

  Lifetime of a user consent in seconds. Defaults to null (no expiration).

* **`ClientName`**

  Client display name (used for logging and consent screen).

* **`ClientUri`**

  URI to further information about client.

* **`LogoUri`**

  URI to client logo.

## Cross Device Flows

[Section titled “Cross Device Flows”](#cross-device-flows)

Settings used in the CIBA and OAuth device flows.

* **`PollingInterval`**

  Maximum polling interval for the client in cross device flows. If the client polls more frequently than the polling interval during those flows, it will receive a `slow_down` error response. Defaults to `null`, which means the throttling will use the global default appropriate for the flow (`IdentityServerOptions.Ciba.DefaultPollingInterval` or `IdentityServerOptions.DeviceFlow.Interval`).

#### Device Flow

[Section titled “Device Flow”](#device-flow)

Device flow specific settings.

* **`UserCodeType`**

  Specifies the type of user code to use for the client. Otherwise, falls back to default.

* **`DeviceCodeLifetime`**

  Lifetime to device code in seconds (defaults to 300 seconds / 5 minutes)

#### CIBA

[Section titled “CIBA”](#ciba)

Client initiated backchannel authentication specific settings.

* **`CibaLifetime`**

  Specifies the backchannel authentication request lifetime in seconds. Defaults to `null`.

## DPoP

[Section titled “DPoP”](#dpop)

Added in 6.3.0.

Settings specific to the Demonstration of Proof-of-Possession at the Application Layer ([DPoP](/identityserver/tokens/pop/)) feature.

* **`RequireDPoP`**

  Specifies whether a DPoP (Demonstrating Proof-of-Possession) token is required to be used by this client. Defaults to `false`.

* **`DPoPValidationMode`**

  Enum setting to control validation for the DPoP proof token expiration. This supports both the client generated ‘iat’ value and/or the server generated ‘nonce’ value. Defaults to `DPoPTokenExpirationValidationMode.Iat`, which only validates the ‘iat’ value.

* **`DPoPClockSkew`**

  Clock skew used in validating the client’s DPoP proof token ‘iat’ claim value. Defaults to *5 minutes*.

## Third-Party Initiated Login

[Section titled “Third-Party Initiated Login”](#third-party-initiated-login)

Added in 6.3.0.

* **`InitiateLoginUri`**

  An optional URI that can be used to [initiate login](https://openid.net/specs/openid-connect-core-1_0.html#thirdpartyinitiatedlogin) from the IdentityServer host or a third party. This is most commonly used to create a client application portal within the IdentityServer host. Defaults to null.

## Pushed Authorization Requests

[Section titled “Pushed Authorization Requests”](#pushed-authorization-requests)

Added in 7.0.0

* **`RequirePushedAuthorization`**

  Controls if this client requires PAR. PAR is required if either the global configuration is enabled or if the client’s flag is enabled (this can’t be used to opt out of the global configuration). This defaults to `false`, which means the global configuration will be used.

* **`PushedAuthorizationLifetime`**

  Controls the lifetime of pushed authorization requests for a client. If this lifetime is set, it takes precedence over the global configuration. This defaults to `null`, which means the global configuration is used.
-----
# Grant Validation Result

> Reference documentation for the GrantValidationResult class which models the outcome of grant validation for extension grants and resource owner password grants in Duende IdentityServer.

## Duende.IdentityServer.Validation.GrantValidationResult

[Section titled “Duende.IdentityServer.Validation.GrantValidationResult”](#duendeidentityservervalidationgrantvalidationresult)

The `GrantValidationResult` class models the outcome of grant validation for [extensions grants](/identityserver/tokens/extension-grants/) and [resource owner password grants](/identityserver/tokens/password-grant/).

It models either a successful validation result with claims (e.g. subject ID) or an invalid result with an error code and message, e.g.:

```csharp
public class ExtensionGrantValidator : IExtensionGrantValidator
{
    public Task ValidateAsync(ExtensionGrantValidationContext context)
    {
        // some validation steps


        if (success)
        {
            context.Result = new GrantValidationResult(
                subject: "818727",
                authenticationMethod: "custom",
                claims: extraClaims);
        }
        else
        {
            // custom error message
            context.Result = new GrantValidationResult(
                TokenRequestErrors.InvalidGrant,
                "invalid custom credential");
        }


        return Task.CompletedTask;
    }
}
```

It also allows passing additional custom values that will be included in the token response, e.g.:

```csharp
context.Result = new GrantValidationResult(
    subject: "818727",
    authenticationMethod: "custom",
    customResponse: new Dictionary
    {
        { "some_data", "some_value" }
    });
```

This will result in the following token response:

```json
{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 360,
  "some_data": "some_value"
}
```
-----
# Identity Resource

> Reference documentation for the IdentityResource class which models an identity resource in Duende IdentityServer, including standard and custom identity resources and their properties.

## Duende.IdentityServer.Models.IdentityResource

[Section titled “Duende.IdentityServer.Models.IdentityResource”](#duendeidentityservermodelsidentityresource)

This class models an identity resource.

```csharp
public static readonly IEnumerable IdentityResources =
    new[]
    {
        // some standard scopes from the OIDC spec
        new IdentityResources.OpenId(),
        new IdentityResources.Profile(),
        new IdentityResources.Email(),


        // custom identity resource with some associated claims
        new IdentityResource("custom.profile",
            userClaims: new[] { JwtClaimTypes.Name, JwtClaimTypes.Email, "location", JwtClaimTypes.Address })
    };
```

* **`Enabled`**

  Indicates if this resource is enabled and can be requested. Defaults to true.

* **`Name`**

  The unique name of the identity resource. This is the value a client will use for the scope parameter in the authorize request.

* **`DisplayName`**

  This value will be used e.g. on the consent screen.

* **`Description`**

  This value will be used e.g. on the consent screen.

* **`Required`**

  Specifies whether the user can de-select the scope on the consent screen (if the consent screen wants to implement such a feature). Defaults to false.

* **`Emphasize`**

  Specifies whether the consent screen will emphasize this scope (if the consent screen wants to implement such a feature). Use this setting for sensitive or important scopes. Defaults to false.

* **`ShowInDiscoveryDocument`**

  Specifies whether this scope is shown in the discovery document. Defaults to `true`.

* **`UserClaims`**

  List of associated user claim types that should be included in the identity token.
-----
# Identity Provider

> Reference documentation for identity provider models in Duende IdentityServer, including OidcProvider for external OpenID Connect providers, IdentityProviderName, and the base IdentityProvider class.

## Duende.IdentityServer.Models.OidcProvider

[Section titled “Duende.IdentityServer.Models.OidcProvider”](#duendeidentityservermodelsoidcprovider)

The `OidcProvider` models an external OpenID Connect provider for use in the [dynamic providers](/identityserver/ui/login/dynamicproviders/) feature. Its properties map to the Open ID Connect options class from ASP.NET Core, and those properties include:

* **`Enabled`**

  Specifies if provider is enabled. Defaults to `true`.

* **`Scheme`**

  Scheme name for the provider.

* **`DisplayName`**

  Display name for the provider.

* **`Type`**

  Protocol type of the provider. Defaults to `"oidc"` for the `OidcProvider`.

* **`Authority`**

  The base address of the OIDC provider.

* **`ResponseType`**

  The response type. Defaults to `"id_token"`.

* **`ClientId`**

  The client id.

* **`ClientSecret`**

  The client secret. By default, this is the plaintext client secret and great consideration should be taken if this value is to be stored as plaintext in the store. It is possible to store this in a protected way and then unprotect when loading from the store either by implementing a custom `IIdentityProviderStore` or registering a custom `IConfigureNamedOptions`.

* **`Scope`**

  Space separated list of scope values.

* **`GetClaimsFromUserInfoEndpoint`**

  Indicates if userinfo endpoint is to be contacted. Defaults to true.

* **`UsePkce`**

  Indicates if PKCE should be used. Defaults to true.

#### Duende.IdentityServer.Models.IdentityProviderName

[Section titled “Duende.IdentityServer.Models.IdentityProviderName”](#duendeidentityservermodelsidentityprovidername)

The `IdentityProviderName` models the display name of an identity provider.

* **`Enabled`**

  Specifies if provider is enabled. Defaults to `true`.

* **`Scheme`**

  Scheme name for the provider.

* **`DisplayName`**

  Display name for the provider.

#### Duende.IdentityServer.Models.IdentityProvider

[Section titled “Duende.IdentityServer.Models.IdentityProvider”](#duendeidentityservermodelsidentityprovider)

The `IdentityProvider` is a base class to model arbitrary identity providers, which `OidcProvider` derives from. This leaves open the possibility for extensions to the dynamic provider feature to support other protocol types (as distinguished by the `Type` property).
-----
# License Usage Summary

> Reference documentation for the LicenseUsageSummary class which provides detailed information about clients, issuers, and features used in Duende IdentityServer for self-auditing and license compliance.

## Duende.IdentityServer.Licensing.LicenseUsageSummary

[Section titled “Duende.IdentityServer.Licensing.LicenseUsageSummary”](#duendeidentityserverlicensinglicenseusagesummary)

Added in 7.1

The `LicenseUsageSummary` class allows developers to get a detailed summary of clients, issuers, and features used during the lifetime of an active .NET application for self-auditing purposes.

* **`LicenseEdition`**

  Indicates the current IdentityServer instance’s license edition.

* **`ClientsUsed`**

  A `string` collection of clients used with the current IdentityServer instance.

* **`IssuersUsed`**

  A `string` collection of issuers used with the current IdentityServer instance.

* **`FeaturesUsed`**

  A `string` collection of features has been used since the IdentityServer instance ran.

## Register LicenseUsageSummary Services

[Section titled “Register LicenseUsageSummary Services”](#register-licenseusagesummary-services)

To make the `LicenseUsageSummary` class available in your application, you’ll need to make sure it is registered in the service collection at startup. You can do this by calling the `AddLicenseSummary()` extension method when registering IdentityServer:

Program.cs

```csharp
builder.Services.AddIdentityServer()
    .AddLicenseSummary();
```

## Using LicenseUsageSummary with .NET Lifetime Events

[Section titled “Using LicenseUsageSummary with .NET Lifetime Events”](#using-licenseusagesummary-with-net-lifetime-events)

In .NET, an [`IHost`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.hosting.ihostapplicationlifetime) implementation allows developers to subscribe to application lifetime events, including **Application Started**, **Application Stopped**, and **Application Stopping**. IdentityServer tracks usage metrics internally and that information may be accessed by developers at any time during the application’s lifetime from the application’s service collection using the following code snippet.

```csharp
// from a valid services scope
app.Services.GetRequiredService();
```

For self-auditing purposes, we recommend using the `IHost` lifetime event `ApplicationStopping` as shown in the example below.

Note, `LicenseUsageSummary` is *`read-only`*.

```csharp
app.Lifetime.ApplicationStopping.Register(() =>
{
  var usage = app.Services.GetRequiredService();
  // Todo: Substitue a different logging mechanism
  Console.Write(Summary(usage));
});
```

Developers may also use common dependency injection techniques such as property or constructor injection.

```csharp
// An ASP.NET Core MVC Controller
public class MyController : Controller
{
    public MyController(LicenseUsageSummary summary)
    {
        // use the summary information
    }
}
```

Developers can use the license usage summary to determine if their organization is within their current licensing tier or if they need to make adjustments to stay within compliance of [Duende licensing terms](https://duendesoftware.com/products/identityserver).
-----
# Secrets

> Reference documentation for secret handling in Duende IdentityServer, including the ISecretParser interface for extracting secrets from HTTP requests, the ParsedSecret class, and the ISecretValidator interface.

## Duende.IdentityServer.Validation.ISecretParser

[Section titled “Duende.IdentityServer.Validation.ISecretParser”](#duendeidentityservervalidationisecretparser)

Parses a secret from the raw HTTP request.

```csharp
public interface ISecretParser
{
    /// 

    /// Tries to find a secret on the context that can be used for authentication
    /// 
    /// The HTTP context.
    /// A parsed secret
    Task ParseAsync(HttpContext context);


    /// 

    /// Returns the authentication method name that this parser implements
    /// 
    /// The authentication method.
    string AuthenticationMethod { get; }
}
```

* **`AuthenticationMethod`**

  The name of the authentication method that this parser registers for. This value must be unique and will be displayed in the discovery document.

* **`ParseAsync`**

  The job of this method is to extract the secret from the HTTP request and parse it into a `ParsedSecret`

#### Duende.IdentityServer.Model.ParsedSecret

[Section titled “Duende.IdentityServer.Model.ParsedSecret”](#duendeidentityservermodelparsedsecret)

Represents a parsed secret.

```csharp
/// 

/// Represents a secret extracted from the HttpContext
/// 
public class ParsedSecret
{
    /// 

    /// Gets or sets the identifier associated with this secret
    /// 
    /// 
    /// The identifier.
    /// 
    public string Id { get; set; }


    /// 

    /// Gets or sets the credential to verify the secret
    /// 
    /// 
    /// The credential.
    /// 
    public object Credential { get; set; }


    /// 

    /// Gets or sets the type of the secret
    /// 
    /// 
    /// The type.
    /// 
    public string Type { get; set; }


    /// 

    /// Gets or sets additional properties.
    /// 
    /// 
    /// The properties.
    /// 
    public Dictionary Properties { get; set; } = new Dictionary();
}
```

The parsed secret is forwarded to the registered secret validator. The validator will typically inspect the `Type` property to determine if this secret is something that can be validated by that validator instance. If yes, it will know how to cast the `Credential` object into a format that is understood.

#### Duende.IdentityServer.Validation.ISecretValidator

[Section titled “Duende.IdentityServer.Validation.ISecretValidator”](#duendeidentityservervalidationisecretvalidator)

Validates a parsed secret.

```csharp
public interface ISecretValidator
{
    /// 
Validates a secret
    /// The stored secrets.
    /// The received secret.
    /// A validation result
    Task ValidateAsync(
      IEnumerable secrets,
      ParsedSecret parsedSecret);
}
```
-----
# IdentityServer Options

> 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.

#### Duende.IdentityServer.Configuration.IdentityServerOptions

[Section titled “Duende.IdentityServer.Configuration.IdentityServerOptions”](#duendeidentityserverconfigurationidentityserveroptions)

The `IdentityServerOptions` is the central place to configure fundamental settings in Duende IdentityServer.

You set the options when registering IdentityServer at startup time, using a lambda expression in the AddIdentityServer method:

Program.cs

```csharp
var idsvrBuilder = builder.Services.AddIdentityServer(options =>
{
    // configure options here..
})
```

## Main

[Section titled “Main”](#main)

Top-level settings. Available directly on the `IdentityServerOptions` object.

* **`IssuerUri`**

  The name of the token server, used in the discovery document as the `issuer` claim and in JWT tokens and introspection responses as the `iss` claim.

  It is not recommended to set this option. If it is not set (the default), the issuer is inferred from the URL used by clients. This better conforms to the OpenID Connect specification, which requires that issuer values be “identical to the Issuer URL that was directly used to retrieve the configuration information”. It is also more convenient for clients to validate the issuer of tokens, because they will not need additional configuration or customization to know the expected issuer.

  If you need to access IdentityServer on a different address from the expected issuer value, for example internally in a Kubernetes cluster, setting the issuer is a good practice. Note that when doing so, you will need to set the OpenID Connect metadata address manually in your client application to prevent the address derived from the authority from being used.

* **`LowerCaseIssuerUri`**

  Controls the casing of inferred `IssuerUri`s. When set to `false`, the original casing of the IssuerUri in requests is preserved. When set to `true`, the `IssuerUri` is converted to lowercase. Defaults to `true`.

* **`AccessTokenJwtType`**

  The value used for the `typ` header in JWT access tokens. Defaults to `at+jwt`, as specified by the [RFC 9068](https://datatracker.ietf.org/doc/html/rfc9068). If `AccessTokenJwtType` is set to `null` or the empty string, the `typ` header will not be emitted in JWT access tokens.

* **`LogoutTokenJwtType`**

  The value for the `typ` header in back-channel logout tokens. Defaults to “logout+jwt”, as specified by [OpenID Connect Back-Channel Logout 1.0](https://openid.net/specs/openid-connect-backchannel-1_0.html#logouttoken).

* **`EmitScopesAsSpaceDelimitedStringInJwt`**

  Controls the format of scope claims in JWTs and introspection responses. Historically scopes values were emitted as an array in JWT access tokens. [RFC 9068](https://datatracker.ietf.org/doc/html/rfc9068) now specifies a space delimited string instead. Defaults to `false` for backwards compatibility.

* **`EmitStaticAudienceClaim`**

  Emits a static `aud` (audience) claim in all access tokens with the format `{issuer}/resources`. For example, if IdentityServer was running at `https://identity.example.com`, the static `aud` claim’s value would be `https://identity.example.com/resources`. Historically, older versions of IdentityServer produced tokens with a static audience claim in this format. This flag is intended for use when you need to produce backwards-compatible access tokens. Also note that multiple audience claims are possible. If you enable this flag and also configure `ApiResource`s you can have both the static audience and audiences from the API resources. Defaults to `false`.

* **`EmitIssuerIdentificationResponseParameter`**

  Emits the `iss` response parameter on authorize responses, as specified by [RFC 9207](https://datatracker.ietf.org/doc/rfc9207/). Defaults to `true`.

* **`EmitStateHash`**

  Emits the s\_hash claim in identity tokens. The s\_hash claim is a hash of the state parameter that is specified in the OpenID Connect [Financial-grade API Security Profile](https://openid.net/specs/openid-financial-api-part-2-1_0.html). Defaults to `false`.

* **`StrictJarValidation`**

  Strictly validate JWT-secured authorization requests according to [RFC 9101](https://datatracker.ietf.org/doc/rfc9101/). When enabled, JWTs used to secure authorization requests must have the `typ` header value `oauth-authz-req+jwt` and JWT-secured authorization requests must have the HTTP `content-type` header value `application/oauth-authz-req+jwt`. This might break older OIDC conformant request objects. Defaults to `false`.

* **`ValidateTenantOnAuthorization`** Specifies if a user’s `tenant` claim is compared to the tenant `acr_values` parameter value to determine if the login page is displayed. Defaults to `false`.

## Key management

[Section titled “Key management”](#key-management)

Automatic key management settings. Available on the `KeyManagement` property of the `IdentityServerOptions` object.

* **`Enabled`**

  Enables automatic key management. Defaults to true.

* **`SigningAlgorithms`**

  The signing algorithms for which automatic key management will manage keys.

  This option is configured with a list of objects containing a Name property, which is the name of a supported signing algorithm, and a UseX509Certificate property, which is a flag indicating if the signing key should be wrapped in an X.509 certificate.

  The first algorithm in the collection will be used as the default for clients that do not specify `AllowedIdentityTokenSigningAlgorithms`.

  The supported signing algorithm names are `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512`, `ES256`, `ES384`, and `ES512`.

  X.509 certificates are not supported for `ES256`, `ES384`, and `ES512` keys.

  Defaults to `RS256` without an X.509 certificate.

Note

*X.509 certificates* have an expiration date, but IdentityServer does not use this data to validate the certificate and throw an exception. If a certificate has expired then you must decide whether to continue using it or replace it with a new certificate.

* **`RsaKeySize`** Key size (in bits) of RSA keys. The signing algorithms that use RSA keys (`RS256`, `RS384`, `RS512`, `PS256`, `PS384`, and `PS512`) will generate an RSA key of this length. Defaults to 2048.

* **`RotationInterval`**

  Age at which keys will no longer be used for signing, but will still be used in discovery for validation. Defaults to 90 days.

* **`PropagationTime`**

  Time expected to propagate new keys to all servers, and time expected all clients to refresh discovery. Defaults to 14 days.

* **`RetentionDuration`**

  Duration for keys to remain in discovery after rotation. Defaults to 14 days.

* **`DeleteRetiredKeys`**

  Automatically delete retired keys. Defaults to true.

* **`KeyPath`**

  Path for storing keys when using the default file system store. Defaults to the “keys” directory relative to the hosting application.

* **`DataProtectKeys`**

  Automatically protect keys in the storage using data protection. Defaults to true.

* **`KeyCacheDuration`**

  When in normal operation, duration to cache keys from store. Defaults to 24 hours.

* **`InitializationDuration`**

  When no keys have been created yet, this is the window of time considered to be an initialization period to allow all servers to synchronize if the keys are being created for the first time. Defaults to 5 minutes.

* **`InitializationSynchronizationDelay`**

  Delay used when re-loading from the store when the initialization period. It allows other servers more time to write new keys so other servers can include them. Defaults to 5 seconds.

* **`InitializationKeyCacheDuration`**

  Cache duration when within the initialization period. Defaults to 1 minute.

## Endpoints

[Section titled “Endpoints”](#endpoints)

Endpoint settings, including flags to disable individual endpoints and support for the request\_uri JAR parameter. Available on the `Endpoints` property of the `IdentityServerOptions` object.

* **`EnableAuthorizeEndpoint`**

  Enables the authorize endpoint. Defaults to true.

* **`EnableTokenEndpoint`**

  Enables the token endpoint. Defaults to true.

* **`EnableDiscoveryEndpoint`**

  Enables the discovery endpoint. Defaults to true.

* **`EnableUserInfoEndpoint`**

  Enables the user info endpoint. Defaults to true.

* **`EnableEndSessionEndpoint`**

  Enables the end session endpoint. Defaults to true.

* **`EnableCheckSessionEndpoint`**

  Enables the check session endpoint. Defaults to true.

* **`EnableTokenRevocationEndpoint`**

  Enables the token revocation endpoint. Defaults to true.

* **`EnableIntrospectionEndpoint`**

  Enables the introspection endpoint. Defaults to true.

* **`EnableDeviceAuthorizationEndpoint`**

  Enables the device authorization endpoint. Defaults to true.

* **`EnableBackchannelAuthenticationEndpoint`**

  Enables the backchannel authentication endpoint. Defaults to true.

* **`EnablePushedAuthorizationEndpoint`**

  Enables the pushed authorization endpoint. Defaults to true.

* **`EnableJwtRequestUri`** Enables the `request_uri` parameter for JWT-Secured Authorization Requests. This allows the JWT to be passed by reference. Disabled by default, due to the security implications of enabling the request\_uri parameter (see [RFC 9101 section 10.4](https://datatracker.ietf.org/doc/rfc9101/)).

## Discovery

[Section titled “Discovery”](#discovery)

Discovery settings, including flags to toggle sections of the discovery document and settings to add custom entries to it. Available on the `Discovery` property of the `IdentityServerOptions` object.

If you want to take full control over the rendering of the discovery and jwks documents, you can implement the `IDiscoveryResponseGenerator` interface (or derive from our default implementation).

* **`ShowEndpoints`**

  Shows endpoints (authorization\_endpoint, token\_endpoint, etc.) in the discovery document. Defaults to true.

* **`ShowKeySet`**

  Shows the jwks\_uri in the discovery document and enables the jwks endpoint. Defaults to true.

* **`ShowIdentityScopes`**

  Includes IdentityResources in the supported\_scopes of the discovery document. Defaults to true.

* **`ShowApiScopes`**

  Includes ApiScopes in the supported\_scopes of the discovery document. Defaults to true.

* **`ShowClaims`**

  Shows claims\_supported in the discovery document. Defaults to true.

* **`ShowResponseTypes`**

  Shows response\_types\_supported in the discovery document. Defaults to true.

* **`ShowResponseModes`**

  Shows response\_modes\_supported in the discovery document. Defaults to true.

* **`ShowGrantTypes`**

  Shows grant\_types\_supported in the discovery document. Defaults to true.

* **`ShowExtensionGrantTypes`**

  Includes extension grant types in the grant\_types\_supported of the discovery document. Defaults to true.

* **`ShowTokenEndpointAuthenticationMethods`**

  Shows token\_endpoint\_auth\_methods\_supported in the discovery document. Defaults to true.

* **`CustomEntries`** Adds custom elements to the discovery document. For example:

Program.cs

```csharp
var idsvrBuilder = builder.Services.AddIdentityServer(options =>
{
    options.Discovery.CustomEntries.Add("my_setting", "foo");
    options.Discovery.CustomEntries.Add("my_complex_setting",
        new
        {
            foo = "foo",
            bar = "bar"
        });
});
```

* **`ExpandRelativePathsInCustomEntries`** Expands paths in custom entries that begin with ”\~/” into absolute paths below the IdentityServer base address. Defaults to true. In the following example, if IdentityServer’s base address is `https://localhost:5001`, then `my_custom_endpoint`’s value will be expanded to `https://localhost:5001/custom`.

```csharp
options.Discovery.CustomEntries.Add("my_custom_endpoint", "~/custom");
```

## Authentication

[Section titled “Authentication”](#authentication)

Login/logout related settings. Available on the `Authentication` property of the `IdentityServerOptions`

* **`CookieAuthenticationScheme`** Sets the cookie authentication scheme configured by the host used for interactive users. If not set, the scheme will be inferred from the host’s default authentication scheme. This setting is typically used when AddPolicyScheme is used in the host as the default scheme.

* **`CookieLifetime`**

  The authentication cookie lifetime (only effective if the IdentityServer-provided cookie handler is used). Defaults to 10 hours.

* **`CookieSlidingExpiration`**

  Specifies if the cookie should be sliding or not (only effective if the IdentityServer-provided cookie handler is used). Defaults to false.

* **`CookieSameSiteMode`**

  Specifies the SameSite mode for the internal cookies. Defaults to None.

* **`RequireAuthenticatedUserForSignOutMessage`**

  Indicates if user must be authenticated to accept parameters to end session endpoint. Defaults to false.

* **`CheckSessionCookieName`**

  The name of the cookie used for the check session endpoint. Defaults to the constant `IdentityServerConstants.DefaultCheckSessionCookieName`, which has the value “idsrv.session”.

* **`CheckSessionCookieDomain`**

  The domain of the cookie used for the check session endpoint. Defaults to `null`.

* **`CheckSessionCookieSameSiteMode`**

  The SameSite mode of the cookie used for the check session endpoint. Defaults to None.

* **`RequireCspFrameSrcForSignout`**

  Enables all content security policy headers on the end session endpoint. For historical reasons, this option’s name mentions `frame-src`, but the content security policy headers on the end session endpoint also include other fetch directives, including a *default-src ‘none’* directive, which prevents most resources from being loaded by the end session endpoint, and a `style-src` directive that specifies the hash of the expected style on the page.

* **`CoordinateClientLifetimesWithUserSession`** (added in `v6.1`) When enabled, all clients’ token lifetimes (e.g. refresh tokens) will be tied to the user’s session lifetime. This means when the user logs out, any revokable tokens will be removed. If using server-side sessions, expired sessions will also remove any revokable tokens, and backchannel logout will be triggered. An individual client can override this setting with its own `CoordinateLifetimeWithUserSession` configuration setting.

## Events

[Section titled “Events”](#events)

Configures which [events](/identityserver/diagnostics/events/) should be raised at the registered event sink.

* **`RaiseSuccessEvents`**

  Enables success events. Defaults to false. Success events include all the events whose names are postfixed with “SuccessEvent”. In general, they are raised when properly formed and valid requests are processed without errors.

* **`RaiseFailureEvents`**

  Enables failure events. Defaults to false. Failure events include all the events whose names are postfixed with “FailureEvent”. In general, they are raised when an action has failed because of incorrect or badly formed parameters in a request. They indicate that the user or client calling IdentityServer has done something wrong and are analogous to a 400: bad request error.

* **`RaiseErrorEvents`**

  Enables Error events. Defaults to false. Error events are raised when an error has occurred, either because of invalid configuration or an unhandled exception. They indicate that there is something wrong within the token server or its configuration and are analogous to a 500: internal server error.

* **`RaiseInformationEvents`**

  Enables Information events. Defaults to false. Information events are emitted when an action has occurred that is of informational interest, but that is neither a success nor a failure. For example, when the end user grants, denies, or revokes consent, that is considered an information event, because these events capture a valid choice of the user rather than success or failure.

## Logging

[Section titled “Logging”](#logging)

Logging related settings, including filters that will remove sensitive values and unwanted exceptions from logs. Available on the `Logging` property of the `IdentityServerOptions` object.

* **`AuthorizeRequestSensitiveValuesFilter`**

  Collection of parameter names passed to the authorize endpoint that are considered sensitive and will be redacted in logs. Note that authorization parameters pushed to the Pushed Authorization Request (PAR) endpoint are eventually handled by the authorize request pipeline. This filter should be configured to exclude sensitive values wether or not they are pushed, and usually should be set to the same value as `PushedAuthorizationSensitiveValuesFilter`. Defaults to `client_secret`, `client_assertion`, `id_token_hint`. The default value was changed in version 7.2.2 to include `client_secret` and `client_assertion`.

* **`PushedAuthorizationSensitiveValuesFilter`**

  Collection of parameter names passed to the Pushed Authorization Request (PAR) endpoint that are considered sensitive and will be redacted in logs. Note that authorization parameters pushed to the PAR endpoint are eventually handled by the authorize request pipeline. This filter should be configured to exclude sensitive values that are pushed, and usually should be set to the same value as `AuthorizeRequestSensitiveValuesFilter`. Defaults to `client_secret`, `client_assertion`, `id_token_hint`.

* **`TokenRequestSensitiveValuesFilter`**

  Collection of parameter names passed to the token endpoint that are considered sensitive and will be redacted in logs. In `v7.0` and earlier, defaults to `client_secret`, `password`, `client_assertion`, `refresh_token`, and `device_code`. In `v7.1`, `subject_token` is also excluded.

* **`BackchannelAuthenticationRequestSensitiveValuesFilter`**

  Collection of parameter names passed to the backchannel authentication endpoint that are considered sensitive and will be redacted in logs. Defaults to `client_secret`, `client_assertion`, and `id_token_hint`.

* **`UnhandledExceptionLoggingFilter`** (added in `v6.2`)

  A function that is called when the IdentityServer middleware detects an unhandled exception, and is used to determine if the exception is logged. The arguments to the function are the HttpContext and the Exception. It should return true to log the exception, and false to suppress. The default is to suppress logging of cancellation-related exceptions when the `CancellationToken` on the `HttpContext` has requested cancellation. Such exceptions are thrown when Http requests are canceled, which is an expected occurrence. Logging them creates unnecessary noise in the logs. In `v7.0` and earlier, only `TaskCanceledException`s were filtered. Beginning in `v7.1`, `OperationCanceledException`s are filtered as well.

## InputLengthRestrictions

[Section titled “InputLengthRestrictions”](#inputlengthrestrictions)

Settings that control the allowed length of various protocol parameters, such as client id, scope, redirect URI etc. Available on the `InputLengthRestrictions` property of the `IdentityServerOptions` object.

* **`ClientId`**

  Max length for ClientId. Defaults to 100.

* **`ClientSecret`**

  Max length for external client secrets. Defaults to 100.

* **`Scope`**

  Max length for scope. Defaults to 300.

* **`RedirectUri`**

  Max length for redirect\_uri. Defaults to 400.

* **`Nonce`**

  Max length for nonce. Defaults to 300.

* **`UiLocale`**

  Max length for ui\_locale. Defaults to 100.

* **`LoginHint`**

  Max length for login\_hint. Defaults to 100.

* **`AcrValues`**

  Max length for acr\_values. Defaults to 300.

* **`GrantType`**

  Max length for grant\_type. Defaults to 100.

* **`UserName`**

  Max length for username. Defaults to 100.

* **`Password`**

  Max length for password. Defaults to 100.

* **`CspReport`**

  Max length for CSP reports. Defaults to 2000.

* **`IdentityProvider`**

  Max length for external identity provider name. Defaults to 100.

* **`ExternalError`**

  Max length for external identity provider errors. Defaults to 100.

* **`AuthorizationCode`**

  Max length for authorization codes. Defaults to 100.

* **`DeviceCode`**

  Max length for device codes. Defaults to 100.

* **`RefreshToken`**

  Max length for refresh tokens. Defaults to 100.

* **`TokenHandle`**

  Max length for token handles. Defaults to 100.

* **`Jwt`**

  Max length for JWTs. Defaults to 51200.

* **`CodeChallengeMinLength`**

  Min length for the code challenge. Defaults to 43.

* **`CodeChallengeMaxLength`**

  Max length for the code challenge. Defaults to 128.

* **`CodeVerifierMinLength`**

  Min length for the code verifier. Defaults to 43.

* **`CodeVerifierMaxLength`**

  Max length for the code verifier. Defaults to 128.

* **`ResourceIndicatorMaxLength`**

  Max length for resource indicator parameter. Defaults to 512.

* **`BindingMessage`**

  Max length for binding\_message. Defaults to 100.

* **`UserCode`**

  Max length for user\_code. Defaults to 100.

* **`IdTokenHint`**

  Max length for id\_token\_hint. Defaults to 4000.

* **`LoginHintToken`**

  Max length for login\_hint\_token. Defaults to 4000.

* **`AuthenticationRequestId`** Max length for auth\_req\_id. Defaults to 100.

## UserInteraction

[Section titled “UserInteraction”](#userinteraction)

User interaction settings, including urls for pages in the UI, names of parameters to those pages, and other settings related to interactive flows. Available on the `UserInteraction` property of the `IdentityServerOptions` object.

* **`LoginUrl`**, **`LogoutUrl`**, **`ConsentUrl`**, **`ErrorUrl`**, **`DeviceVerificationUrl`**

  Sets the URLs for the login, logout, consent, error and device verification pages.

* **`CreateAccountUrl`** (added in `v6.3`)

  Sets the URL for the create account page, which is used by OIDC requests that include the `prompt=create` parameter. When this option is set, including the `prompt=create` parameter will cause the user to be redirected to the specified url. `create` will also be added to the discovery document’s `prompt_values_supported` array to announce support for this feature. When this option is not set, the `prompt=create` parameter is ignored, and `create` is not added to discovery. Defaults to `null`.

* **`LoginReturnUrlParameter`**

  Sets the name of the return URL parameter passed to the login page. Defaults to `returnUrl`.

* **`LogoutIdParameter`**

  Sets the name of the logout message id parameter passed to the logout page. Defaults to `logoutId`.

* **`ConsentReturnUrlParameter`**

  Sets the name of the return URL parameter passed to the consent page. Defaults to `returnUrl`.

* **`ErrorIdParameter`**

  Sets the name of the error message id parameter passed to the error page. Defaults to `errorId`.

* **`CustomRedirectReturnUrlParameter`**

  Sets the name of the return URL parameter passed to a custom redirect from the authorization endpoint. Defaults to `returnUrl`.

* **`DeviceVerificationUserCodeParameter`**

  Sets the name of the user code parameter passed to the device verification page. Defaults to `userCode`.

* **`CookieMessageThreshold`**

  Certain interactions between IdentityServer and some UI pages require a cookie to pass state and context (any of the pages above that have a configurable “message id” parameter). Since browsers have limits on the number of cookies and their size, this setting is used to prevent too many cookies being created. The value sets the maximum number of message cookies of any type that will be created. The oldest message cookies will be purged once the limit has been reached. This effectively indicates how many tabs can be opened by a user when using IdentityServer. Defaults to 2.

* **`AllowOriginInReturnUrl`**

  Flag that allows return URL validation to accept full URL that includes the IdentityServer origin. Defaults to `false`.

* **`PromptValuesSupported`** (added in `v7.0.7`)

  The collection of OIDC prompt modes supported and that will be published in discovery. By default, this includes all values in `Constants.SupportedPromptModes`. If the `CreateAccountUrl` option is set, then the “create” value is also included. If additional prompt values are added, a customized [`IAuthorizeInteractionResponseGenerator"`](/identityserver/ui/custom/) is also required to handle those values.

## Caching

[Section titled “Caching”](#caching)

Caching settings for the stores. Available on the `Caching` property of the `IdentityServerOptions` object. These settings only apply if the respective caching has been enabled in the services configuration in startup.

* **`ClientStoreExpiration`**

  Cache duration of client configuration loaded from the client store. Defaults to 15 minutes.

* **`ResourceStoreExpiration`**

  Cache duration of identity and API resource configuration loaded from the resource store. Defaults to 15 minutes.

* **`CorsExpiration`**

  Cache duration of CORS configuration loaded from the CORS policy service. Defaults to 15 minutes.

* **`IdentityProviderCacheDuration`**

  Cache duration of identity provider configuration loaded from the identity provider store. Defaults to 60 minutes.

* **`CacheLockTimeout`**

  The timeout for concurrency locking in the default cache. Defaults to 60 seconds.

## CORS

[Section titled “CORS”](#cors)

CORS settings for IdentityServer’s endpoints. Available on the `Cors` property of the `IdentityServerOptions` object. The underlying CORS implementation is provided from ASP.NET Core, and as such it is automatically registered in the dependency injection system.

* **`CorsPolicyName`**

  Name of the CORS policy that will be evaluated for CORS requests into IdentityServer. Defaults to `IdentityServer`. The policy provider that handles this is implemented in terms of the `ICorsPolicyService` registered in the dependency injection system. If you wish to customize the set of CORS origins allowed to connect, then it is recommended that you provide a custom implementation of `ICorsPolicyService`.

* **`CorsPaths`**

  The endpoints within IdentityServer where CORS is supported. Defaults to the discovery, user info, token, and revocation endpoints.

* **`PreflightCacheDuration`**

  Indicates the value to be used in the preflight `Access-Control-Max-Age` response header. Defaults to `null` indicating no caching header is set on the response.

## Content Security Policy

[Section titled “Content Security Policy”](#content-security-policy)

Settings for Content Security Policy (CSP) headers that IdentityServer emits. Available on the `Csp` property of the `IdentityServerOptions` object.

* **`Level`**

  The level of CSP to use. CSP Level 2 is used by default, but this can be changed to `CspLevel.One` to accommodate older browsers.

* **`AddDeprecatedHeader`** Indicates if the older `X-Content-Security-Policy` CSP header should also be emitted in addition to the standards-based header value. Defaults to `true`.

## Device Flow

[Section titled “Device Flow”](#device-flow)

OAuth device flow settings. Available on the `DeviceFlow` property of the `IdentityServerOptions` object.

* **`DefaultUserCodeType`**

  The user code type to use, unless set at the client level. Defaults to `Numeric`, a 9-digit code.

* **`Interval`**

  The maximum frequency in seconds that a client may poll the token endpoint in the device flow. Defaults to `5`.

## Mutual TLS

[Section titled “Mutual TLS”](#mutual-tls)

[Mutual TLS](/identityserver/tokens/client-authentication/) settings. Available on the `MutualTls` property of the `IdentityServerOptions` object.

Program.cs

```csharp
var builder = services.AddIdentityServer(options =>
{
    options.MutualTls.Enabled = true;


    // use mtls subdomain
    options.MutualTls.DomainName = "mtls";


    options.MutualTls.AlwaysEmitConfirmationClaim = true;
})
```

* **`Enabled`**

  Specifies if MTLS support should be enabled. Defaults to `false`.

* **`ClientCertificateAuthenticationScheme`**

  Specifies the name of the authentication handler for X.509 client certificates. Defaults to `Certificate`.

* **`DomainName`**

  Specifies either the name of the subdomain or full domain for running the MTLS endpoints. MTLS will use path-based endpoints if not set (the default). Use a simple string (e.g. “mtls”) to set a subdomain, use a full domain name (e.g. “identityserver-mtls.io”) to set a full domain name. When a full domain name is used, you also need to set the `IssuerUri` to a fixed value.

* **`AlwaysEmitConfirmationClaim`**

  Specifies whether a cnf claim gets emitted for access tokens if a client certificate was present. Normally the cnf claims only gets emitted if the client used the client certificate for authentication, setting this to true, will set the claim regardless of the authentication method. Defaults to false.

## PersistentGrants

[Section titled “PersistentGrants”](#persistentgrants)

Shared settings for persisted grants behavior.

* **`DataProtectData`**

  Data protect the persisted grants “data” column. Defaults to `true`. If your database is already protecting data at rest, then you can consider disabling this.

* **`DeleteOneTimeOnlyRefreshTokensOnUse`** (added in `v6.3`)

  When Refresh tokens that are configured with RefreshTokenUsage.OneTime are used, this option controls if they will be deleted immediately or retained and marked as consumed. The default is on - immediately delete.

## Dynamic Providers

[Section titled “Dynamic Providers”](#dynamic-providers)

Settings for [dynamic providers](/identityserver/ui/login/dynamicproviders/). Available on the `DynamicProviders` property of the `IdentityServerOptions` object.

* **`PathPrefix`**

  Prefix in the pipeline for callbacks from external providers. Defaults to “/federation”.

* **`SignInScheme`**

  Scheme used for signin. Defaults to the constant `IdentityServerConstants.ExternalCookieAuthenticationScheme`, which has the value “idsrv.external”.

* **`SignOutScheme`** Scheme for signout. Defaults to the constant `IdentityServerConstants.DefaultCookieAuthenticationScheme`, which has the value “idsrv”.

## CIBA

[Section titled “CIBA”](#ciba)

[CIBA](/identityserver/ui/ciba/) settings. Available on the `Ciba` property of the `IdentityServerOptions` object.

* **`DefaultLifetime`**

  The default lifetime of the pending authentication requests in seconds. Defaults to 300.

* **`DefaultPollingInterval`** The maximum frequency in seconds that a client may poll the token endpoint in the CIBA flow. Defaults to 5.

## Server-Side Sessions

[Section titled “Server-Side Sessions”](#server-side-sessions)

Settings for [server-side sessions](/identityserver/ui/server-side-sessions/). Added in `v6.1`. Available on the `ServerSideSessions` property of the `IdentityServerOptions` object.

* **`UserDisplayNameClaimType`**

  Claim type used for the user’s display name. Unset by default due to possible PII concerns. If used, this would commonly be `JwtClaimTypes.Name`, `JwtClaimType.Email` or a custom claim.

* **`RemoveExpiredSessions`**

  Enables periodic cleanup of expired sessions. Defaults to true.

* **`RemoveExpiredSessionsFrequency`**

  Frequency that expired sessions will be removed. Defaults to 10 minutes.

* **`RemoveExpiredSessionsBatchSize`**

  Number of expired session records to be removed at a time. Defaults to 100.

* **`ExpiredSessionsTriggerBackchannelLogout`**

  If enabled, when server-side sessions are removed due to expiration, back-channel logout notifications will be sent. This will, in effect, tie a user’s session lifetime at a client to their session lifetime at IdentityServer. Defaults to false.

* **`FuzzExpiredSessionRemovalStart`**

  The background session cleanup job runs at a configured interval. If multiple nodes run the cleanup job at the same time update conflicts might occur in the store. To reduce the propability of that happening, the startup time can be fuzzed. The first run is scheduled at a random time between the host startup and the configured RemoveExpiredSessionsFrequency. Subsequent runs are run on the configured RemoveExpiredSessionsFrequency. Defaults to `true`.

## Validation

[Section titled “Validation”](#validation)

* **`InvalidRedirectUriPrefixes`**

  Collection of URI scheme prefixes that should never be used as custom URI schemes in the `redirect_uri` passed to tha authorize endpoint or the `post_logout_redirect_uri` passed to the end\_session endpoint. Defaults to *\[“javascript:”, “file:”, “data:”, “mailto:”, “ftp:”, “blob:”, “about:”, “ssh:”, “tel:”, “view-source:”, “ws:”, “wss:”]*.

## DPoP

[Section titled “DPoP”](#dpop)

Added in 6.3.0.

Demonstration of Proof-of-Possession settings. Available on the `DPoP` property of the `IdentityServerOptions` object.

* **`ProofTokenValidityDuration`**

  Duration that DPoP proof tokens are considered valid. Defaults to *1 minute*.

* **`ServerClockSkew`** Clock skew used in validating DPoP proof token expiration using a server-generated nonce value. Defaults to `0`.

## Pushed Authorization Requests

[Section titled “Pushed Authorization Requests”](#pushed-authorization-requests)

[Pushed Authorization Requests (PAR)](/identityserver/tokens/par/) settings. Added in `v7.0`. Available on the `PushedAuthorization` property of the `IdentityServerOptions` object.

* **`Required`**

  Causes PAR to be required globally. Defaults to `false`.

* **`Lifetime`**

  Controls the lifetime of pushed authorization requests. The pushed authorization request’s lifetime begins when the request to the PAR endpoint is received, and is validated until the authorize endpoint returns a response to the client application. Note that user interaction, such as entering credentials or granting consent, may need to occur before the authorize endpoint can do so. Setting the lifetime too low will likely cause login failures for interactive users, if pushed authorization requests expire before those users complete authentication. Some security profiles, such as the FAPI 2.0 Security Profile recommend an expiration within 10 minutes to prevent attackers from pre-generating requests. To balance these constraints, this lifetime defaults to 10 minutes.

## Diagnostics

[Section titled “Diagnostics”](#diagnostics)

[Diagnostic data](/identityserver/diagnostics/data/) settings. Added in `v7.3`. Available on the `Diagnostics` property of the `IdentityServerOptions` object.

* **`LogFrequency`**

  Frequency at which the diagnostic data is logged. Defaults to 1 hour.

* **`ChunkSize`**

  Maximum size of diagnostic data log message chunks in kilobytes. Defaults to 8160 bytes. 8 KB is a conservative limit for the max size of a log message that is imposed by some logging tools. We take 32 bytes less than that to allow for additional formatting of the log message.

## Preview Features

[Section titled “Preview Features”](#preview-features)

Preview Features settings. Available on the `Preview` property of the `IdentityServerOptions` object.

Note

Duende IdentityServer may ship preview features, which can be configured using preview options. Note that preview features can be removed and may break in future releases.

#### Discovery Document Cache

[Section titled “Discovery Document Cache”](#discovery-document-cache)

In large deployments of Duende IdentityServer, where a lot of concurrent users attempt to consume the [discovery endpoint](/identityserver/reference/v7/endpoints/discovery/) to retrieve metadata about your IdentityServer, you can increase throughput by enabling the discovery document cache preview using the *`EnableDiscoveryDocumentCache`* flag. This will cache discovery document information for the duration specified in the *`DiscoveryDocumentCacheDuration`* option.

It’s best to keep the cache time low if you use the *`CustomEntries`* element on the discovery document or implement a custom *`IDiscoveryResponseGenerator`*.

#### Strict Audience Validation

[Section titled “Strict Audience Validation”](#strict-audience-validation)

When using [*private key JWT*](/identityserver/tokens/client-authentication/#private-key-jwts), there is a theoretical vulnerability where a Relying Party trusting multiple OpenID Providers could be attacked if one of the OpenID Providers is malicious or compromised.

The OpenID Foundation proposed a two-part fix: strictly validate the audience and set an explicit `typ` header in the authentication JWT.

You can [enable strict audience validation in Duende IdentityServer](/identityserver/tokens/client-authentication/#strict-audience-validation) using the *`StrictClientAssertionAudienceValidation`* flag, which strictly validates that the audience is equal to the issuer and validates the token’s `typ` header.
-----
# Scope Parser

> Reference documentation for IScopeParser, which parses raw scope strings from authorization and token requests into structured ParsedScopeValue objects.

The `IScopeParser` interface is responsible for parsing the raw `scope` parameter from OAuth/OIDC requests into individual, structured scope values. While the default implementation treats scopes as simple space-delimited strings, custom implementations enable **parameterized scopes** - scopes that carry dynamic data like transaction IDs, tenant identifiers, or resource-specific parameters.

## When to Use

[Section titled “When to Use”](#when-to-use)

Use a custom scope parser when:

* Scopes carry runtime parameters (e.g., `transaction:abc123`, `tenant:acme`)
* You need to validate scope structure before further processing
* Scope values follow a convention that requires extraction of embedded data

## Interface

[Section titled “Interface”](#interface)

#### Duende.IdentityServer.Validation.IScopeParser

[Section titled “Duende.IdentityServer.Validation.IScopeParser”](#duendeidentityservervalidationiscopeparser)

```csharp
/// 

/// Allows parsing raw scopes values into structured scope values.
/// 
public interface IScopeParser
{
    /// 

    /// Parses the requested scopes.
    /// 
    ParsedScopesResult ParseScopeValues(IEnumerable scopeValues);
}
```

### ParseScopeValues

[Section titled “ParseScopeValues”](#parsescopevalues)

Receives the scope values as a collection (already split from the space-delimited request parameter) and returns a `ParsedScopesResult` containing:

* **`ParsedScopes`** - A collection of `ParsedScopeValue` objects, each with:

  * `RawValue` - The original scope string segment
  * `ParsedName` - The scope name (e.g., `"transaction"`)
  * `ParsedParameter` - The extracted parameter, if any (e.g., `"123"`)

* **`Errors`** - Any parsing errors encountered

* **`Succeeded`** - Whether parsing completed without errors

## Default Implementation

[Section titled “Default Implementation”](#default-implementation)

The `DefaultScopeParser` iterates over the scope values and creates a `ParsedScopeValue` for each. Override the virtual `ParseScopeValue` method to add custom parsing logic for parameterized scopes:

```csharp
public class ParameterizedScopeParser : DefaultScopeParser
{
    public ParameterizedScopeParser(ILogger logger) : base(logger)
    { }


    public override void ParseScopeValue(ParseScopeContext scopeContext)
    {
        // Custom parsing logic here
        // Call base.ParseScopeValue(scopeContext) for standard scopes
    }
}
```

### DefaultScopeParser.ParseScopeContext

[Section titled “DefaultScopeParser.ParseScopeContext”](#defaultscopeparserparsescopecontext)

The `ParseScopeContext` is a nested class within `DefaultScopeParser` that provides:

| Member                             | Description                                               |
| ---------------------------------- | --------------------------------------------------------- |
| `RawValue`                         | The original scope string being parsed                    |
| `ParsedName`                       | The parsed scope name (read after `SetParsedValues`)      |
| `ParsedParameter`                  | The parsed parameter value (read after `SetParsedValues`) |
| `Error`                            | The error message if parsing failed                       |
| `Ignore`                           | Whether this scope should be excluded from results        |
| `Succeeded`                        | `true` if not ignored and no error                        |
| `SetParsedValues(name, parameter)` | Sets the parsed scope name and parameter                  |
| `SetIgnore()`                      | Marks this scope to be excluded from results              |
| `SetError(message)`                | Marks this scope as invalid with an error message         |

## Common Scenarios

[Section titled “Common Scenarios”](#common-scenarios)

### Transaction or Resource IDs

[Section titled “Transaction or Resource IDs”](#transaction-or-resource-ids)

Scopes like `transaction:abc123` or `document:read:456` embed resource identifiers:

```csharp
public override void ParseScopeValue(ParseScopeContext scopeContext)
{
    const string prefix = "transaction:";


    if (scopeContext.RawValue.StartsWith(prefix))
    {
        var parameter = scopeContext.RawValue.Substring(prefix.Length);
        if (!string.IsNullOrEmpty(parameter))
        {
            scopeContext.SetParsedValues("transaction", parameter);
            return;
        }
        scopeContext.SetError("transaction scope requires a parameter");
        return;
    }


    base.ParseScopeValue(scopeContext);
}
```

Access the parsed parameter downstream in your `IProfileService`:

```csharp
var txScope = context.RequestedResources.ParsedScopes
    .FirstOrDefault(x => x.ParsedName == "transaction");


if (txScope?.ParsedParameter != null)
{
    context.IssuedClaims.Add(new Claim("transaction_id", txScope.ParsedParameter));
}
```

### Multi-Tenant Scopes

[Section titled “Multi-Tenant Scopes”](#multi-tenant-scopes)

Encode tenant context in scopes like `tenant:acme:read`:

```csharp
public override void ParseScopeValue(ParseScopeContext scopeContext)
{
    // Pattern: tenant:{tenant_id}:{permission}
    if (scopeContext.RawValue.StartsWith("tenant:"))
    {
        var parts = scopeContext.RawValue.Split(':', 3);
        if (parts.Length == 3)
        {
            // Store as "tenant:{permission}" with tenant ID as parameter
            scopeContext.SetParsedValues($"tenant:{parts[2]}", parts[1]);
            return;
        }
    }


    base.ParseScopeValue(scopeContext);
}
```

### Dynamic Scope Validation

[Section titled “Dynamic Scope Validation”](#dynamic-scope-validation)

Reject malformed or unauthorized scope patterns early:

```csharp
public override void ParseScopeValue(ParseScopeContext scopeContext)
{
    // Reject scopes with invalid characters
    if (scopeContext.RawValue.Contains("..") || scopeContext.RawValue.Contains("//"))
    {
        scopeContext.SetError("Invalid scope format");
        return;
    }


    // Ignore internal/debug scopes in production
    if (scopeContext.RawValue.StartsWith("debug:"))
    {
        scopeContext.SetIgnore();
        return;
    }


    base.ParseScopeValue(scopeContext);
}
```

## Registration

[Section titled “Registration”](#registration)

Register your custom scope parser in `ConfigureServices`:

```csharp
builder.Services.AddIdentityServer()
    .AddScopeParser();
```

## See Also

[Section titled “See Also”](#see-also)

[API Scopes](/identityserver/fundamentals/resources/api-scopes/)Learn about defining and using API scopes for access control

[Resource Validator](/identityserver/reference/v7/validators/resource-validator/)Validate whether requested scopes are allowed for a client
-----
# Response Generators

> An overview of IdentityServer's response generation pattern and customization options for protocol endpoint responses.

IdentityServer’s endpoints follow a pattern of abstraction in which a response generator uses a validated input model to produce a response model. The response model is a type that represents the data that will be returned from the endpoint. The response model is then wrapped in a result model, which is a type that facilitates serialization by an implementation of `IHttpResponseWriter`.

Customization of protocol endpoint responses is possible in both the response generators and response writers. Response generator customization is appropriate when you want to change the “business logic” of an endpoint and is typically accomplished by overriding virtual methods in the default response generator. Response writer customization is appropriate when you want to change the serialization, encoding, or headers of the HTTP response and is accomplished by registering a custom implementation of the `IHttpResponseWriter`.
-----
# Authorize Interaction Response Generator

> Documentation for the IAuthorizeInteractionResponseGenerator interface which determines if a user must log in or consent when making requests to the authorization endpoint.

#### Duende.IdentityServer.ResponseHandling.IAuthorizeInteractionResponseGenerator

[Section titled “Duende.IdentityServer.ResponseHandling.IAuthorizeInteractionResponseGenerator”](#duendeidentityserverresponsehandlingiauthorizeinteractionresponsegenerator)

The `IAuthorizeInteractionResponseGenerator` interface models the logic for determining if user must log in or consent when making requests to the authorization endpoint.

Note

If a custom implementation of `IAuthorizeInteractionResponseGenerator` is desired, then it’s [recommended](/identityserver/ui/custom/#built-in-authorizeinteractionresponsegenerator) to derive from the built-in `AuthorizeInteractionResponseGenerator` to inherit all the default logic pertaining to log in and consent semantics.

## IAuthorizeInteractionResponseGenerator APIs

[Section titled “IAuthorizeInteractionResponseGenerator APIs”](#iauthorizeinteractionresponsegenerator-apis)

* **`ProcessInteractionAsync`**

  Returns the `InteractionResponse` based on the `ValidatedAuthorizeRequest` an and optional `ConsentResponse` if the user was shown a consent page.

## InteractionResponse

[Section titled “InteractionResponse”](#interactionresponse)

* **`IsLogin`**

  Specifies if the user must log in.

* **`IsConsent`**

  Specifies if the user must consent.

* **`IsCreateAccount`**

  Added in `v6.3`.

  Specifies if the user must create an account.

* **`IsError`**

  Specifies if the user must be shown an error page.

* **`Error`**

  The error to display on the error page.

* **`ErrorDescription`**

  The description of the error to display on the error page.

* **`IsRedirect`**

  Specifies if the user must be redirected to a custom page for custom processing.

* **`RedirectUrl`**

  The URL for the redirect to the page for custom processing.
-----
# IHttpResponseWriter

> Documentation for the IHttpResponseWriter interface, a low-level abstraction for customizing serialization, encoding, and HTTP headers in protocol endpoint responses.

The `IHttpResponseWriter` interface is the contract for services that can produce HTTP responses for `IEndpointResult`s. This is a low-level abstraction that is intended to be used if you need to customize the serialization, encoding, or HTTP headers in a response from a protocol endpoint.

#### Duende.IdentityServer.Hosting.IHttpResponseWriter

[Section titled “Duende.IdentityServer.Hosting.IHttpResponseWriter”](#duendeidentityserverhostingihttpresponsewriter)

```csharp
/// 

/// Contract for a service that writes appropriate http responses for  objects.
/// 
public interface IHttpResponseWriter
    where T : IEndpointResult
{
    /// 

    /// Writes the endpoint result to the HTTP response.
    /// 
    Task WriteHttpResponse(T result, HttpContext context);
}
```

#### Duende.IdentityServer.Hosting.IEndpointResult

[Section titled “Duende.IdentityServer.Hosting.IEndpointResult”](#duendeidentityserverhostingiendpointresult)

```csharp
/// 

/// An  is the object model that describes the
/// results that will returned by one of the protocol endpoints provided by
/// IdentityServer, and can be executed to produce an HTTP response.
/// 
public interface IEndpointResult
{
    /// 

    /// Executes the result to write an http response.
    /// 
    /// The HTTP context.
    Task ExecuteAsync(HttpContext context);
}
```
-----
# Token Response Generator

> Documentation for the ITokenResponseGenerator interface and its implementation, which generates responses to valid token endpoint requests with customization options for different token flows.

## Duende.IdentityServer.ResponseHandling.ITokenResponseGenerator

[Section titled “Duende.IdentityServer.ResponseHandling.ITokenResponseGenerator”](#duendeidentityserverresponsehandlingitokenresponsegenerator)

The `ITokenResponseGenerator` interface is the contract for the service that generates responses to valid requests to the token endpoint. A response in this context refers to an object model that describes the content that will be serialized and transmitted in the HTTP response.

The default implementation is the `TokenResponseGenerator` class. You can customize the behavior of the token endpoint by providing your own implementation of the `ITokenResponseGenerator` to the ASP.NET Core service provider.

To create a customized implementation of `ITokenResponseGenerator`, we recommend that you create a class that derives from the default implementation. Your custom implementation should override the appropriate virtual methods of the default implementation and add your custom behavior to those overrides, possibly calling the base methods first and then manipulating their results.

## ITokenResponseGenerator

[Section titled “ITokenResponseGenerator”](#itokenresponsegenerator)

The `ITokenResponseGenerator` contains a single method to process validated token requests and return token responses.

* **`ProcessInteractionAsync`**

  Returns the `TokenResponse` based on the `ValidatedTokenRequest`.

## TokenResponseGenerator

[Section titled “TokenResponseGenerator”](#tokenresponsegenerator)

The default implementation of the `ITokenResponseGenerator` contains virtual methods that can be overridden to customize particular behavior for particular token requests.

* **`ProcessAsync`**

  Returns the `TokenResponse` for any `TokenRequestValidationResult`.

* **`ProcessClientCredentialsRequestAsync`**

  Returns the `TokenResponse` for a `TokenRequestValidationResult` from the client credentials flow.

* **`ProcessPasswordRequestAsync`**

  Returns the `TokenResponse` for a `TokenRequestValidationResult` from the resource owner password flow.

* **`ProcessAuthorizationCodeRequestAsync`**

  Returns the `TokenResponse` for a `TokenRequestValidationResult` from the authorization code flow.

* **`ProcessRefreshTokenRequestAsync`**

  Returns the `TokenResponse` for a `TokenRequestValidationResult` from the refresh token flow.

* **`ProcessDeviceCodeRequestAsync`**

  Returns the `TokenResponse` for a `TokenRequestValidationResult` from the device code flow.

* **`ProcessCibaRequestAsync`**

  Returns the `TokenResponse` for a `TokenRequestValidationResult` from the CIBA flow.

* **`ProcessExtensionGrantRequestAsync`**

  Returns the `TokenResponse` for a `TokenRequestValidationResult` from an extension grant.

* **`CreateAccessTokenAsync`**

  Creates an access token and optionally a refresh token.

* **`CreateIdTokenFromRefreshTokenRequestAsync`**

  Creates an ID token in a refresh token request.

## TokenResponse

[Section titled “TokenResponse”](#tokenresponse)

The `TokenResponse` class represents the data that will be included in the body of the response returned from the token endpoint. It contains properties for the various tokens that can be returned, the scope and expiration of the access token, and a mechanism for adding custom properties to the result. Omitting property values will cause the entire property to be absent from the response.

* **`IdentityToken`**

  The identity token.

* **`AccessToken`**

  The access token.

* **`RefreshToken`**

  The refresh token.

* **`AccessTokenLifetime`**

  The access token lifetime in seconds.

* **`Scope`**

  The scope.

* **`Custom`**

  A dictionary of strings to objects that will be serialized to json and added to the token response.
-----
# Backchannel Authentication Interaction Service

> Documentation for the IBackchannelAuthenticationInteractionService interface which provides services for accessing and completing CIBA login requests.

#### Duende.IdentityServer.Services.IBackchannelAuthenticationInteractionService

[Section titled “Duende.IdentityServer.Services.IBackchannelAuthenticationInteractionService”](#duendeidentityserverservicesibackchannelauthenticationinteractionservice)

The `IBackchannelAuthenticationInteractionService` interface provides services for a user to access or complete a login requests for [CIBA](/identityserver/ui/ciba/). It is available from the dependency injection system and would normally be injected as a constructor parameter into your MVC controllers for the user interface of IdentityServer.

## IBackchannelAuthenticationInteractionService APIs

[Section titled “IBackchannelAuthenticationInteractionService APIs”](#ibackchannelauthenticationinteractionservice-apis)

* **`GetPendingLoginRequestsForCurrentUserAsync`**

  Returns a collection of [BackchannelUserLoginRequest](/identityserver/reference/v7/models/ciba-login-request/) objects which represent pending login requests for the current user.

* **`GetLoginRequestByInternalIdAsync`**

  Returns the [BackchannelUserLoginRequest](/identityserver/reference/v7/models/ciba-login-request/) object for the id.

* **`CompleteLoginRequestAsync`**

  Completes the login request with the provided `CompleteBackchannelLoginRequest` response for the current user or the subject passed.

### CompleteBackchannelLoginRequest

[Section titled “CompleteBackchannelLoginRequest”](#completebackchannelloginrequest)

Models the data needed for a user to complete a backchannel authentication request.

* **`InternalId`**

  The internal store id for the request.

* **`ScopesValuesConsented`**

  Gets or sets the scope values consented to. Setting any scopes grants the login request. Leaving the scopes null or empty denies the request.

* **`Description`**

  Gets or sets the optional description to associate with the consent.

* **`Subject`**

  The subject for which the completion is being made. This allows more claims to be associated with the request that was identified on the backchannel authentication request. If not provided, then the `IUserSession` service will be consulting to obtain the current subject.

* **`SessionId`**

  The session id to associate with the completion request if the Subject is provided. If the Subject is not provided, then this property is ignored in favor of the session id provided by the `IUserSession` service.
-----
# Backchannel Authentication User Notification Service

> Documentation for the IBackchannelAuthenticationUserNotificationService interface which is used to notify users when a CIBA login request has been made.

#### Duende.IdentityServer.Services.IBackchannelAuthenticationUserNotificationService

[Section titled “Duende.IdentityServer.Services.IBackchannelAuthenticationUserNotificationService”](#duendeidentityserverservicesibackchannelauthenticationusernotificationservice)

The `IBackchannelAuthenticationUserNotificationService` interface is used to contact users when a [CIBA](/identityserver/ui/ciba/) login request has been made. To use CIBA, you are expected to implement this interface and register it in the ASP.NET Core service provider.

## IBackchannelAuthenticationUserNotificationService APIs

[Section titled “IBackchannelAuthenticationUserNotificationService APIs”](#ibackchannelauthenticationusernotificationservice-apis)

* **`SendLoginRequestAsync`**

  Sends a notification for the user to login via the [BackchannelUserLoginRequest](/identityserver/reference/v7/models/ciba-login-request/) parameter.
-----
# Device Flow Interaction Service

> Documentation for the IDeviceFlowInteractionService interface which provides services for user interfaces to communicate with IdentityServer during device flow authorization.

#### Duende.IdentityServer.Services.IDeviceFlowInteractionService

[Section titled “Duende.IdentityServer.Services.IDeviceFlowInteractionService”](#duendeidentityserverservicesideviceflowinteractionservice)

The `IDeviceFlowInteractionService` interface is intended to provide services to be used by the user interface to communicate with Duende IdentityServer during device flow authorization. It is available from the dependency injection system and would normally be injected as a constructor parameter into your MVC controllers for the user interface of IdentityServer.

## IDeviceFlowInteractionService APIs

[Section titled “IDeviceFlowInteractionService APIs”](#ideviceflowinteractionservice-apis)

* **`GetAuthorizationContextAsync(string userCode)`**

  Returns the `DeviceFlowAuthorizationRequest` based on the `userCode` passed to the login or consent pages.

* **`HandleRequestAsync(string userCode, ConsentResponse consent)`**

  Completes device authorization for the given `userCode`.

## DeviceFlowAuthorizationRequest

[Section titled “DeviceFlowAuthorizationRequest”](#deviceflowauthorizationrequest)

* **`Client`**

  The client that initiated the device authorization request.

* **`ValidatedResources`**

  The validated resources (scopes and resource indicators) requested by the client.

## DeviceFlowInteractionResult

[Section titled “DeviceFlowInteractionResult”](#deviceflowinteractionresult)

* **`IsError`**

  Specifies if the authorization request errored.

* **`IsAccessDenied`**

  Gets or sets a value indicating whether the user denied access.

* **`ErrorDescription`**

  Error description upon failure.

* **`Failure(string errorDescription = null)`** *(static method)*

  Creates a `DeviceFlowInteractionResult` indicating failure with an optional error description.
-----
# IdentityServer Interaction Service

> Documentation for the IIdentityServerInteractionService interface which provides services for user interfaces to communicate with IdentityServer for authorization, consent, logout, and other user interactions.

#### Duende.IdentityServer.Services.IIdentityServerInteractionService

[Section titled “Duende.IdentityServer.Services.IIdentityServerInteractionService”](#duendeidentityserverservicesiidentityserverinteractionservice)

The `IIdentityServerInteractionService` interface is intended to provide services to be used by the user interface to communicate with IdentityServer, mainly pertaining to user interaction. It is available from the dependency injection system and would normally be injected as a constructor parameter into your MVC controllers for the user interface of IdentityServer.

## IIdentityServerInteractionService APIs

[Section titled “IIdentityServerInteractionService APIs”](#iidentityserverinteractionservice-apis)

* **`GetAuthorizationContextAsync`**

  Returns the `AuthorizationRequest` based on the `returnUrl` passed to the login or consent pages.

* **`IsValidReturnUrl`**

  Indicates if the `returnUrl` is a valid URL for redirect after login or consent.

* **`GetErrorContextAsync`**

  Returns the `ErrorMessage` based on the `errorId` passed to the error page.

* **`GetLogoutContextAsync`**

  Returns the `LogoutRequest` based on the `logoutId` passed to the logout page.

* **`CreateLogoutContextAsync`**

  Used to create a `logoutId` if there is not one presently. This creates a cookie capturing all the current state needed for signout and the `logoutId` identifies that cookie. This is typically used when there is no current `logoutId` and the logout page must capture the current user’s state needed for sign-out prior to redirecting to an external identity provider for signout. The newly created `logoutId` would need to be roundtripped to the external identity provider at signout time, and then used on the signout callback page in the same way it would be on the normal logout page.

* **`GrantConsentAsync`**

  Accepts a `ConsentResponse` to inform IdentityServer of the user’s consent to a particular `AuthorizationRequest`.

* **`DenyAuthorizationAsync`**

  Accepts a `AuthorizationError` to inform IdentityServer of the error to return to the client for a particular `AuthorizationRequest`.

* **`GetAllUserGrantsAsync`**

  Returns a collection of `Grant` for the user. These represent a user’s consent or a clients access to a user’s resource.

* **`RevokeUserConsentAsync`**

  Revokes all of a user’s consents and grants for a client.

* **`RevokeTokensForCurrentSessionAsync`**

  Revokes all of a user’s consents and grants for clients the user has signed in to during their current session.

## Returned models

[Section titled “Returned models”](#returned-models)

The above methods return various models.

### AuthorizationRequest

[Section titled “AuthorizationRequest”](#authorizationrequest)

* **`Client`**

  The client that initiated the request.

* **`RedirectUri`**

  The URI to redirect the user to after successful authorization.

* **`DisplayMode`**

  The display mode passed from the authorization request.

* **`UiLocales`**

  The UI locales passed from the authorization request.

* **`IdP`** The external identity provider requested. This is used to bypass home realm discovery (HRD). This is provided via the “idp:” prefix to the `acr_values` parameter on the authorize request.

* **`Tenant`**

  The tenant requested. This is provided via the “tenant:” prefix to the `acr_values` parameter on the authorize request.

* **`LoginHint`**

  The expected username the user will use to login. This is requested from the client via the `login_hint` parameter on the authorize request.

* **`PromptMode`**

  The prompt mode requested from the authorization request.

* **`AcrValues`**

  The acr values passed from the authorization request.

* **`ValidatedResources`**

  The `ResourceValidationResult` which represents the validated resources from the authorization request.

* **`Parameters`**

  The entire parameter collection passed to the authorization request.

* **`RequestObjectValues`**

  The validated contents of the request object (if present).

### ResourceValidationResult

[Section titled “ResourceValidationResult”](#resourcevalidationresult)

* **`Resources`**

  The resources of the result.

* **`ParsedScopes`**

  The parsed scopes represented by the result.

* **`RawScopeValues`**

  The original (raw) scope values represented by the validated result.

### ErrorMessage

[Section titled “ErrorMessage”](#errormessage)

* **`Error`**

  The error code.

* **`ErrorDescription`**

  The error description.

* **`DisplayMode`**

  The display mode passed from the authorization request.

* **`UiLocales`**

  The UI locales passed from the authorization request.

* **`RequestId`**

  The per-request identifier. This can be used to display to the end user and can be used in diagnostics.

* **`ClientId`**

  The client id making the request (if available).

* **`RedirectUri`**

  The redirect URI back to the client (if available).

### LogoutRequest

[Section titled “LogoutRequest”](#logoutrequest)

* **`ClientId`**

  The client identifier that initiated the request.

* **`PostLogoutRedirectUri`**

  The URL to redirect the user to after they have logged out.

* **`SessionId`**

  The user’s current session id.

* **`SignOutIFrameUrl`**

  The URL to render in an `