Partager via

ADFS Certificates - SSL, Token Signing, and Client Authentication Certs

  • Article

 

We are seeing quite a few support calls relating to certificate problems. Many of these are due to a misunderstanding of how the various certificates are used.

ADFS/PKI issues are often very difficult to diagnose for the following reason – a lack of logging telling you what the problem is.

For example – if the SSL certificate on your Web Server is incorrect or has a problem like missing a private key. The user experience will be a page can’t be displayed error and absolutely nothing will be logged in the event viewer, security log, or adfs debug logs.

There are several variations of this – but if you aren’t getting *anything* in the logs – start looking at your certificates! More times than not – it is the SSL certificate and you aren’t even getting to ADFS which is why there aren’t any error messages to work with.

Other sub-items that come to mind on this topic are:

1. Using Certutil to verify the certificates in question

2. What type of certificate should I use? 3rd Party, an internal CA, or a combination of the two.

In addition to this blog, you should also review the TechNet documentation on Understanding Certificates starting here. Between the two, I hope it makes it clear what goes where.

Also, it may be helpful to revisit my blog on the PKI portion of setting up a lab.  That is located here.

ADFS Certificates for Federation Servers

SSL Certificate

The SSL certificates must be trusted by the client machine which accesses the web sites. Since the client machine (in a Federated WebSSO scenario) will visit the WS, then the FS-R, then the FS-A, the client must trust all three SSL certificates. For this reason, it may make sense to use a 3rd party certificate for the SSL certificate.

A SSL certificate is in place to encrypt the session between client and the server. These certificates are not specific to ADFS, but rather specific to IIS.

The Subject Name of the SSL certificate must match the names used in the ADFS configuration. For example, if you specify a federation server endpoint URL as https://adfsresource.treyresearch.net/adfs/ls/ - then the subject name on the SSL certificate for that server must be “adfsresource.treyresearch.net” This is a very important item and a common misconfiguration. The name can be anything – it just needs to match. If you choose to setup ADFS for use on the intranet only and you want to use only the host name, then the endpoint URL would be https://adfsresource/adfs/ls/ and the Subject Name on the certificate should be “adfsresource”

The same Subject Name rules also apply to the web sites protected by ADFS. The name on the certificate should match the name clients will use to access the ADFS protected web site.

Token Signing Certificate

On the Federation Servers – you also need a token signing certificate. This certificate can be any X.509 certificate, the intended purpose or EKU doesn’t matter. The “issued to” name doesn’t matter. Any X.509 certificate will do. When you install the Federation Server role – setup will prompt you to pick a token signing certificate OR let setup create a self signed certificate for you.

Self Signed Certificates are OK for a lab – but should not be used in production deployments.

If you choose to select a token signing certificate in the setup portion, you will be presented with a list of all certificates present in the local machine personal certificate store. Whichever option you choose, the setup program will place an export of the token signing certificate in the list of verification certificates for the same machine. A verification certificate is simply an export (less the private key) of the token signing certificate. Each Federation Server must have a verification certificate for its own token signing certificate. If you change the token signing certificate later – the adfs.msc program will display a message telling you that the new verification certificate will be added to the list of verification certificates.

It seems a little strange that a Federation Server needs to verify its own token signing certificate, but that is the way it works…

A token signing certificate is used to “sign the ADFS authentication token” - this is the token that contains a users claims and is used to make authorization decisions at the website. The verification token is used to “verify” the token was sent by the federated partner and that it has not been tampered with.

In a Federated WebSSO scenario where you have an Account Partner and a Resource Partner, the Account Partner’s verification certificate must be present on the Resource Partners trust policy file. This certificate (by default) must be trusted, must be able to chain to the root, and must be able to access the certificate revocation list.

IMPORTANT NOTE:

Using the SSL certificate for the token signing certificate will work – but this should not be the configuration you use in production. This is considered bad key hygiene. The SSL certificate for the web site serves one purpose – the token signing certificate serves an entirely different purpose. This is the most misunderstood item we see.

Here is a screenshot from my Federation Server – notice how the SSL certificate is “issued to” adfsresource.treyresearch.net and the Token Signing certificate I use has a friendly name in the Issued To

ADFS Certificates for Federation Server Proxies

SSL Certificate

As with the other Federation Server roles, the FS-P web site will need a SSL certificate. The Subject Name must match the Federation Server endpoint URL specified on the Federation Server. If you have your endpoint URL as https://adfsresource.treyresearch.net/adfs/ls/ - the SSL certificate for the federation server itself should have a Subject Name of adfsresource.treyresearch.net and the Federation Server Proxy SSL certificate should also have a Subject Name of adfsresource.treyresearch.net. Even if the machine name is adfsproxy.treyresearch.net – the URL the client will hit is adfsresource.treyresearch.net. Whether or not the client is redirected to the IP address of adfsresource or adfsproxy depends on how the client resolves that name via DNS.

