Create a test Active Directory Federation Services 3.0 Instance on an Azure Virtual Machine

Greenhouse works with several Single Sign On providers, including Active Directory Federation Services (ADFS). This article documents how to set up a testing (non-production) ADFS 3.0 instance on an Azure Virtual Machine.

While writing the documentation for configuring ADFS with Greenhouse*, we first needed to create test instances of ADFS and Active Directory (the application that stores the user data accessed by ADFS). We found that while there are several articles online addressing the topic, it was difficult to piece that information together into a cohesive set of instructions. This article outlines every step of our process, from creating an Azure Virtual Machine to configuring a running instance of ADFS 3.0. It’s important to note that this documentation is intended for creating a test instance of ADFS and the process may differ for setting up a production instance.

• you must be a Greenhouse user to access the above link

This article will cover:

• How to create and access a Windows Server 2012 R2 Virtual Machine (Steps 1–2)
• How to configure an Active Directory Domain Services instance and add a user to it (Steps 3–5)
• How to create an Azure Network Security Group, which will allow network traffic to reach your Virtual Machine (Step 6)
• How to create a Fully Qualified Domain Name for your Virtual Machine (Step 7)
• How to create and export a Self-Signed SSL Certificate (Steps 8–9)
• How to configure an Active Directory Federation Services 3.0 instance (Steps 10–11)
• How to find the IdP endpoints associated with your ADFS instance (Step 12)
• How to find the event logs associated with your ADFS instance (Event Logs)

Index:

• Step 1: Create a Windows 2012 R2 Virtual Machine
• Step 2: Connect to the Virtual Machine
• Step 3: Install Active Directory Domain Services
• Step 4: Configure Active Directory Domain Services
• Step 5: Add a User to Active Directory Domain Services
• Step 6: Add a Security Rule to an Azure Network Security Group
• Step 7: Create a Fully Qualified Domain Name
• Step 8: Create a Self-Signed SSL Certificate
• Step 9: Export a Self-Signed SSL Certificate
• Step 10: Install Active Directory Federation Services
• Step 11: Configure Active Directory Federation Services
• Step 12: Find ADFS Endpoints: SSO, SLO, Metadata
• Event Logs

Before you begin, you’ll need to have an Azure account. Create an Azure account here.

Step 1: Create a Windows 2012 R2 Virtual Machine

First, you’ll need to set up a Windows 2012 R2 Virtual Machine.

1. Navigate to your Azure Portal

2. Click the Browse button on the navigation bar on the left-hand side of the Azure Portal

3. Search for “virtual machines”

4. Click “+ Add”

5. Search for “Windows 2012 R2 Datacenter”

6. Select “Resource Manager” as your deployment model, then click Create

7. On the “Basics” tab, add a server name, username, password, and select your subscription type. Under “Resource group,” click Create new and give the Resource Group a name. Set your Location, then click OK.

8. On the “Size” tab, select the appropriate machine size. We’ll use a DS1_V2 size for this example.

9. On the “Settings” tab, click OK.

10. On the “Summary” tab, click OK.

Step 2: Connect to the Virtual Machine

Now that the Virtual Machine is running, you’ll need to connect to it and log in.

1. Navigate to your Virtual Machine page in the Azure Portal.

2. To connect to the Virtual Machine, click Connect.

3. This will download a .rdp file to your computer. Click the downloaded file to access the Virtual Machine.

If you’re using a Mac, you’ll need a tool to open that file. Download Microsoft Remote Desktop from the Apple store.

4. You’ll be prompted to enter the machine’s Username and Password. Microsoft Remote Desktop also allows users to save their credentials so that you’ll only need to enter them once.

To save your credentials, click Edit on the Microsoft Remote Desktop window

In the “General” tab, enter a Connection Name and the machine’s Username and Password. You can also configure other settings, including setting the machine to open in full screen, scale content, or open on multiple monitors.

Once you’ve configured these settings, you’ll automatically be logged into the machine whenever you click on the .rdp file from Azure.

Step 3: Install Active Directory Domain Services

