Guide: Integrating Active Directory Federation Services (AD FS) as an OIDC Provider¶

This document provides a comprehensive, step-by-step guide for administrators to configure an on-premises Active Directory Federation Services (AD FS) server as an OpenID Connect (OIDC) identity provider. The goal is to enable users from your Active Directory to securely authenticate with our platform to access their VDI sessions and other cloud resources.

This guide is designed to be followed sequentially and covers everything from initial server setup to final production-ready configuration.

Table of Contents¶

Introduction & Prerequisites
Glossary of Terms & Tools
Part 1: Building the Foundation: Active Directory
Part 2: Setting Up the Identity Provider: AD FS
Part 3: Connecting Your Platform to AD FS (Application Group)
Part 4: Making AD FS Production-Ready
Part 5: Finalizing the OIDC Configuration for Claims
Part 6: Your Platform's Configuration
Troubleshooting Common Issues
System Maintenance & Lifecycle Management
Security Best Practices
Conclusion

1. Introduction & Prerequisites¶

Goal¶

The objective is to allow your Active Directory users to sign in to our platform using their existing corporate credentials. We will achieve this by configuring your AD FS server to act as a trusted identity provider using the modern OIDC standard. This enables Single Sign-On (SSO) and allows for Just-in-Time (JIT) user provisioning based on group membership.

Prerequisites¶

Before you begin, ensure you have the following: * A Windows Server VM with a static private IP address, designated to be your Domain Controller (DC). * A second Windows Server VM with a static private IP, designated for your AD FS installation. * Administrator credentials for both servers. * A public-facing static IP address on your cloudspace firewall that can be routed to the AD FS server. * A public DNS name (e.g., sso.yourcompany.com) that you can point to the public IP. * A valid public SSL certificate for your chosen DNS name (we will cover creating a temporary one for setup).

2. Glossary of Terms & Tools¶

Understanding these components is key to a successful setup.

Key Terms¶

Active Directory Domain Services (AD DS): The core of a Windows network. It's the database that stores all user accounts, passwords, computers, and security groups. This is your "single source of truth."
Domain Controller (DC): A server running the AD DS role. It is the "brain" of your domain.
Active Directory Federation Services (AD FS): A Windows Server role that acts as a bridge between your internal Active Directory and external applications. It handles the secure authentication process using standards like OIDC.
OpenID Connect (OIDC): A modern authentication protocol built on top of OAuth 2.0. It allows applications to verify a user's identity and obtain basic profile information.
Claim: A piece of information about a user (e.g., their email address, name, or group memberships) that is packaged inside a security token.

Administrative Tools¶

Server Manager: The main dashboard on Windows Server for installing roles and features.
- How to Open: Automatically starts on login, or run servermanager.exe.
Active Directory Users and Computers: The tool used to create and manage users, groups, and Organizational Units (OUs).
- How to Open: After installing AD DS, run dsa.msc.
AD FS Management: The tool used to configure AD FS, including connecting applications.
- How to Open: After installing AD FS, run adfsmgmt.msc.
Windows PowerShell (Admin): A powerful command-line interface essential for advanced configuration and troubleshooting.
- How to Open: Start Menu -> Type "PowerShell" -> Right-click -> "Run as administrator".

3. Part 1: Building the Foundation: Active Directory¶

In this section, we will configure your first server to be a Domain Controller.

Step 1: Install Active Directory Domain Services (AD DS)¶

Log into your designated Domain Controller VM.
Open Server Manager.
Click Manage -> Add Roles and Features.
Proceed through the wizard until you reach the Server Roles screen.
Select Active Directory Domain Services. Accept the prompt to add required features.
Continue and click Install.

Step 2: Promote the Server to a Domain Controller¶

