Connecting On-Premise Active Directory to a Managed PKI via AD FS

This page explains how to connect your on-premise Active Directory (AD) to an externally hosted Managed PKI, such as the DARZ Managed PKI. By creating a secure identity bridge, you can enable User Federation to provide Single Sign-On (SSO) and controlled identity management. In order to issue certificates for AD managed objects, you can follow the instructions in this page.

The established and required approach is to deploy Active Directory Federation Services (AD FS). AD FS acts as an Identity Provider (IdP), allowing your users to authenticate locally against your AD while securely passing standard tokens (OpenID Connect or SAML) to the Managed PKI’s Keycloak identity broker.

Installing and Securing AD FS & WAP

To maintain a secure posture, AD FS requires a two-server architecture: an internal AD FS server connected to your Active Directory and a Web Application Proxy (WAP) server residing in your DMZ.

Prerequisites

  • A dedicated Virtual Machine running Windows Server 2016 or newer joined to your AD domain.

  • A second Windows Server 2016 or newer located in your DMZ. For security reasons, this server should not be joined to your internal AD domain.

  • A valid SSL/TLS Certificate for your federation service name (e.g., adfs.yourcompany.com). The certificate must be issued by a public Certificate Authority. If you use an internal CA, Keycloak and external client devices will reject the TLS handshake and authentication will fail.

  • A Group Managed Service Account (gMSA) in your Active Directory to run the AD FS service securely.

  • Network/DNS: The WAP server must be able to resolve the Federation Service Name (e.g., sts.yourcompany.com) to the internal IP address of your AD FS server. You can achieve this via an entry in the WAP server’s C:\Windows\System32\drivers\etc\hosts file.

  • Firewall: Port 443 must be open inbound from the internet to the WAP and port 443 must be open outbound from the WAP to the internal AD FS server.

Step 1: Internal AD FS Server Installation

  1. Import your SSL certificate (with private key) into the Local Machine Personal certificate store.

  2. Open Server Manager > Manage > Add Roles and Features.

  3. Select Active Directory Federation Services and install.

  4. Launch the AD FS Configuration Wizard from the Server Manager warning flag.

  5. Select Create the first federation server in a federation server farm.

  6. Select the SSL certificate you imported, define the Federation Service Name and specify your gMSA account.

  7. Select Windows Internal Database (WID) and finalize the configuration.

Step 2: Web Application Proxy (WAP) Installation

  1. Copy the .pfx SSL certificate from the AD FS server to the WAP server.

  2. Import the .pfx file into the WAP server’s Local Machine Personal certificate store.

  3. Open Server Manager > Manage > Add Roles and Features.

  4. Select the Remote Access role.

  5. On the Role Services screen, check Web Application Proxy. Complete the installation.

  6. Launch the Web Application Proxy Configuration Wizard.

  7. Enter the Federation Service Name (e.g., sts.yourcompany.com).

  8. Enter the credentials of a local administrator account on the internal AD FS server (this is required once to establish the proxy trust).

  9. Select the SSL certificate you imported.

  10. Finalize the configuration. The WAP is now securely proxying requests to your internal AD FS farm.

Verifying WAP Connectivity

A simple, zero-configuration way to verify that your Web Application Proxy (WAP) is successfully routing external traffic to your internal AD FS server is to check the public metadata endpoints. These are the exact URLs Keycloak will call to establish the connection.

You must perform this test from a device outside your corporate network (e.g., a smartphone on cellular data or a remote machine).

Open a web browser or use a tool like curl to reach one of the following URLs, depending on your chosen integration protocol:

For OpenID Connect (OIDC):

Navigate to the OIDC Discovery endpoint:

https://<your-federation-service-name>/adfs/.well-known/openid-configuration

For Example: https://sts.yourcompany.com/adfs/.well-known/openid-configuration

Expected Result: Your browser should display a raw JSON document containing various AD FS configuration endpoints (authorization, token, jwks, etc.).

For SAML 2.0:

Navigate to the Federation Metadata endpoint:

https://<your-federation-service-name>/FederationMetadata/2007-06/FederationMetadata.xml

Expected Result: Your browser should download or display a large XML document containing your AD FS public keys and claim definitions.

If these pages load successfully and return the JSON or XML data, your external DNS, firewall rules and WAP routing are working correctly. You can then confidently proceed to configure Keycloak.

If the connection times out, returns an SSL error or shows a "503 Service Unavailable" page, check your WAP proxy configuration and external firewall rules.

Phase 2: Connecting to Keycloak

You can connect AD FS to the Managed PKI Keycloak instance using either OpenID Connect (OIDC) or SAML 2.0.

OpenID Connect (OIDC) is highly recommended. AD FS automatically rotates its token-signing certificates annually. OIDC handles this gracefully via a dynamic JSON Web Key Set (JWKS) endpoint. If you use SAML, this annual rotation will break authentication until you manually update the Keycloak configuration.

