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.
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.
LowerCaseIssuerUri
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.
AccessTokenJwtType
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.
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.
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 now specifies a space delimited string instead. Defaults to false for backwards compatibility.
EmitStaticAudienceClaim
Emits a static aud claim in all access tokens with the format issuer/resources. Defaults to false.
EmitIssuerIdentificationResponseParameter
Emits the iss response parameter on authorize responses, as specified by RFC 9207. 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. Defaults to false.
StrictJarValidation
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.
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.
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.
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.
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.
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).
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:
var builder = services.AddIdentityServer(options =>
{
options.Discovery.CustomEntries.Add("my_setting", "foo");
options.Discovery.CustomEntries.Add("my_complex_setting",
new
{
foo = "foo",
bar = "bar"
});
});
options.Discovery.CustomEntries.Add("my_custom_endpoint", "~/custom");
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 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.
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 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 excluded from logging. Defaults to id_token_hint.
TokenRequestSensitiveValuesFilter
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.
BackchannelAuthenticationRequestSensitiveValuesFilter
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.
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.
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.
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 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.
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.
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 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;
})
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 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.
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.
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 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.
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 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.
Settings for server-side sessions. Added in 6.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 true.
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:”].
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.