One Click

For this article on Active Directory Federation Services (ADFS) automation, I assume the work on Active Directory (AD) and DNS itself is complete and that the SQL Server is installed and available. The service account on the AD – in which context the service runs on each federation server – has no special permissions. However, it must be a member of the local Administrators group on each federation server. You can ensure this with a script or the following command at the prompt:

Net Localgroup administrators KBCORP\ADFSSrv /add

The NetBIOS name of the domain in the examples here is KBCORP , which you will see several times.

If you use multiple federated servers on your farm and want to populate the local administrator's group on the servers centrally and remotely, the Sysinternals PsExec.exe PSTools is a useful choice (Figure 1). In this age of PowerShell remoting and similar features, you have many ways to manage servers remotely, but few are as easy to handle as PSTools [1]. Without registering or installing anything on the target system or elsewhere, you can call PsExec.exe from any folder:

psexec \\adfs1 net localgroup administrators kbcorp\ADFSSrv /add

Figure 1: PSTools does the job without the need to install.

In this example, I use it to add the ADFSSrv account to the Administrators group on the federation server ADFS1.

Certificates: A Basis of Trust

The preparatory work includes making sure a service certificate, which represents the federation server, exists on all the federation servers; however, before you do this, you need to set up the federation service. Automating this process is extremely useful, because an incorrectly installed certificate can cause problems.

ADFS gives you some scope for the origin of the certificate: It can come from a certificate authority (CA) in your organization or be a public certificate that is valid outside of the corporate network. It is important to issue the certificate and then export it as a file to be able to import it automatically, and as often as you need, at the command line to other ADFS servers and Web Application Proxy (WAP) servers. A WAP server is a proxy for ADFS and a separate role that does not run on a federation server. Instead, the server is located in a DMZ, because this is the component in the ADFS environment that partly resides on the Internet. A WAP server can use the same server certificate as the ADFS server.

It is customary for enterprises to purchase a public certificate, especially if they communicate with external partners in their federated environment. However, a certificate from your own public key infrastructure (PKI) is sufficient for testing purposes. The web server template, which guarantees the authenticity of the server as a server certificate, acts as the certificate template in this case. To adapt it to your own needs, you first need to make a copy. After that, you can edit the properties you want to apply to certificates created on the basis of this template.

In this example, the federation server (and the WAP server) require a certificate with the option for exporting the private key (Figure 2). Everything else can remain unchanged in the template. Issuing certificates is essential and multifaceted in ADFS. Microsoft TechNet provides details [2]. By the way, you only need to take care of the service certificate. Although ADFS also requires the token decryption and token signing certificates, if you do not specify them during the setup, the routine simply creates self-signed certificates.

Figure 2: A copied web server template: It must be possible to export the private key.

At this point, I assume that the certificate exists as a .pfx file and the private key has been exported. On the federation server, type the following command to add the computer certificate on the server (Figure 3):

$secpwd=Read-Host -AsSecureString "Please enter password for PFX file"
$cert = Import-PfxCertificate -FilePath \
  c:\STSKBCorp.pfx cert:\localMachine\My -Password $secpwd -Exportable

Figure 3: The main cmdlets for creating a federation server farm.

The Read-Host cmdlet accepts the password as a secure string and stores it in the $secpwd variable. Import-PfxCertificate then sends the certificate to the repository for computer certificates or, to be more precise, in the logical repository for My Certificates . If you run the command as described, you might notice that it is not particularly chatty; in fact, it says nothing about the successful import.

However, you can rely on this working; Import-PfxCertificate would have output an error if it had found inconsistencies with one of the parameters or the certificate itself. To be on the safe side, check the variable content of $cert (e.g., with the $cert | fl * cmdlet) and make sure you have a valid cryptography object with corresponding properties. This also shows you the thumbprint of the certificate (ThumbPrint variable); you will need this to set up the federation service on the server.

In this example, the issuing CA is also the root CA, which is not usually the case, although technically quite possible. Always remember that all certificates of the certification authorities in the certification path must exist up to the root CA. This is the only way for the respective certificate to be valid. Remember to delete the .pfx files, which contain the private key and thus offer the potential for an attack.

Earlier, I showed how to import a certificate. The counterpart to this is the Export-PfxCertificate command. Whether this is the best way to create a PFX file depends on the situation. The fact is that on a server you usually have multiple computer certificates, and the export cmdlet needs to know which certificate you want to export. You could handle this, for example, by working with the fingerprint again. However, it might be easier to export the certificate using the Certificates MMC snap-in, while remembering to set the focus to computer certificates, not user certificates.

Installing a New Farm

When installing an ADFS farm, a distinction is made between the first server and the remaining servers in the farm. In both cases, always add the ADFS Windows feature first and then configure it. An important parameter here is CertificateThumbprint. In this example, I ran the certificate import steps and ADFS configuration directly, one after the other, so that the fingerprint from the $cert object variable could be read. If the two actions take place separately, you have to read the thumbprint from the properties of the certificate, copy it via the clipboard to Notepad to remove the spaces, and then add the string as a cmdlet parameter. The command is shown in Listing 1.

Install-AdfsFarm -CertificateThumbprint "40f4e41b8174d73b06f34fd86f2432c09a63dc03"
  -FederationServiceDisplayName "KBCorp Federation" -FederationServiceName "sts.kbcorp.de"
  -OverwriteConfiguration:$true -ServiceAccountCredential $ADFSSrvCredentials

Take care to use the correct thumbprint; otherwise, the work step fails at this point. The other parameters are largely self-explanatory. What is important in this context is that you run the cmdlet as a domain administrator. If the local administrator and domain administrator roles are separate in your company, you could use the -Credential parameter. This lets you specify a different account; otherwise, the install uses the context of the logged-in admin. The whole spectrum of the cmdlets for commissioning an ADFS farm is described on Microsoft TechNet [3].

Adding New Federation Servers to the Farm

The process is similar for other servers that you add to the farm. They also need the certificate you just used, and you also need to install the adfs-federation feature for these servers. Afterward, you can continue with the Add-AdfsFarmNode cmdlet, which you use to add the server to an existing farm. To keep the example simple, the first server is ADFS1 and you then add a server named ADFS2 . The command is shown in Listing 2.

Add-AdfsFarmNode -PrimaryComputerName "ADFS2"
  -CertificateThumbprint $cert.ThumbPrint -ServiceAccountCredential $ADFSSrvCredentials

This cmdlet also lets you to use the -Credential parameter to change to the context of a domain administrator. For an overview with further examples, see TechNet [4]. Calling the logon page tests whether the federation service has been added correctly on a server. The commands

$ie = New-Object -ComObject InternetExplorer.Application
$ie.Navigate2("https://sts.kbcorp.de/adfs/ls/IdpInitiatedSignon.aspx")
$ie.Visible = $true

can be used to automate this process.