OIDC is the modern standard for identity federation. Ensure your AD FS is running on Windows Server 2016 or newer.

Step 1: AD FS Configuration

  1. Open AD FS Management and navigate to Application Groups > Add Application Group.

  2. Select Server application accessing a web API.

  3. Server Application: Name the application (e.g., Managed PKI). Copy the generated Client ID.

  4. Redirect URI: Enter the Keycloak redirect URI provided by your PKI administrator (e.g., https://<keycloak-domain>/realms/mtg-ers/broker/adfs-oidc/endpoint).

  5. Client Secret: Copy the generated Client Secret. Treat this securely.

  6. Web API: Set the Identifier to the exact Client ID from Step 3.

  7. Issuance Transform Rules: Configure rules to send necessary claims for User Federation (e.g., mapping User-Principal-Name to the upn claim).

Step 2: Keycloak Configuration

  1. In the Keycloak Admin Console, go to Identity Providers > Add provider > OpenID Connect v1.0.

  2. Set the alias (must match the alias in your Redirect URI, e.g., adfs-oidc).

  3. Scroll to Import External IDP Config and enter the AD FS Discovery URL: https://<your-adfs-domain>/adfs/.well-known/openid-configuration

  4. Click Import. Keycloak will automatically populate the Authorization, Token and JWKS URLs.

  5. In the OIDC Config section, enter the Client ID and Client Secret.

  6. Set Client Authentication to Client secret sent as post.

  7. Click Save, then configure the necessary Mappers to map AD FS claims (like email or name) to Keycloak user attributes.

Alternative Option: SAML 2.0

If your environment strictly requires SAML, follow these steps. Be prepared to manage annual certificate rollovers manually or via API automation.

Step 1: AD FS Configuration

  1. In AD FS Management, go to Relying Party Trusts > Add.

  2. Select Claims aware and click Start.

  3. Choose Import data about the relying party from a file and upload the Keycloak SAML SP Metadata XML file.

  4. Name the trust and proceed through the wizard.

  5. Right-click the new trust and select Edit Claim Issuance Policy.

  6. Map your internal AD attributes (e.g., E-Mail-Addresses) to outgoing SAML claims (e.g., E-Mail Address).

  7. Provide your AD FS Federation Metadata URL to the Keycloak administrator (usually https://<your-adfs-domain>/FederationMetadata/2007-06/FederationMetadata.xml).

Step 2: Keycloak Configuration

  1. In Keycloak, go to Identity Providers > Add provider > SAML v2.0.

  2. Set the alias.

  3. Scroll to Import External IDP Config and paste the AD FS Federation Metadata URL (or upload the XML file).

  4. Click Import. This populates the SSO URLs and token-signing certificates.

  5. Click Save, then navigate to the Mappers tab to map the incoming SAML attributes to Keycloak attributes.

Troubleshooting Common Integration Errors

1. Token Rejected: Clock Skew (NTP Issues)

Symptom: Users authenticate successfully at the AD FS login screen, but upon redirecting to Keycloak, they receive an "Invalid Token" or "Login Failed" error.

Cause: The system clocks on your AD FS server and the Keycloak server are out of sync. Security tokens are strictly time-bound.

Resolution: Ensure both your on-premise AD FS servers and the Managed PKI Keycloak servers are synchronizing their time with a reliable Network Time Protocol (NTP) server.

2. SAML Error: Invalid NameID Format

Symptom: Keycloak rejects the SAML response with an error mentioning NameID format mismatch.

Cause: AD FS is not sending the NameID claim in the format Keycloak is requesting.

Resolution: Add a new rule in AD FS using the Transform an Incoming Claim template. Map your desired incoming identifier (e.g., UPN) to an Outgoing claim type of Name ID and set the format to whatever Keycloak expects (e.g., Email).

3. SAML Error: Signature Validation Failed

Symptom: SAML authentication stops working and Keycloak logs show Invalid signature or Signature validation failed.

Cause: AD FS automatically rotates its token-signing certificate every 365 days. The old certificate pinned in Keycloak is no longer valid.

Resolution: Obtain the new Federation Metadata XML from your AD FS server and re-import it into Keycloak. To permanently fix this, switch to OpenID Connect (OIDC).

4. OIDC Error: Invalid Client Credentials

Symptom: The redirect back to Keycloak fails with an invalid_client error in the logs.

Cause: The Client ID or Client Secret configured in Keycloak does not exactly match AD FS, or the secret has expired.

Resolution: Generate a new Client Secret in the AD FS Application Group properties and update the OIDC Identity Provider configuration in Keycloak.

5. External Users Cannot Reach AD FS

Symptom: Users on the corporate network can log in, but remote users get a timeout error when redirected to AD FS.

Cause: The Web Application Proxy (WAP) is misconfigured or firewall rules are blocking traffic.

Resolution: Verify that port 443 is open inbound from the internet to the WAP and that the WAP can successfully resolve and route traffic via port 443 to your internal AD FS server.