After the installation, a notification flag will appear in Server Manager. Click it and select "Promote this server to a domain controller".
In the wizard, select "Add a new forest".
Enter a Root domain name. For internal use, something like yourcompany.internal is standard.
On the next screen, set a Directory Services Restore Mode (DSRM) password. Store this safely.
Proceed through the next steps, accepting the defaults.
Prerequisite Check: If you encounter an error about the local Administrator password being blank, you must set it first. Cancel the wizard, set a strong password for the local Administrator account (lusrmgr.msc), and then restart this promotion process.
Click Install. The server will configure itself and restart automatically.

Step 3: Create an Organizational Unit (OU)¶

An OU helps keep your VDI-related users and groups organized. 1. After the server reboots, log in as the domain administrator (e.g., YOURCOMPANY\Administrator). 2. Open Active Directory Users and Computers (dsa.msc). 3. Right-click your domain in the left pane -> New -> Organizational Unit. 4. Name it VDI_Environment and click OK.

Step 4: Create Users and Groups¶

Right-click your new VDI_Environment OU and select New -> Group.
- Group Name: VDI_Users (This group will contain all users entitled to a VDI session).
- Leave defaults and click OK.
Right-click the VDI_Environment OU and select New -> User.
- Create a test user (e.g., username test.vdi).
- Set a password and uncheck "User must change password at next logon" for easier testing.
Important for Verification: Double-click the new user, go to the General tab, and enter a real, valid email address in the E-mail field. Our platform uses this for new user verification.
Double-click the VDI_Users group, go to the Members tab, and add your test user to this group.

4. Part 2: Setting Up the Identity Provider: AD FS¶

Now, we will configure your second server to be the AD FS server. This server must first be joined to the domain you created.

Step 1: Install the AD FS Role¶

Log into your designated AD FS VM.
Join this server to your yourcompany.internal domain and restart.
Log back in with your domain administrator account.
Open Server Manager -> Manage -> Add Roles and Features.
On the Server Roles screen, select Active Directory Federation Services.
Proceed through the wizard and click Install.

Step 2: Create a Dedicated Service Account¶

For better security and to avoid common setup issues, we will create a standard user account to run the AD FS service. 1. On your Domain Controller VM, open Active Directory Users and Computers. 2. In your VDI_Environment OU, create a new user named adfs_service. 3. Set a strong password and check the boxes for "User cannot change password" and "Password never expires".

Step 3: Configure the AD FS Service¶

Back on your AD FS server, click the notification flag in Server Manager and select "Configure the federation service on this server".
Select "Create the first federation server farm".
On the Connect to AD DS page, confirm your administrator account is shown.
On the Specify Service Properties page:
- SSL Certificate: For initial setup, we will create a temporary certificate. Open PowerShell (Admin) and run:
```
New-SelfSignedCertificate -DnsName "adfs.yourcompany.internal" -CertStoreLocation "cert:\LocalMachine\My"
```
- Go back to the wizard, click Previous then Next to refresh. Select the new adfs.yourcompany.internal certificate from the dropdown.
- Federation Service Name will auto-populate.
- Federation Service Display Name: Enter a user-friendly name, like "Your Company Login".
On the Specify Service Account page:
- Select "Use an existing domain user account...".
- Click "Select..." and choose the adfs_service account you created. Enter its password.
On the Specify Database page, select "Create a database on this server using Windows Internal Database (WID)".
Proceed through the wizard, pass the prerequisite checks, and click Configure.

5. Part 3: Connecting Your Platform to AD FS (Application Group)¶

Here, we will register our platform with AD FS, so it knows who is allowed to connect.

Step 1: Create the Application Group¶

On your AD FS server, open AD FS Management (adfsmgmt.msc).
Right-click Application Groups -> Add Application Group....
Name it Cloud_VDI_Platform.
Under "Client-Server applications", select the "Server application and Web API" template. Click Next.

Step 2: Configure the Server Application¶

