IssuerNameRegistry Class

.NET Framework (current version)
 

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

NameDescription
System_CAPS_protmethodIssuerNameRegistry()

Initializes a new instance of the IssuerNameRegistry class.

NameDescription
System_CAPS_pubmethodEquals(Object)

Determines whether the specified object is equal to the current object.(Inherited from Object.)

System_CAPS_protmethodFinalize()

Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)

System_CAPS_pubmethodGetHashCode()

Serves as the default hash function. (Inherited from Object.)

System_CAPS_pubmethodGetIssuerName(SecurityToken)

When overridden in a derived class, returns the name of the issuer of the specified security token.

System_CAPS_pubmethodGetIssuerName(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.

System_CAPS_pubmethodGetType()

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_pubmethodGetWindowsIssuerName()

Returns the default issuer name to be used for Windows claims.

System_CAPS_pubmethodLoadCustomConfiguration(XmlNodeList)

When overridden in a derived class, loads custom configuration from XML.

System_CAPS_protmethodMemberwiseClone()

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_pubmethodToString()

Returns a string that represents the current object.(Inherited from Object.)

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”.

System_CAPS_warningWarning

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
Available since 4.5

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

Return to top
Show: