ID4175–The issuer of the security token was not recognized by the IssuerNameRegistry

Yesterday I worked in close collaboration with one of my clients to renew the certificates on their ADFS server. Of course this wouldn't be an interesting post if nothing went wrong and there was nothing to learn.

Changing the certificate is quite easy. First upload the certificate to your ADFS instance through the ADFS Management UI:

• Open Server Manager
• Click on “Tools”. Select “AD FS Management” from the menu.
• Expand “Service” node and click on “Certificates”.
• Click on “Set Service Communication Certificate” on the right side.

Now you can activate this certificate using the following command:

Set-AdfsSslCertificate -Thumbprint {thumbprint}

That’s the easy part. So where did we get into trouble?

After changing the certificate, some of our .NET applications started to fail with the following error message:

ID4175: The issuer of the security token was not recognized by the IssuerNameRegistry. To accept security tokens from this issuer, configure the IssuerNameRegistry to return a valid name for this issuer.

Let me explain why this happened. As part of our older .NET (4.8) applications the related ADFS configuration is added directly inside the web.config. Among the information we provide in the web.config is the list of allowed issuername registries:

	<issuerNameRegistry type="System.IdentityModel.Tokens.ConfigurationBasedIssuerNameRegistry, System.IdentityModel, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089">
	<trustedIssuers>
	<add thumbprint="<thumbprint>" name="https://adfs.example.com/adfs/ls/" />
	</trustedIssuers>
	</issuerNameRegistry>

view raw web.config hosted with ❤ by GitHub

By changing the certificate the corresponding thumbprint has changed as well. As a consequence the original configuration is no longer valid.

Fixing this is easy, just update the thumbprint inside the configuration.

But is there a better way so that we can avoid to do this change in the future when we have to renew our certificates again?

Federation metadata

The answer can be found in ‘Federation metadata’. ADFS (and other STS products) publishes a federation metadata document on a federation metadata endpoint. This metadata document format is described in the Web Services Federation Language (WS-Federation) Version 1.2, which extends Metadata for the OASIS Security Assertion Markup Language (SAML) v2.0.

It contains (at least) the following information:

• Entity ID
• Token signing certificates
• WS-Federation endpoint URL
• SAML endpoint URL

The good news is that our application logic can automatically read this information avoiding the need to store all this information directly in our web.config. So instead of using the built-in ConfigurationBasedIssuerNameRegistry that reads the issuer information from the web.config, we create our own instance that parses the federation metadata.

A solution was created by Brock Allen in Thinktecture.IdentityModel but this library is no longer maintained.

Here is a copy of the relevant code:

	/*
	* Copyright (c) Dominick Baier, Brock Allen. All rights reserved.
	* see LICENSE
	*/
	using System;
	using System.Configuration;
	using System.IdentityModel.Metadata;
	using System.IdentityModel.Tokens;
	using System.IO;
	using System.Linq;
	using System.Net.Http;
	using System.Security.Cryptography.X509Certificates;
	using System.ServiceModel.Security;
	using System.Threading.Tasks;
	using System.Xml;
	namespace Thinktecture.IdentityModel.Metadata
	{
	public class MetadataBasedIssuerNameRegistry : IssuerNameRegistry
	{
	private Uri metadataAddress;
	private string issuerName;
	X509CertificateValidationMode mode;
	private static volatile ConfigurationBasedIssuerNameRegistry _registry;
	private static object _registryLock = new object();
	public MetadataBasedIssuerNameRegistry()
	{
	}
	public MetadataBasedIssuerNameRegistry(
	Uri metadataAddress,
	string issuerName,
	X509CertificateValidationMode mode = X509CertificateValidationMode.None,
	bool lazyLoad = false)
	{
	if (metadataAddress == null) throw new ArgumentNullException("metadataAddress");
	if (String.IsNullOrWhiteSpace(issuerName)) throw new ArgumentNullException("issuerName");
	this.metadataAddress = metadataAddress;
	this.issuerName = issuerName;
	this.mode = mode;
	if (!lazyLoad)
	{
	LoadMetadata();
	}
	}
	public override string GetIssuerName(SecurityToken securityToken)
	{
	if (_registry == null)
	{
	lock (_registryLock)
	{
	if (_registry == null)
	{
	LoadMetadata();
	}
	}
	}
	return _registry.GetIssuerName(securityToken);
	}
	protected virtual Stream GetMetadataStream()
	{
	var client = new HttpClient { BaseAddress = metadataAddress };
	return client.GetStreamAsync("").Result;
	}
	protected async virtual Task<Stream> GetMetadataStreamAsync()
	{
	var client = new HttpClient { BaseAddress = metadataAddress };
	return await client.GetStreamAsync("");
	}
	protected virtual void LoadMetadata()
	{
	using (var stream = GetMetadataStream())
	{
	var serializer = new MetadataSerializer();
	serializer.CertificateValidationMode = mode;
	var md = serializer.ReadMetadata(stream);
	var ed = md as EntityDescriptor;
	var stsd = (SecurityTokenServiceDescriptor)ed.RoleDescriptors.FirstOrDefault(x => x is SecurityTokenServiceDescriptor);
	var registry = new ConfigurationBasedIssuerNameRegistry();
	foreach (var key in stsd.Keys)
	{
	var clause = key.KeyInfo.FirstOrDefault() as X509RawDataKeyIdentifierClause;
	if (clause != null)
	{
	var cert = new X509Certificate2(clause.GetX509RawData());
	registry.AddTrustedIssuer(cert.Thumbprint, issuerName);
	}
	}
	_registry = registry;
	}
	}
	public override void LoadCustomConfiguration(XmlNodeList nodeList)
	{
	if (nodeList == null || nodeList.Count == 0)
	{
	throw new ConfigurationErrorsException("No configuration provided.");
	}
	var node = nodeList.Cast<XmlNode>().FirstOrDefault(x => x.LocalName == "trustedIssuerMetadata");
	if (node == null)
	{
	throw new ConfigurationErrorsException("Expected 'trustedIssuerMetadata' element.");
	}
	var elem = node as XmlElement;
	var name = elem.Attributes["issuerName"];
	if (name == null || String.IsNullOrWhiteSpace(name.Value))
	{
	throw new ConfigurationErrorsException("Expected 'issuerName' attribute.");
	}
	var address = elem.Attributes["metadataAddress"];
	if (address == null || String.IsNullOrWhiteSpace(address.Value))
	{
	throw new ConfigurationErrorsException("Expected 'metadataAddress' attribute.");
	}
	this.metadataAddress = new Uri(address.Value);
	this.issuerName = name.Value;
	}
	}
	}

view raw MetadataBasedIssuerNameRegistry.cs hosted with ❤ by GitHub

More information

Obtain and configure token signing and token decryption certificates for AD FS | Microsoft Learn

Dynamic issuer name registry direct from STS federation metadata with Thinktecture IdentityModel | brockallen