ADFS 2.0 Client Certificate Authentication using test certificates

Introduction

I was developing a WCF based solution that required services to be authenticated using ADFS 2.0. The requirement was that the clients will be using client based certificates to authenticate to services. If you have a complete AD CS solution implemented that wouldn’t have been that difficult since the platform already takes care of most of the stuff already mentioned here but I wanted to test this scenario with my own testing certificates that are generated using command line tool “makecert.exe” and not a CA.

The Solution

The steps that you need to follow are:

· Step 1: Create a claims aware WCF service using WIF.

· Step 2: Add ADFS as an STS to the WCF service.

· Step 3: Add this as a relying party in ADFS using the generated metadata.

· Step 4: Build a client application and add a service reference.

· Step 5: Change the issuer address to make sure it is using the ADFS certificate endpoint.

· Step 6: Create a Certificate to Act as Your Client Root Certificate Authority.

· Step 7: Create a Certificate Revocation List File from the Root Certificate.

· Step 8: Install Your Client Root Certificate Authority on the Client and Server Machines

· Step 9: Install the Certificate Revocation List File on the Server and Client Machines

· Step 10: Add the Client Root Certificate Authority to the NTAuth store

· Step 11: Create and Install Your Temporary Client Certificate

· Step 12: Configure Active Directory Mapping.

So let’s get into the detail shall we.

I am not going over the first four steps since you can find more details on how to perform them in many places such as here or here. So I will start explaining starting of step 5.

Step 5: Change the issuer address to make sure it is using the ADFS certificate endpoint

ADFS 2.0 supports multiple methods to issue tokens, these are called endpoints. As you can see in the below image it supports many and you can even enable or disable them as required.

So we need to make sure that the Certificate Mixed endpoint is first enabled in ADFS. Now if you did not add an issuer address to your WCF service or added any endpoint address other than the certificate mixed one you need to change that in your client configuration. You can simply do this by opening the app.config file and look within the imported service binding for the issuer or the issuermetadata tag. It should eventually be configured similar to the below.

Step 6: Create a Certificate to Act as Your Client Root Certificate Authority

In this step, you use the makecert tool to create a root CA that will be used to sign your certificate. This certificate will be self-signed and will only have the public key that will be used to perform chain trust validation, when authenticating clients with the certificate. The self-signed certificate will act as a root CA itself, instead of pointing to a Root authority in a chain of trust.

1. Open a Visual Studio command prompt and browse to the location where you want to save the certificate files.

2. Run the following command to create the root CA:

makecert -n "CN=RootCaClientTest" -r -sv RootCaClientTest.pvk RootCaClientTest.cer

In this command:

· -n specifies the subject name for the root CA. The convention is to prefix the subject name with "CN = " for "Common Name".

· -r specifies that the certificate will be self-signed. This means that certificates created with this switch will act as a root certificate.

· -sv specifies the file that will contain the private key of the certificate. The file is always created, if it does not already exist. This will allow creation of certificates using the private key file for signing and key generation.

· RootCaClientTest.cer specifies the name of the file containing the public key of the certificate. The RootCATes.cer file will not have the private key. This is the certificate that will be installed in the store for chain trust validation on the client and server machines.

3. In the Create Private Key Password dialog box, enter a password, confirm the password, and then click OK.

Optionally, you can click None without entering the password, but this is not recommended for security reasons.

4. In the Enter Private Key Password dialog box, enter the password again and then click OK.

This is the password needed to access the private key file RootCaClientTest.pvk in order to generate the file RootCaClientTest.cer containing the public key.

This step creates a certificate named RootCaClientTest.cer and a private key file named RootCaClientTest.pvk.

Step 7: Create a Certificate Revocation List File from the Root Certificate

In this step, you create a CRL file that will be imported into the correct certificate stores of the client and service machines. You create a CRL for the temporary root certificate; the CRL is necessary because WCF clients check for the CRL when validating certificates.

1. Open a Visual Studio command prompt and browse to the location where you want to save the CRL file for the root certificate.

2. Run the following command to create the CRL file:

makecert -crl -n "CN=RootCaClientTest" -r -sv RootCaClientTest.pvk RootCaClientTest.crl