A typical name resolution setup for a Proxy scenario would be to have client machines on the internal LAN resolve adfsresource to the actual IP address of adfsresource.

Client machines on the internet (or outside of your internal LAN) resolve the name adfsresource.treyresearch.net to the IP address of adfsproxy.treyresearch.net. It is important to remember that you won’t specify the name adfsproxy.treyresearch.net anywhere in your setup. The website on this server should have a certificate issued to the name adfsresource.treyresearch.net.

The adfsproxy.treresearch.net server should be configured to resolve the name adfsresource.treyresearch.net to the actual IP address of adfsresource.treyresearch.net (this machine should be the only server in the DMZ/Internet) that knows adfsresource by its real IP. This is commonly accomplished by using a host file on adfsproxy.

With the scenario setup like this – the internal LAN clients will enjoy a single sign on experience when visiting an ADFS resource (not be prompted for credentials). Users external to the LAN will be presented with a forms based authentication page asking for username/password.

This is typically a desired configuration because the internet user probably hasn’t authenticated with his or her home domain.

Client Authentication Certificate

I like to explain the client authenticate certificate as “It is sort of like the token signing certificate, but for ADFS proxy servers” – while this isn’t really the case, it is a different certificate than what is used for SSL on the website. This certificate must have “client authentication” as an intended purpose. When you install the Federation Proxy component, when you choose your client authentication certificate, you will be presented with a list of certificates that have an EKU of “Client Authentication.” If you don’t have any in the local machine personal store, the list will be empty.

The client authentication certificate and its private key reside on the ADFS Proxy Server, but a copy of this certificate with only the public key resides on the Federation Server. This is why I try to explain it as “think of it like the proxies TS certificate” - it is different in many ways. Most importantly, it isn’t used to sign any tokens. But again – this is a completely different certificate than the one used for SSL on the server.

Comments

  • Anonymous
    January 01, 2003
    I'm running into a situation where the CRL url on our ADFS cert occasionally goes down, taking out all authentication requests to sharepoint. The system in question is using tumbleweed as a CAPI. Is there a way to disable active certificate validation for ADFS?

  • Anonymous
    January 01, 2003
    Our clients are having issues requesting these "Client Authentication" certificates, specifically from Verisign.  Are there other names that could be used to request it?  Is it simply requesting an SSL Cert with "client authentication" as the EKU?

  • Anonymous
    January 01, 2003
    The comment has been removed

  • Anonymous
    August 20, 2007
    I'm trying to create a certificate request for a 3rd-party CA.  Using certreq.exe, I'm having trouble creating a template to work. Any suggestions?

  • Anonymous
    October 26, 2010
    I am implenting ADFS 1.0 on windows 2003 having F5 load balancer setup. The load balancer receives port SSL requests and does a offloading to port 81 from SSL when it hits the servers. ADFS picks up this port and appends it in return url which breaks the system. Any suggestions on how to fix?

  • Anonymous
    November 29, 2013
    I am implementing SSO with ADFS Server and Service provider (different application server on linux). How many SSL certificates do I need? two certficates for adfs and application server are needed or one ssl is enough?

  • Anonymous
    July 03, 2014
    HI,
    Can i use *.domain.com wild cart cert?

    As

  • Anonymous
    August 05, 2014
    "We are seeing quite a few support calls relating to certificate problems. Many of these are due to a misunderstanding of how the various certificates are used." Duh. When Microsoft explains it, you might as well just try understanding hieroglyphics.

  • Anonymous
    January 25, 2015
    It would be really helpful to have an updated version of this article that 1) addresses Win 2012 R2 and 2) doesn't throw around jargon like FS-R, FS-A, and EKU without bothering to explain anything. As is, this article leaves more questions than it answers.

  • Anonymous
    June 04, 2015
    Configuring WAP with Certificate Based Authentication.
    This is a Walk through article on configuring

  • Anonymous
    August 25, 2015
    re: "What type of certificate should I use? 3rd Party, an internal CA, or a combination of the two."

    For production scenarios, where would you recommend anything other than using 3rd party certificates?

  • Anonymous
    January 19, 2016
    I am implementing SSO with ADFS Server and Service provider (different application server on linux). How many SSL certificates do I need? two certficates for adfs and application server are needed or one ssl is enough?