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:
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:
More information
Obtain and configure token signing and token decryption certificates for AD FS | Microsoft Learn