Export (0) Print
Expand All

IssuerNameRegistry Class

.NET Framework 4.5

The abstract base class for an issuer name registry. An issuer name registry is used to associate a mnemonic name to the cryptographic material that is needed to verify the signatures of tokens produced by the corresponding issuer. The issuer name registry maintains a list of issuers that are trusted by a relying party (RP) application.

Namespace:  System.IdentityModel.Tokens
Assembly:  System.IdentityModel (in System.IdentityModel.dll)

public abstract class IssuerNameRegistry : ICustomIdentityConfiguration

The IssuerNameRegistry type exposes the following members.

  NameDescription
Protected methodIssuerNameRegistryInitializes a new instance of the IssuerNameRegistry class.
Top

  NameDescription
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetIssuerName(SecurityToken)When overridden in a derived class, returns the name of the issuer of the specified security token.
Public methodGetIssuerName(SecurityToken, String)When overridden in a derived class, returns the name of the issuer of the specified security token. The specified issuer name may be considered in determining the issuer name to return.
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodGetWindowsIssuerNameReturns the default issuer name to be used for Windows claims.
Public methodLoadCustomConfigurationWhen overridden in a derived class, loads custom configuration from XML.
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Top

The issuer name registry is used to associate a mnemonic name to the cryptographic material needed to verify signatures of tokens produced by the corresponding issuer. This name is then used to set the Issuer or the OriginalIssuer property of a claim. The methods exposed by the IssuerNameRegistry class are called from the pipeline by the security token handler that is processing the token. Tokens signed by material that is not mapped by an issuer name registry are discarded as untrusted. The name returned by the issuer name registry should be unique within the context of an RP application.

In code, you can specify the issuer name registry to use by setting the SecurityTokenHandlerConfiguration.IssuerNameRegistry property. In a configuration file, the issuer name registry can be specified by specifying the <issuerNameRegistry> element under the <securityTokenHandlerConfiguration> element.

Windows Identity Foundation (WIF) provides an implementation of the IssuerNameRegistry class out of the box: the ConfigurationBasedIssuerNameRegistry class. When you use this implementation you can specify the list of trusted issuers in the configuration file of the RP application under the <trustedIssuers> element, which is a child element of the <issuerNameRegistry> element when the ConfigurationBasedIssuerNameRegistry.class is referenced in that element’s type attribute. Under the <trustedIssuers> element, each issuer name is mapped to the X.509 certificate that should be used to verify its signature.

To create a custom issuer name registry, you must override the IssuerNameRegistry.GetIssuerName(SecurityToken) method. This method returns the issuer name for the specified security token. You can optionally override the IssuerNameRegistry.GetIssuerName(SecurityToken, String) method to provide a hinting mechanism when retrieving issuer names and the GetWindowsIssuerName method if you want to provide an issuer name for Windows tokens that is different from DefaultIssuer. Override the LoadCustomConfiguration method to enable your issuer name registry to be initialized from a configuration file.

The following code shows an implementation of the IssuerNameRegistry class that only accepts issuers that use certificates with subject “CN=localhost”.

Caution noteCaution

The following code is for illustrative purposes only. Validating certificates based on subject name is not a good practice. This code should not be used as is in production.

using System;
using System.IdentityModel.Tokens;

namespace System.IdentityModel.Samples
{
    /// <summary> 
    /// This class verifies that the issuer is trusted, and provides the issuer name. 
    /// </summary> 
    public class TrustedIssuerNameRegistry : IssuerNameRegistry
    {
        /// <summary> 
        /// Gets the issuer name of the given security token, 
        /// if it is the X509SecurityToken of 'localhost'. 
        /// </summary> 
        /// <param name="securityToken">The issuer's security token</param>
        /// <returns>A string that represents the issuer name</returns> 
        /// <exception cref="SecurityTokenException">If the issuer is not trusted.</exception>
        public override string GetIssuerName(SecurityToken securityToken)
        {
            X509SecurityToken x509Token = securityToken as X509SecurityToken;
            if (x509Token != null)
            {
                if (String.Equals(x509Token.Certificate.SubjectName.Name, "CN=localhost"))
                {
                    return x509Token.Certificate.SubjectName.Name;
                }
            }

            throw new SecurityTokenException("Untrusted issuer.");
        }
    }
}

The following shows the XML necessary to configure an application with the trusted issuer name registry.

  <system.identityModel>
    <identityConfiguration>
      <issuerNameRegistry type="System.IdentityModel.Samples.TrustedIssuerNameRegistry, MyApp" />
    </identityConfiguration>
  </system.identityModel>

.NET Framework

Supported in: 4.6, 4.5

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Show:
© 2014 Microsoft