[Starting with the .NET Framework 4.5, Windows Identity Foundation (WIF) has been fully integrated into the .NET Framework. The version of WIF addressed by this topic, WIF 3.5, is deprecated and should only be used when developing against the .NET Framework 3.5 SP1 or the .NET Framework 4. For more information about WIF in the .NET Framework 4.5, also known as WIF 4.5, see the Windows Identity Foundation documentation in the .NET Framework 4.5 Development Guide.]
The Microsoft.IdentityModel.Tokens.IssuerNameRegistry class provides a name service that returns the issuer name of a given token. WIF provides the Microsoft.IdentityModel.Tokens.ConfigurationBasedIssuerNameRegistry class to demonstrate an easy way to get started, but it is recommended that developers write a custom implementation that derives from the IssuerNameRegistry class.
ConfigurationBasedIssuerNameRegistry takes in an X509 security token and returns an issuer name if the SHA-1-based thumbprint of the certificate exists in the ConfiguredTrustedIssuers property. ConfigurationBasedIssuerNameRegistry should first be configured with ConfiguredTrustedIssuers, which is a list of trusted issuers. ConfiguredTrustedIssuers is a dictionary of certificate thumbprints and issuer names.
Although the IssuerNameRegistry is the logical place to reject untrusted, unknown, or invalid issuers, keep in mind that the token handlers enforce PeerOrChainTrust validity on issuer certificates by default, so any similar checks in the IssuerNameRegistry will be redundant.
Note that the Microsoft.IdentityModel.Claims.Claim.Issuer property is of type String. This allows the issuer to be represented in a more descriptive manner and authentication and authorization decisions to be made based on the string value returned from the IssuerNameRegistry. It is recommended that developers use the IssuerNameRegistry as a trust decision point to reject unknown or untrusted issuers as soon as possible in the authentication pipeline.
The IssuerNameRegistry has three methods, which are called by default from the various token handlers.
Microsoft.IdentityModel.Tokens.IssuerNameRegistry.GetIssuerName(System.IdentityModel.Tokens.SecurityToken) is called for client certificate authentication on the issuer certificate of an incoming
Microsoft.IdentityModel.Tokens.IssuerNameRegistry.GetIssuerName(System.IdentityModel.Tokens.SecurityToken,System.String) is called for SAML issued token authentication on the signing certificate of an incoming SAML 1.1 or SAML 2 token. The string parameter is the requested issuer name from the “Issuer” in the SAML token.
Microsoft.IdentityModel.Tokens.IssuerNameRegistry.GetWindowsIssuerName is called during Windows authentication, and during map to Windows scenarios where additional Windows claims are added to the client’s identity.