In this command:

· -crl specifies that you want to generate the CRL file for the root certificate.

· -n specifies the subject name for the CRL. The convention is to prefix the subject name with "CN = " for "Common Name". You can give it the same name as the root CA.

· -r specifies that the CRL file will be self-signed. This means that CRL files created with this switch will act as CRL files for the root CA.

· -sv specifies the file that will contain the private key for CRL file generation. The file is not created because it already exists. This allows creation of CRL files using the private key file for signing.

· RootCaClientTest.crl is the CRL file created with the command.

Step 8: Install Your Client Root Certificate Authority on the Client and Server Machines

In this step, you install the client root CA in the Trusted Root Certification Authorities location on both the server and client machines. All certificates that are signed with this certificate will be trusted by the client machine.

Repeat the following steps on both the client and server machines:

1. Copy the RootCaClientTest.cer file to the client and server machines.
2. Click Start and then click Run.
3. In the command line, type MMC and then click OK.
4. In the Microsoft Management Console, on the File menu, click Add/Remove Snap-in.
5. In the Add Remove Snap-in dialog box, click Add.
6. In the Add Standalone Snap-in dialog box, select Certificates and then click Add.
7. In the Certificates snap-in dialog box, select the Computer account radio button (because the certificate needs to be made available to all users), and then click Next.
8. In the Select Computer dialog box, leave the default Local computer: (the computer this console is running on) selected and then click Finish.
9. In the Add Standalone Snap-in dialog box, click Close.
10. In the Add/Remove Snap-in dialog box, click OK.
11. In the left pane, expand the Certificates (Local Computer) node, and then expand the Trusted Root Certification Authorities folder.
12. Under Trusted Root Certification Authorities, right-click the Certificates subfolder, click All Tasks, and then click Import.
13. On the Certificate Import Wizard welcome screen, click Next.
14. On the File to Import screen, click Browse.
15. Browse to the location of the signed root CA RootCaClientTest.cer file copied in Step 1, select the file, and then click Open.
16. On the File to Import screen, click Next.
17. On the Certificate Store screen, accept the default choice and then click Next.
18. On the Completing the Certificate Import Wizard screen, click Finish.

The signed root CA certificate is now installed in the Trusted Root Certification Authorities store. You can expand the Certificates subfolder under Trusted Root Certification Authorities to see the RootCaClientTest certificate installed properly.

Step 9: Install the Certificate Revocation List File on the Server and Client Machines

In this step, you install the CRL from the file in the Trusted Root Certification Authorities location on both the server and client machines. The CRL is checked during the certificate validation process.

Repeat the following steps on both the client and server machines:

1. Copy the RootCaClientTest.crl file to the client and server machines.
2. Click Start and then click Run.
3. In the command line, type MMC and then click OK.
4. In the Microsoft Management Console, on the File menu, click Add/Remove Snap-in.
5. In the Add Remove Snap-in dialog box, click Add.
6. In the Add Standalone Snap-in dialog box, select Certificates and then click Add.
7. In the Certificates snap-in dialog box, select the Computer account radio button (because the certificate needs to be made available to all users), and then click Next.
8. In the Select Computer dialog box, leave the default Local computer: (the computer this console is running on) selected and then click Finish.
9. In the Add Standalone Snap-in dialog box, click Close.
10. In the Add/Remove Snap-in dialog box, click OK.
11. In the left pane, expand the Certificates (Local Computer) node, and then expand the Trusted Root Certification Authorities folder.
12. Under Trusted Root Certification Authorities, right-click the Certificates subfolder, select All Tasks, and then click Import.
13. On the Certificate Import Wizard welcome screen, click Next.
14. On the File to Import screen, click Browse.
15. On the Files of Type screen, select Certificate Revocation List.
16. Browse to the location of the signed root CA RootCaClientTest.crl file copied in Step 1, select the file, and then click Open.
17. On the File to Import screen, click Next.
18. On the Certificate Store screen, accept the default choice and then click Next.
19. On the Completing the Certificate Import Wizard screen, click Finish.

