Cody Bunch Some Random IT Guy - OpenStack, DevOps, Cloud, Things

Building ADFS with PowerShell

09 May 2018

I have had a need recently to have a number of OpenSource projects authenticate against Microsoft Active Directory. While there are many ways to do this, ADFS, or Active Directory Federation Services allows us to use SAML, which in turn can be tied into 3rd party Single Sign On tools (Okta, Facebook, etc.)

Getting started

In order to use this script, you will need:

  • A Windows server, either 2012R2 or 2016
  • Active Directory
    • Schema level of at least 2012R2
  • User account with Domain Admin permission
  • PowerShell 5.x
    • Older versions may work, but are untested

Installing ADFS with PowerShell

To install ADFS with powershell, log into the Windows server where ADFS is to be deployed, and:

  1. Open PowerShell
  2. Download the script (Full script also included below)
  3. Review & run the script

How it works

Now that you’ve installed ADFS, let’s examine what we actually ran.

The script first installs NuGet. This is used to install 3rd party modules.

Get-PackageProvider -Name NuGet -ForceBootstrap
Install-PackageProvider nuget -Force

Next, the PSPKI module is installed and loaded into the current shell. We use this module to create the self-signed SSL certificate needed to install ADFS:

Install-Module -Name PSPKI -Force
Import-Module -Name PSPKI

With the PSPKI module loaded, we can now create a self-signed SSL certificate, and install it into the Windows certificate store:

Note: Replace $fqdn with the FQDN for the ADFS host.

$selfSignedCert = New-SelfSignedCertificateEx -Subject "CN=$fqdn" `
    -ProviderName "Microsoft Enhanced RSA and AES Cryptographic Provider" `
    -KeyLength 2048 -FriendlyName 'OAFED SelfSigned' `
    -SignatureAlgorithm sha256 `
    -EKU "Server Authentication", "Client authentication" `
    -KeyUsage "KeyEncipherment, DigitalSignature" -Exportable `
    -StoreLocation "LocalMachine"

$certThumbprint = $selfSignedCert.Thumbprint

When creating the SSL certificate, we stored the thumbprint for the certificate in a variable so we can use it again when configuring ADFS.

The next several commands are responsible for installing and configuring the ADFS role:

$user  = "$env:USERDOMAIN\$env:USERNAME"
$credential = New-Object `
    -TypeName System.Management.Automation.PSCredential `
    -ArgumentList $user, $securePassword

Install-WindowsFeature -IncludeManagementTools -Name ADFS-Federation

Import-Module ADFS
Install-AdfsFarm -CertificateThumbprint $certThumbprint `
    -FederationServiceName $fqdn `
    -ServiceAccountCredential $credential

This final bit of the script grabs the username of the current user, and then creates a credential object for the service account that ADFS will use.

Next it installs the ADFS feature Install-WindowsFeature.

The final bit imports the ADFS PowerShell module and configures ADFS to:

  • Use the SSL certificate created earlier
  • Assign a service name. (All the ADFS URLs use this)
  • Assign the service account

Test it out

You can validate that the ADFS role was installed and is running by browsing to https://<FQDN OF HOST>/adfs/fs/federationserverservice.asmx after the certificate warning you should get a bunch of XML.

You can also validate ADFS with the following PowerShell commands:

Install-Module ADFSDiagnostics -Force
Import-Module ADFSDiagnostics -Force

Test-AdfsServerHealth | ft Name,Result -AutoSize

If ADFS is working, you’ll see something like this:

ADFS is working

There is more!

The script provided creates a self-signed SSL certificate. While that will get you up and running in the lab, is not how you should deploy this in production. If you have a different certificate, say from an internal CA, or otherwise trusted CA, you can use it with this script. First ensure it is part of your Windows certificate store, then substitute your certificate’s thumbprint in the following line and continue to use the script:

$certThumbprint = "Your SSL Cert Thumbprint here"

Summary

In this post we used PowerShell to install, configure, and validate Active Directory Federation Services (ADFS). This in turn enables you to use Active Directory as an identity provider with all manner of 3rd party SSO tools.

Resources

Related Posts