Client Identifier: A GUID is generated. Copy this value; you will need it for our platform's configuration.
Redirect URI: Enter the callback URL provided by our platform's documentation (e.g., https://<your-platform-url>/callback). Click Add. Click Next.
Select "Generate a shared secret". Copy this secret immediately and store it securely. This is your Client Secret. Click Next.

Step 3: Configure the Web API¶

Identifier: On the Web API screen, paste the Client Identifier you copied in the previous step into the "Relying party identifier" box and click Add. Click Next.
Choose an access control policy (e.g., "Permit everyone") for now. Click Next.

Step 4: Configure Issuance Transform Rules (To Send Group Memberships)¶

On the Summary screen, click Next, then Close. The Application Group is created.
Double-click the Cloud_VDI_Platform group you just created.
Double-click the Web API application in the list.
Go to the Issuance Transform Rules tab and click Add Rule....
Choose the "Send LDAP Attributes as Claims" template.
Rule Name: Send User Attributes
Attribute store: Active Directory
Configure the following mapping. The Token-Groups entry is critical for VDI entitlements.

LDAP Attribute	Outgoing Claim Type
Token-Groups - Unqualified Names	group
E-Mail-Addresses	E-Mail Address
Display-Name	Name

Click Finish, then OK.

6. Part 4: Making AD FS Production-Ready¶

The temporary certificate and internal name must be replaced for public access.

Step 1: Install a Public SSL Certificate¶