Active Directory Domain Services, or ADDS, will be the data store for your users. In this section, you’ll add ADDS to your Virtual Machine.

1. Open the Server Manager in your Virtual Machine. On the “Dashboard” tab, select “Add Roles and Features.” This will open the “Add Roles and Features” Wizard.

2. The first page is an overview of the Wizard. If you’d like, check the box next to “Skip this page by default” to prevent the prompt from appearing again.

3. On the “Installation Type” tab, select “Role-based or feature-based installation.”

4. On the “Server Selection” tab, choose “Select a server from the server pool.” Then, select the “Microsoft Windows Server 2012 R2 Datacenter” that you created when you set up the Virtual Machine.

5. On the “Server roles” tab, select “Active Directory Domain Services.” This will open another window. Click Add Features in the pop-up window, then click Next in the main window.

6. On the “Features” tab, leave the defaults and click Next.

7. On the “AD DS” tab, click Next.

8. On the “Confirmation” tab, click Install.

9. This may take a few minutes to install. You’ll be able to see the status of the installation on the “Results” tab.

Step 4: Configure Active Directory Domain Services

After installing ADDS, you’ll need to configure it to be your Domain Controller, or the server that responds to authentication requests from ADFS.

1. After installing ADDS, you’ll see a notification icon at the top of your Server Manager window. Click the icon to make a drop-down menu appear. Then, click “Promote this server to be a domain controller.” This will open the “Active Directory Domain Services Configuration” Wizard.

2. On the “Deployment Configuration” page, select “Add a new forest” and give it a domain name.

3. On the “Domain Controller Options” page, leave the default configurations. Then, create a password for Directory Services Restore Mode. This will provide you with a fallback to ADDS if you need to recover the server in the future.

4. A window will pop up with an error message. This is expected — Click OK, then click Next.

5. On the “Additional Options” page, click Next.

6. On the “Paths” page, click Next.

7. On the “Review Options” page, click Next. You can also click the “View script” button to view the PowerShell script for these settings.

8. On the “Prerequisites Check” page, you may see warning messages in the “View Results” window. This is expected — Click Install.

9. Your Virtual Machine will restart to complete the installation.

Step 5: Add a User to Active Directory Domain Services

You’re now ready to add users to your ADDS instance. Each user will need to have a name and an email address before they can log into an app through ADFS.

1. Navigate to the Server Manager tool. Then, click Tools in the navigation bar and select “Active Directory Users and Computers” from the drop-down menu. This will open a new window.

2. In the new window, expand the local host folder (in this example case, the folder is called “greenhouse.local”). Then, open the “Users” folder.

3. Right-click on the “Users” folder and select “New,” then select “User.” This will open the “New Object — User” window.

4. In the new window, enter the user’s name information, then click Next.

5. On the new page, enter a password for the user, and choose the settings you’d like to apply to the user’s password.

6. On the last page, click Finish.

7. The user will now appear in the list of Active Directory Users and Computers. To add the user’s email address, click on user’s name. This will open the “Properties” window for that user.

8. On the “General” tab, enter an email address for the user in the “E-mail” field. You can also use this window to add additional information about the user.

9. Click Apply, then click OK to close the window.

Step 6: Add a Security Rule to an Azure Network Security Group

Next, you’ll need to update the security rules for your Virtual Machine. This will be done on the Azure website, which you can access in a browser outside of your Virtual Machine.

1. Navigate to the Virtual Machine page in the Azure Portal. Then, click the value under “Virtual network/subnet.” This will open the “Virtual Network” section.

2. In the “Virtual Network” section, click on your Virtual Machine under “Connected devices.” This will open the “Network Interface” section.

3. In the “Network Interface” section, click “Network Security Group” under the “Settings” sidebar on the right side of the page.

4. In the “Network Security Group” section, select your Virtual Machine.

5. Select “Inbound Security Rules” under the “Settings” sidebar on the right side of the page.

6. On the “Inbound Security Rules” page, click “+ Add.”

7. In the “Add inbound security rule” sidebar, create a new rule named “allow-all.” Set the “Destination port range” to “ * ”. Leave all other settings as their defaults.

