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:
var builder = services.AddIdentityServer(options =>
// configure options here..
Top-level settings. Available directly on the IdentityServerOptions object.
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.
Controls the casing of inferred IssuerUris. 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.
The value used for the typ header in JWT access tokens. Defaults to at+jwt, as specified by the RFC 9068. If AccessTokenJwtType is set to null or the empty string, the typ header will not be emitted in JWT access tokens.
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.
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 now specifies a space delimited string instead. Defaults to false for backwards compatibility.
Emits a static aud claim in all access tokens with the format issuer/resources. Defaults to false.
Emits the iss response parameter on authorize responses, as specified by RFC 9207. Defaults to true.
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. Defaults to false.
Strictly validate JWT-secured authorization requests according to RFC 9101. 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.
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.
Automatic key management settings. Available on the KeyManagement property of the IdentityServerOptions object.
Enables automatic key management. Defaults to true.
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.
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.
Age at which keys will no longer be used for signing, but will still be used in discovery for validation. Defaults to 90 days.
Time expected to propagate new keys to all servers, and time expected all clients to refresh discovery. Defaults to 14 days.
Duration for keys to remain in discovery after rotation. Defaults to 14 days.
Automatically delete retired keys. Defaults to true.
Path for storing keys when using the default file system store. Defaults to the “keys” directory relative to the hosting application.
Automatically protect keys in the storage using data protection. Defaults to true.
When in normal operation, duration to cache keys from store. Defaults to 24 hours.
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.
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.
Cache duration when within the initialization period. Defaults to 1 minute.
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.
Enables the authorize endpoint. Defaults to true.
Enables the token endpoint. Defaults to true.
Enables the discovery endpoint. Defaults to true.
Enables the user info endpoint. Defaults to true.
Enables the end session endpoint. Defaults to true.
Enables the check session endpoint. Defaults to true.
Enables the token revocation endpoint. Defaults to true.
Enables the introspection endpoint. Defaults to true.
Enables the device authorization endpoint. Defaults to true.
Enables the backchannel authentication 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).
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).
Shows endpoints (authorization_endpoint, token_endpoint, etc) in the discovery document. Defaults to true.
Shows the jwks_uri in the discovery document and enables the jwks endpoint. Defaults to true.
Includes IdentityResources in the supported_scopes of the discovery document. Defaults to true.
Includes ApiScopes in the supported_scopes of the discovery document. Defaults to true.
Shows claims_supported in the discovery document. Defaults to true.
Shows response_types_supported in the discovery document. Defaults to true.
Shows response_modes_supported in the discovery document. Defaults to true.
Shows grant_types_supported in the discovery document. Defaults to true.
Includes extension grant types in the grant_types_supported of the discovery document. Defaults to true.
Shows token_endpoint_auth_methods_supported in the discovery document. Defaults to true.
CustomEntries Adds custom elements to the discovery document. For example:
var builder = services.AddIdentityServer(options =>
foo = "foo",
bar = "bar"
Login/logout related settings. Available on the Authentication property of the IdentityServerOptions
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.
The authentication cookie lifetime (only effective if the IdentityServer-provided cookie handler is used). Defaults to 10 hours.
Specifies if the cookie should be sliding or not (only effective if the IdentityServer-provided cookie handler is used). Defaults to false.
Specifies the SameSite mode for the internal cookies. Defaults to None.
Indicates if user must be authenticated to accept parameters to end session endpoint. Defaults to false.
The name of the cookie used for the check session endpoint. Defaults to the constant IdentityServerConstants.DefaultCheckSessionCookieName, which has the value “idsrv.session”.
The domain of the cookie used for the check session endpoint. Defaults to null.
The SameSite mode of the cookie used for the check session endpoint. Defaults to None.
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 6.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.
Configures which events should be raised at the registered event sink.
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.
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.
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.
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 related settings, including filters that will remove sensitive values and unwanted exceptions from logs. Available on the Logging property of the IdentityServerOptions object.
Collection of parameter names passed to the authorize endpoint that are considered sensitive and will be excluded from logging. Defaults to id_token_hint.
Collection of parameter names passed to the token endpoint that are considered sensitive and will be excluded from logging. Defaults to client_secret, password, client_assertion, refresh_token, and device_code.
Collection of parameter names passed to the backchannel authentication endpoint that are considered senstivie and will be excluded from logging. Defaults to client_secret, client_assertion, and id_token_hint.
UnhandledExceptionLoggingFilter (Added in 6.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 TaskCanceledExceptions 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.
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.
Max length for ClientId. Defaults to 100.
Max length for external client secrets. Defaults to 100.
Max length for scope. Defaults to 300.
Max length for redirect_uri. Defaults to 400.
Max length for nonce. Defaults to 300.
Max length for ui_locale. Defaults to 100.
Max length for login_hint. Defaults to 100.
Max length for acr_values. Defaults to 300.
Max length for grant_type. Defaults to 100.
Max length for username. Defaults to 100.
Max length for password. Defaults to 100.
Max length for CSP reports. Defaults to 2000.
Max length for external identity provider name. Defaults to 100.
Max length for external identity provider errors. Defaults to 100.
Max length for authorization codes. Defaults to 100.
Max length for device codes. Defaults to 100.
Max length for refresh tokens. Defaults to 100.
Max length for token handles. Defaults to 100.
Max length for JWTs. Defaults to 51200.
Min length for the code challenge. Defaults to 43.
Max length for the code challenge. Defaults to 128.
Min length for the code verifier. Defaults to 43.
Max length for the code verifier. Defaults to 128.
Max length for resource indicator parameter. Defaults to 512.
Max length for binding_message. Defaults to 100.
Max length for user_code. Defaults to 100.
Max length for id_token_hint. Defaults to 4000.
Max length for login_hint_token. Defaults to 4000.
AuthenticationRequestId Max length for auth_req_id. Defaults to 100.
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.
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.
Sets the name of the return URL parameter passed to the login page. Defaults to returnUrl.
Sets the name of the logout message id parameter passed to the logout page. Defaults to logoutId.
Sets the name of the return URL parameter passed to the consent page. Defaults to returnUrl.
Sets the name of the error message id parameter passed to the error page. Defaults to errorId.
Sets the name of the return URL parameter passed to a custom redirect from the authorization endpoint. Defaults to returnUrl.
Sets the name of the user code parameter passed to the device verification page. Defaults to userCode.
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.
Flag that allows return URL validation to accept full URL that includes the IdentityServer origin. Defaults to false.
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.
Cache duration of client configuration loaded from the client store. Defaults to 15 minutes.
Cache duration of identity and API resource configuration loaded from the resource store. Defaults to 15 minutes.
Cache duration of CORS configuration loaded from the CORS policy service. Defaults to 15 minutes.
Cache duration of identity provider configuration loaded from the identity provider store. Defaults to 60 minutes.
The timeout for concurrency locking in the default cache. Defaults to 60 seconds.
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.
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.
The endpoints within IdentityServer where CORS is supported. Defaults to the discovery, user info, token, and revocation endpoints.
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.
Settings for Content Security Policy (CSP) headers that IdentityServer emits. Available on the Csp property of the IdentityServerOptions object.
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.
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.
OAuth device flow settings. Available on the DeviceFlow property of the IdentityServerOptions object.
The user code type to use, unless set at the client level. Defaults to Numeric, a 9-digit code.
The maximum frequency in seconds that a client may poll the token endpoint in the device flow. Defaults to 5.
Mutual TLS settings. Available on the MutualTls property of the IdentityServerOptions object.
var builder = services.AddIdentityServer(options =>
options.MutualTls.Enabled = true;
// use mtls sub-domain
options.MutualTls.DomainName = "mtls";
options.MutualTls.AlwaysEmitConfirmationClaim = true;
Specifies if MTLS support should be enabled. Defaults to false.
Specifies the name of the authentication handler for X.509 client certificates. Defaults to Certificate.
Specifies either the name of the sub-domain 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 sub-domain, 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 IssuerName to a fixed value.
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.
Shared settings for persisted grants behavior.
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 6.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.
Settings for dynamic providers. Available on the DynamicProviders property of the IdentityServerOptions object.
Prefix in the pipeline for callbacks from external providers. Defaults to “/federation”.
Scheme used for signin. Defaults to the constant IdentityServerConstants.ExternalCookieAuthenticationScheme, which has the value “idsrv.external”.
Scheme for signout. Defaults to the constant IdentityServerConstants.DefaultCookieAuthenticationScheme, which has the value “idsrv”.
CIBA settings. Available on the Ciba property of the IdentityServerOptions object.
The default lifetime of the pending authentication requests in seconds. Defaults to 300.
The maximum frequency in seconds that a client may poll the token endpoint in the CIBA flow. Defaults to 5.
Settings for server-side sessions. Added in 6.1. Available on the ServerSideSessions property of the IdentityServerOptions object.
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.
Enables periodic cleanup of expired sessions. Defaults to true.
Frequency that expired sessions will be removed. Defaults to 10 minutes.
Number of expired session records to be removed at a time. Defaults to 100.
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 true.
Added in 6.3.0.
Demonstration of Proof-of-Possession settings. Available on the DPoP property of the IdentityServerOptions object.
Duration that DPoP proof tokens are considered valid. Defaults to 1 minute.
Clock skew used in validating DPoP proof token expiration using a server-generated nonce value. Defaults to 0.