Obtain a valid SSL certificate for your public DNS name (e.g., sso.yourcompany.com) from a public Certificate Authority (e.g., Let's Encrypt, GoDaddy, etc.).
You will need to export this certificate along with its private key into a single .pfx file, protected by a password.
Import this .pfx file into the "Personal" -> "Certificates" store for the Local Computer on your AD FS server using the MMC Certificates snap-in (mmc.exe).
During the import, ensure you "Mark this key as exportable".
After importing, right-click the new certificate -> All Tasks -> Manage Private Keys.... Add the adfs_service account and grant it Read permissions.

Step 2: Update AD FS to Use the Public Hostname and Certificate¶

This is a multi-part process that must be done carefully.

A. Update AD FS Service Properties¶

In AD FS Management, go to Service -> Edit Federation Service Properties....
Change the Federation Service name to your public DNS name (e.g., sso.yourcompany.com).
Go to Service -> Certificates. Click Set Service Communication Certificate... and select your new public SSL certificate.

B. Update the Service Principal Name (SPN)¶

The service account must be associated with the new public name. Open PowerShell (Admin) and run:

# Replace with your values
$newHostName = "sso.yourcompany.com"
$oldHostName = "adfs.yourcompany.internal"
$serviceAccount = "adfs_service"

Set-ADUser -Identity $serviceAccount -ServicePrincipalNames @{Remove="HOST/$oldHostName"; Add="HOST/$newHostName"}

C. Update the SSL Binding for the Web Service¶

The underlying Windows web service must be manually told to use the new certificate. This is a critical step. 1. First, get the thumbprint of your new public certificate:

Get-ChildItem cert:\LocalMachine\My

2. Run the following commands, replacing the thumbprint with your value.

$newCertThumbprint = "YOUR_PUBLIC_CERT_THUMBPRINT_HERE"
$adfsAppId = "{5d89a20c-beab-4389-9447-32478820194a}"

# Set the SSL binding for all IPs on port 443
netsh http add sslcert ipport=0.0.0.0:443 certhash=$newCertThumbprint appid=$adfsAppId

Note: If this command fails because a binding already exists, first run netsh http delete sslcert ipport=0.0.0.0:443 and try again.

Finally, restart the AD FS service to apply all changes:
```
Restart-Service adfssrv
```

7. Part 5: Finalizing the OIDC Configuration for Claims¶

These final steps ensure our platform receives all the information it needs in a standard way.

Step 1: Grant Scope Permissions to Your Application¶

By default, AD FS will only grant the openid scope. We must permit the others. 1. In AD FS Management, go to Application Groups -> Cloud_VDI_Platform -> double-click the Web API. 2. Go to the Client Permissions tab. 3. Select your client ID from the list and click Edit.... 4. Check the boxes for all available scopes, especially profile, email, and allatclaims. 5. Click OK.

Step 2: Ensure Claims are Sent to the UserInfo Endpoint¶

To support generic OIDC clients that rely on the UserInfo endpoint, we must attach the required claims to the standard scopes. The simplest way is via PowerShell. 1. Open PowerShell (Admin) on the AD FS server. 2. Run this command to attach the necessary claims to the profile scope:

Set-AdfsScopeDescription -TargetName "profile" -AddClaims "name", "email", "group"

3. Restart the AD FS service:

Restart-Service adfssrv

Step 3: Configure the Web API for UserInfo Access¶

To allow the UserInfo endpoint to be called, the Web API's identifier must match the AD FS issuer name. 1. In AD FS Management, go to Cloud_VDI_Platform -> double-click the Web API. 2. Go to the Identifiers tab. 3. Remove the existing identifier (which is likely the Client ID). 4. Add a new identifier that is your AD FS issuer URL (e.g., https://sso.yourcompany.com/adfs). 5. Click OK.

8. Part 6: Your Platform's Configuration¶

You now have all the information needed to configure the OIDC provider on our platform. * Issuer URL: https://<your-public-adfs-dns-name>/adfs * Client ID: The value you copied in Part 3, Step 2. * Client Secret: The value you copied in Part 3, Step 2. * Scopes: openid profile email allatclaims

9. Troubleshooting Common Issues¶

Error Message (in Browser/Logs)	Cause	Solution
`DNS_PROBE_FINISHED_NXDOMAIN`	Your computer cannot find the public DNS record for your AD FS server.	Ensure your public DNS record has been created and has had time to propagate. For testing, you can add an entry to your local `hosts` file (`/etc/hosts` or `C:\Windows\System32\drivers\etc\hosts`).
`ERR_CONNECTION_RESET` or Connection Timeout	A firewall is blocking the connection.	Verify your cloud firewall rules allow inbound traffic on TCP port 443 to the AD FS VM. Also verify the Windows Firewall on the AD FS VM itself has an inbound rule allowing TCP 443.
`ERR_CERT_AUTHORITY_INVALID`	You are using a self-signed or temporary certificate that the browser does not trust.	This is expected during initial setup. For production, you must install a valid public SSL certificate as described in Part 4.
UserInfo endpoint is empty or missing claims	The client does not have permission for the scopes, or the scopes are not configured to release claims.	Ensure you have granted permissions for `profile` and `email` scopes (Part 5, Step 1) and have attached the claims to the `profile` scope using PowerShell (Part 5, Step 2).
Verification code email not received	The user account in Active Directory does not have a valid, real-world email address.	Open the user's properties in Active Directory Users and Computers, go to the General tab, and populate the E-mail field with a real, accessible email address.
AD FS GUI Error: "data set was stale"	The management console's view of the configuration is out of date.	Close and reopen the AD FS Management console to get a fresh session, then try the operation again.
AD FS GUI Error: "Object reference..."	A bug in the graphical interface, often related to certificate operations.	Bypass the GUI and perform the operation using the equivalent PowerShell command. For setting the SSL certificate, use `Set-AdfsSslCertificate`.

10. System Maintenance & Lifecycle Management¶

A production system requires ongoing maintenance to ensure it remains secure and operational. Here are the key areas to manage for your AD FS deployment.

Certificate Renewals¶

You have two types of certificates that will expire and must be managed:

Service Communication (SSL) Certificate:
- What it is: The public SSL certificate you installed in Part 4.
- Impact of Expiration: Browsers and client applications will show security warnings, and connections will fail.
- Action: Before the certificate expires, you must renew it with your public Certificate Authority, import the new .pfx file, and follow the procedure in Part 4, Step 2 to update the AD FS service and the underlying netsh binding.
Token-Signing and Token-Decrypting Certificates:
- What they are: These are self-signed certificates that AD FS creates automatically. They are used to digitally sign the tokens sent to our platform, proving they are legitimate and have not been tampered with.
- Impact of Expiration: Authentication will fail because our platform will no longer trust the expired signing certificate.
- Action: AD FS includes a feature called "Auto Certificate Rollover." By default, it will automatically generate new certificates and promote them to be the primary ones before the old ones expire.
  - Verification: You can check the status in the AD FS Management -> Service -> Certificates console.
  - Manual Rollover: In an emergency, you can force a rollover using the Update-AdfsCertificate command in PowerShell.

Server Patching¶

Like any server, your Domain Controller and AD FS VMs must be kept up-to-date with the latest Windows Server security patches. Apply updates regularly during scheduled maintenance windows. A restart of the AD FS service or server may be required.

Monitoring and Event Logs¶

AD FS logs detailed information about its operations, including successful and failed login attempts. This is invaluable for troubleshooting. * Location: Open Event Viewer on the AD FS server. * Path: Navigate to Applications and Services Logs -> AD FS -> Admin. * What to look for: Look for any Error or Warning events. Error messages often contain a unique "Event ID" and "Exception details" that can be used to diagnose problems.

Backup and Recovery¶

It is critical to back up your AD FS configuration. This allows you to restore the service quickly in case of a server failure. * Method: Use the built-in PowerShell cmdlet Backup-Adfs. * Example Command:

Backup-Adfs -BackupDir "C:\ADFS_Backups"

* Schedule: Run this command as a scheduled task on a nightly or weekly basis, and ensure the backup directory is stored on a separate, secure location.

11. Security Best Practices¶

Beyond the basic setup, follow these principles to harden your AD FS deployment.

Principle of Least Privilege¶

The dedicated service account (adfs_service) should not have excessive permissions. It should not be a member of the "Domain Admins" or "Enterprise Admins" groups. The AD FS configuration wizard correctly grants it the required "Log on as a service" right, which is sufficient.

Extranet Lockout Protection¶

AD FS includes a feature to protect against password-guessing and brute-force attacks coming from the internet. It can be configured to temporarily lock out an account after a certain number of failed password attempts. * How to Configure: This is managed via PowerShell using the Set-AdfsProperties cmdlet. * Example:

# Lock out accounts after 5 failed attempts for 15 minutes
Set-AdfsProperties -EnableExtranetLockout $true -ExtranetLockoutThreshold 5 -ExtranetObservationWindow (new-timespan -Minutes 15)

Strict Firewall Rules¶

Re-confirm your firewall rules are as restrictive as possible: * Domain Controller: Should have NO inbound rules from the internet. * AD FS Server: Should only allow inbound traffic from the internet on TCP port 443 (HTTPS). All other ports should be blocked from external access.

Auditing¶

Enable security auditing on your AD FS server to log successful and failed authentication attempts. This provides a clear record of who is accessing the system and when, which is critical for security investigations. Auditing can be configured within the AD FS Management console under the "Authentication Policies" section.

12. Conclusion¶

Congratulations! By completing this guide, you have successfully deployed a robust, production-ready authentication bridge between your internal Active Directory and our cloud platform.

You have achieved several key business and security objectives: * Centralized User Management: Your administrators can now manage VDI access using the same familiar tools they use for all other corporate resources. * Seamless Single Sign-On (SSO): Users can access our platform's resources without needing to remember a separate set of credentials, improving their experience and reducing support overhead. * Enhanced Security: Authentication is handled by your own trusted identity provider, and access can be granted or revoked instantly based on group membership. * Automated Provisioning: User accounts can be created automatically on our platform the first time a user logs in, streamlining the onboarding process.

This federated identity solution provides a secure, scalable, and efficient foundation for your VDI deployment.