App Context Switches in IdentityModel

Microsoft.IdentityModel uses App Context switches to allow users to opt-in or opt-out of certain library behaviors. The currently applicable switches are located in AppContextSwitches class. The values of the switches are cached for the process lifetime upon first use to improve performance. It's not expected for the switch to be changed while the process is running unlike normal config. To set a switch, you can call AppContext.SetSwitch("Switch.Name", true);. See the official App Context switches documentation for more.

Some switches may be removed in the following major version and the related behaviors set as default.

Identity Model 8x

See currently applicable switches in AppContextSwitches.cs.

UseClaimsIdentityType

Version 8.0.0 introduces a new type - CaseSensitiveClaimsIdentity, which performs a case sensitive claim search when calling methods like FindFirst, 'FindAll, and 'HasClaims'. The current ClaimsIdentity, in .NET, retrieves claims in a case-insensitive manner which is different than querying the underlying SecurityToken. The new CaseSensitiveClaimsIdentityclass provides consistent retrieval logic withSecurityToken. The new CaseSensitiveClaimsIdentityis used instead ofClaimsIdentity` throughout the library. Use this switch to fall back to the previous behavior.

DontFailOnMissingTidValidateIssuerSigning

Starting with version 8.0.0, when validating the issuer signing key, the validation will fail if the 'tid' claim is missing in the token. This is the recommended behavior. This switch disables this check.

TryAllStringClaimsAsDateTime

Starting with version 7.6.1, when parsing a token, the library doesn't try to convert to DateTime any claims that are known to not be DateTime.

UseRfcDefinitionOfEpkAndKid

Enabling this switch improves the library's conformance to RFC 7518 with regards to how the header values for kid and epk are set in ECDH key wrap scenarios. The previous behavior erroneously used key ID of as the kid parameter, and did not automatically set epk as the spec defines. This switch enables the intended behavior where is used for kid and the public portion of is used for epk.

DoNotScrubExceptions

Version 8.8.0 updates some log and error messages (IDX10214, IDX10215) by cleaning up some data related to audience validation. If that extra information is needed for temporary debugging purposes, the current behavior can be reverted by using this switch.

Identity Model 7x

See currently applicable switches in AppContextSwitches.cs.

UseClaimsIdentityType

See the Identity Model 8x section above for details. Identity Model 8x uses CaseSensitiveClaimsIdentity by default. However Identity Model 7x still uses ClaimsIdentity by default and this switch can be used to enable the new behavior.

DontFailOnMissingTidValidateIssuerSigning

See the Identity Model 8x section above for details.

TryAllStringClaimsAsDateTime

See the Identity Model 8x section above for details.

SkipAuthenticationTagLengthValidation

In version 7.5.1 and earlier, Identity Model did not validate authentication tag length. This allowed for issues like #2201 or #1641, where one could append characters to the end of a token and still validate the token. While this was not a security issue, it was technically more correct to ensure that the authentication tag length is as expected based on the given algorithm. See IDX10625 for more details.

This context switch was removed in Identity Model 8x.

UseShortNameForRsaOaepKey

To enhance interoperability in our assemblies, we’ve implemented a context switch that maps the JWE header ‘alg’ attribute to “RSA-OAEP” instead of "http://www.w3.org/2001/04/xmlenc#rsa-oaep" when creating a new JwtSecurityToken. This aligns with the registered "JSON Web Signature and Encryption Algorithms" at IANA, as described in topic 4.1.1 of RFC7516. This switch resolves issue #2089 and is included in 7.6.0 release. See this PR for usage details.

This context switch was removed in Identity Model 8x.

Identity Model 6x

See currently applicable switches in AppContextSwitches.cs.

UseClaimsIdentityType

See the Identity Model 8x section above for details. Identity Model 8x uses CaseSensitiveClaimsIdentity by default. However Identity Model 6x still uses ClaimsIdentity by default and this switch can be used to enable the new behavior.

UnsafeRelaxHmacKeySizeValidation

In versions 6.30.0 and earlier, Microsoft.IdentityModel did not validate the key size when creating a JsonWebToken. According to the specification (RFC 7518), the key size must be the same or greater than the size of what the hash algorithm returns. For example, HS256 requires 256 bits, HS384 requires 384 bits, HS512 requires 512 bits. When the SymmetricKey is smaller than the required size, Identity Model will throw an ArgumentOutOfRangeException. See IDX10720 for more details.

This context switch was removed in Identity Model 7x.