8. You’ll now see your new rule in the “Inbound security rules” section.

Step 7: Create a Fully Qualified Domain Name

You’ll now need to create the Fully Qualified Domain Name, or “FQDN,” that you’ll use with ADFS. The FQDN will be used to determine the ADFS endpoints found in Step 12.

1. Navigate to the Virtual Machine page in the Azure Portal. Then, click the value under “Public IP address/DNS name label.”

2. Click “Configuration” under the “Settings” sidebar on the right side of the page.

3. Add a subdomain to the “DNS name label (optional)” field. Leave the other settings as their defaults. This value will be your Fully Qualified Domain Name. In this example, the FQDN is “greenhouse.eastus.cloudapp.azure.com”

4. You’ll now see your FQDN in the “DNS name” section of your Virtual Machine’s “Public IP address” page.

Step 8: Create a Self-Signed SSL Certificate

To access your ADFS instance from the internet, you’ll need to create an SSL Certificate. For this example, we’ll create a self-signed certificate.

1. Download the Public Key Infrastructure Powershell Module from CodePlex onto your Virtual Machine.

2. Run the downloaded file. This will open the “Powershell PKI Module Setup” window.

3. Select the location for the file and check the box next to “Install for all users”

4. Select “Complete” to install both client and server configurations.

5. Click Install to complete the installation.

6. Open Powershell and call “Import-Module PSPKI”

7. Enter the details for your self-signed certificate into Powershell using the syntax outlined inthis guide.

Our example certificate will use the following details:

“New-SelfSignedCertificateEx -Subject ‘CN=greenhouse.eastus.cloudapp.azure.com’ -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”

Step 9: Export a Self-Signed SSL Certificate

Now that you’ve created the self-signed certificate, you’ll need to export it and add it to your ADFS instance.

1. Open the Microsoft Management Console. You can find it by searching for “MMC” on the Virtual Machine.

2. In the “Console 1 — [Console Root]” window, click File. Then, click “Add/Remove Snap-in…”

3. In the “Add/Remove Snap-ins” window, select “Certificates” in the menu on the left side of the screen. Then, click “Add >”

4. In the “Certificates snap-in” window, select “Computer account.”

5. In the “Select Computer” window, select “Local Computer.” Then, click Finish.

6. Back in the “Add or Remove Snap-ins” window, click OK.

7. Back in the “Console 1 — [Console Root]” window, you’ll now see a folder called “Certificates (Local Computer).”

8. Expand the “Certificates (Local Computer)” folder, then expand the “Personal” folder and click Certificates. You’ll see the certificate that you made using the Public Key Infrastructure Powershell Module.

9. Right-click and select “All Tasks,” then “Export…” This will open the “Certificate Export” Wizard.

10. In the “Certificate Export” Wizard, click Next.

11. Select “Yes, export the private key”

12. Choose “Personal Information Exchange — PKCS #12 (.PFX).” Select “Include all certificates in the certification path if possible” and “Export all extended properties.”

13. Select “Password” and enter a password for the private key.

14. Click Browse and choose your Documents folder. Name the file and save it in your Documents folder, then click Next.

15. Click Finish to complete the certificate export.

Step 10: Install Active Directory Federation Services

In this section, you’ll install ADFS.

1. Open the Server Manager in your Virtual Machine. On the “Dashboard” tab, click “Add Roles and Features”

2. On the “Installation Type” tab, select “Role-based or feature-based installation.”

3. On the “Server Selection” tab, select “Select a server from the server pool.” Then, choose your “Microsoft Windows Server 2012 R2 Datacenter” server.

4. On the “Server Roles” tab, select “Active Directory Federation Services.”

5. On the “Features” tab, click Next.

6. On the “AD FS” tab, click Next.

7. On the “Confirmation” tab, click Install.

8. This may take a few minutes to install. You’ll be able to see the status of the installation on the “Results” tab.

Step 11: Configure Active Directory Federation Services

Now that ADFS is running on your machine, you’ll need to connect it to your ADDS instance and upload your SSL certificate.