The CRL for the root CA certificate is now installed in the Trusted Root Certification Authorities store. You can click the Trusted Root Certification Authorities folder and then press F5 to display the subfolder named Certificate Revocation List. You can expand this folder to see the RootCaClientTest certificate revocation list installed properly.

Step 10: Add the Client Root Certificate Authority to the NTAuth store

This is a critical step for this procedure since the root certificate was not issued by an enterprise CA. if you issue the certificate by an enterprise CA then this is already done automatically during the configuration of the ADFS server.

1. Open a Visual Studio command prompt and browse to the location where the root CA certificate and private key file you created are stored.

2. Run the following command for adding the Client Root Certificate Authority to the NTAuth store:

certutil -enterprise -addstore NTAuth RootCaClientTest.cer

Step 11: Create and Install Your Temporary Client Certificate

In this step, you create the temporary certificate from the signed root CA created in the previous step and install it on the server machine.

3. Open a Visual Studio command prompt and browse to the location where the root CA certificate and private key file you created are stored.

4. Run the following command for creating a certificate signed by the root CA certificate:

makecert -sk MyKeyName -iv RootCaClientTest.pvk -n "CN=tempClientcert" -ic RootCaClientTest.cer -sr currentuser -ss my -sky signature –pe

In this command:

· -sk specifies the key container name for the certificate. This needs to be unique for each certificate you create.

· -iv specifies the private key file from which the temporary certificate will be created. You need to specify the root certificate private key file name that was created in the previous step and make sure that it is available in the current directory. This will be used for signing the certificate and for key generation.

· -n specifies the key subject name for the temporary certificate. The convention is to prefix the subject name with "CN = " for "Common Name".

· -ic specifies the file containing the root CA certificate file generated in the previous step.

· -sr specifies the store location where the certificate will be installed. The default location is currentuser. For certificate authentication, this is the default location that Microsoft Internet Explorer uses for when browsing Web sites that require a client certificate.

· -ss specifies the store name for the certificate. My is the personal store location of the certificate.

· -sky specifies the key type, which could be either signature or exchange. Using signature makes the certificate capable of signing and enables certificate authentication.

· -pe specifies that the private key is generated in the certificate and installed with it in the certificate store. When you double-click the certificate on the General tab, you should see the message “You have a private key that corresponds to this certificate” displayed at the bottom. This is a requirement for certificate authentication. If the certificate does not have the corresponding private key, it cannot be used for certificate authentication.

5. In the Enter Private Key Password dialog box, enter the password for the root CA private key file specified in Step 2, and then click OK.

Step 12: Configure Active Directory Mapping

1. To open Active Directory Users and Computers, click Start, click Control Panel, double-click Administrative Tools, and then double-click Active Directory Users and Computers.

2. To open Active Directory Users and Computers in Windows Server® 2012, click Start, type dsa.msc.

3. On the View menu, select Advanced Features.

4. In the console tree, click Users.

Where?

Active Directory Users and Computers/domain node/Users

Or, click the folder that contains the user account.

5. In the details pane, right-click the user to which you want to map a certificate, and then click Name Mappings.

6. In the Security Identity Mapping dialog box, on the X.509 Certificates tab, click Add.

7. Type the name and path of the .cer file that contains the certificate that you want to map to this user account, and then click Open.

8. Do one of the following:

To map the certificate to one account (one-to-one mapping), confirm that both the Use Issuer for alternate security identity check box and the Use Subject for alternate security identity check box are selected.

To map any certificate that has the same subject to the user account, regardless of the issuer of the certificate (many-to-one mapping), clear the Use Issuer for alternate security identity check box, and confirm that the Use Subject for alternate security identity check box is selected.

To map any certificate that has the same issuer to the user account, regardless of the subject of the certificate (many-to-one mapping), clear the Use Subject for alternate security identity check box, and confirm that the Use Issuer for alternate security identity check box is selected.

That’s basically what you need to do to authorize the user using a client certificate.

One final note, if you get an error such as below:

The X.509 certificate chain building failed. The certificate that was used has a trust chain that cannot be verified. Replace the certificate or change the certificateValidationMode. 'A certification chain processed correctly, but one of the CA certificates is not trusted by the policy provider.

This probably means that you forgot step number 10.