1. After installing ADFS, you’ll see a notification icon at the top of your Server Manager window. Click the icon to make a drop-down menu appear. Then, click “Configure the federation service on this server.” This will open the “Active Directory Federation Services Configuration” Wizard.

2. On the “Welcome” tab of the Wizard, select “Create the first federation server in a federation server farm.”

3. On the “Connect to AD DS” tab, your administrator account will be pre-selected. Click Next.

4. On the “Specify Service Properties” tab, click Import.

5. Browse to your Documents folder and select the certificate that you exported from the Microsoft Management Console in Step 9. You’ll also need to enter the password that you created when you exported the certificate.

6. You’ll now see the name of the certificate appear in the “SSL Certificate” and “Federation Service Name” fields. Enter a “Federation Service Display Name,” then click Next.

7. On the “Specify Service Account” tab, you may see the following error: “Group Managed Service Accounts are not available because the KDS Root Key has not been set…” Click “Show more” to see the full error message.

8. To resolve the error, open Powershell and run the command “Add-KdsRootKey -EffectiveTime (Get-Date).AddHours(-10)”

9. Back on the “Specify Service Account” tab, the error message will now be gone. Select “Create a Group Managed Service Account,” enter an Account Name, then click Next.

10. On the “Specify Database” tab, select “Create a database on this server using Windows Internal Database.” Then click Next.

11. On the “Review Options” tab, click Next.

12. On the “Pre-requisites Checks” tab, you may see a warning about the time that the root key for the Managed Service Account was created. This won’t be an issue if you have only one domain controller. Click Configure.

13. The server will now install. Once the installation is complete, you’ll be redirected to the “Results” tab. Click Close.

Step 12: Find ADFS Endpoints: SSO, SLO, Metadata

All ADFS endpoints will include your Fully Qualified Domain Name followed by a URL path. Remember that the FQDN was set in the Azure Portal in Step 7. In our example case, the FQDN is “greenhouse.eastus.cloudapp.azure.com.”

1. To see all of the available endpoints for your ADFS instance, open the ADFS management tool by clicking Tools in the navigation bar of the Server Manager window. This will open the “AD FS” window.

2. In the new window, expand the “Service” folder and click Endpoints. This will open the list of endpoints for your ADFS instance.

3. You’ll find your Single Sign On URL path in the “Token Issuance” section of the Endpoints window. This value will be “/adfs/ls”, which you can append to the end of your FQDN to construct your Single Sign On URL. In this example case, the full Single Sign On URL will be “greenhouse.eastus.cloudapp.azure.com/adfs/ls/”

4. You’ll find your Metadata URL path In the Metadata section. This value will be “/FederationMetadata/2007–06/FederationMetadata.xml”, which you can append to the end of your FQDN to generate your Metadata URL. In the example case, the full URL will be “greenhouse.eastus.cloudapp.azure.com/FederationMetadata/2007–06/FederationMetadata.xml”

5. The Single Log Out URL won’t be included in the “Endpoints” section, but the URL path will be “/adfs/ls/?wa=wsignout1.0”, which you can append to the end of the FQDN to create your Single Log Out URL. In this example case, the full URL will be “greenhouse.eastus.cloudapp.azure.com/adfs/ls/?wa=wsignout1.0”

Event Logs

If you run into any errors when using your ADFS instance, you can check the Event Viewer in your Virtual Machine to see the details of the error.

1. You can find your server logs by searching for “Event Viewer” in your Virtual Machine. This will open the Event Viewer window.

2. To see ADFS-specific errors, expand the “Applications and Services Log” folder on the left side of the window. Then, expand the “AD FS” folder and click Admin.

3. In this window, you’ll be able to select each event and view the details of it using the “General” and “Details” tabs. Click Refresh on the right side of the window to see the latest events logged for your ADFS instance.

Congratulations! You now have ADFS 3.0 set up and running on Windows Server 2012 R2. To learn how to connect your ADFS instance to Greenhouse, please see this FAQ article.

Rachel Leffel is a Solution Engineer on the Product Engineering team.

Come work with us. We’re hiring!