Skip to main content
This guide walks you through setting up SAML 2.0 single sign-on between TrueFoundry and Microsoft Active Directory Federation Services (AD FS). Once finished, users in your AD forest can sign in to TrueFoundry through a Login with AD FS button.

​
Prerequisites

  • A TrueFoundry tenant with Admin access to Settings → Security & Access → SSO.
  • An AD FS server (Windows Server 2016 or newer) with administrative access to AD FS Management and Windows PowerShell as an administrator.
  • Network reachability from end-user browsers to both the AD FS sign-in endpoint (typically https://<adfs-server>/adfs/ls/) and your TrueFoundry control plane.
You will switch between AD FS Management on the Windows server and TrueFoundry → Settings → Security & Access → SSO in your browser. Keep both open in adjacent windows to copy values across.

​
Configuration overview

1

Create the SSO configuration in TrueFoundry

Save a SAML SSO configuration in TrueFoundry to surface the Assertion Consumer Service URL, Relying Party Identifier, and Relay URL.
2

Create a Relying Party Trust in AD FS

Add a claims-aware Relying Party Trust pointing at TrueFoundry.
3

Configure claim issuance rules

Map LDAP attributes to outgoing SAML claims and add a NameID transform.
4

Sign both the SAML response and assertion

Run a PowerShell command so AD FS signs both the SAML message and the assertion.
5

Paste AD FS values back into TrueFoundry

Copy the AD FS SSO endpoint and the token-signing certificate into TrueFoundry, then test.

​
Step 1 — Create the SSO configuration in TrueFoundry

1

Open SSO settings

Go to Settings → Security & Access → SSO.Click the + icon labeled Add New SSO Config.
TrueFoundry SSO settings page with the Add New SSO Config plus button highlighted
2

Fill in the basic fields

  • Enabled: turn this on.
  • Name: a lowercase alphanumeric label — for example, adfssaml.
  • SSO Provider: choose Custom.
  • Authentication Configuration: select SAML v2.
Leave Identity Provider Endpoint and X.509 Certificate blank for now — you’ll fill them in once AD FS surfaces those values.
3

Save to reveal the Single sign-on URL, Audience URI (SP Entity ID), and Relay URL

Click Save. TrueFoundry displays the values you need for AD FS on the SSO configuration card:
AD FS fieldValue from TrueFoundry
Assertion Consumer Service (ACS) URLSingle Sign On URL
Relying Party Trust IdentifierAudience URI (SP Entity ID)
Relay State (if used)Relay URL
TrueFoundry SSO configuration card displaying Audience URI, Single Sign On URL, Metadata URL, and Relay URL for SAML setup

​
Step 2 — Create a Relying Party Trust in AD FS

1

Open AD FS Management

On your AD FS server, open Server Manager → Tools → AD FS Management.In the left navigation, select Relying Party Trusts, then under Actions, click Add Relying Party Trust….
2

Choose Claims aware

On the Welcome page of the wizard, select Claims aware and click Start.
3

Select the data source

On Select Data Source, pick one of the following based on how your TrueFoundry control plane is reachable:
Choose Import data about the relying party published online or on a local network and enter the metadata URL of your TrueFoundry control plane. This is the recommended option when AD FS can reach the control plane.
Click Next.
4

Specify a display name

On Specify Display Name, enter a Display name such as TrueFoundry. Optionally add notes, then click Next.
Remember this exact display name — you will pass it to PowerShell in Step 4.
5

Choose an access control policy

On Choose Access Control Policy, select Permit everyone for a typical deployment, or pick a more restrictive policy (such as Permit specific group) if you want only specific AD groups to use TrueFoundry. Click Next.
6

Finalize the trust

Review the configuration on Ready to Add Trust and click Next. On Finish, leave Configure claims issuance policy for this application checked and click Close. The Edit Claim Issuance Policy dialog opens automatically.

​
Step 3 — Configure claim issuance rules

In the Edit Claim Issuance Policy dialog, add two rules: one to send LDAP attributes as claims, and one to transform the email claim into a properly formatted NameID.
1

Add a 'Send LDAP Attributes as Claims' rule

Click Add Rule…, choose Send LDAP Attributes as Claims, and click Next.Enter a Claim rule name such as LDAP attributes, select Active Directory as the Attribute store, and add the following mappings:
LDAP AttributeOutgoing Claim Type
E-Mail-AddressesE-Mail Address
E-Mail-Addressesemail
Object-Guidsub
Given-NameGiven Name
SurnameSurname
User-Principal-NameName ID
Click Finish.
2

Add a NameID transform rule

Click Add Rule… again, choose Transform an Incoming Claim, and click Next.Configure the rule as follows:
  • Claim rule name: Email to NameID
  • Incoming claim type: E-Mail Address
  • Outgoing claim type: Name ID
  • Outgoing name ID format: Email
  • Select Pass through all claim values.
Click Finish.
If you prefer to write the rule in the Claim Rule Language directly (for example to script the deployment), the equivalent rule is:
c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]
 => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
          Issuer = c.Issuer,
          OriginalIssuer = c.OriginalIssuer,
          Value = c.Value,
          ValueType = c.ValueType,
          Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"]
            = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");
Click OK to close the Edit Claim Issuance Policy dialog.
Without the NameID transform rule, AD FS sends NameID with Format="Unspecified". TrueFoundry will reject the assertion with an InvalidNameIDPolicy error.

​
Step 4 — Sign both the SAML response and assertion

By default AD FS only signs the SAML assertion, but TrueFoundry requires both the response message and the assertion to be signed. Open Windows PowerShell as an administrator on the AD FS server and run: 
Set-ADFSRelyingPartyTrust -TargetName "<display-name>" -SamlResponseSignature "MessageAndAssertion"
Replace <display-name> with the exact Display name you set in Step 2.

​
Step 5 — Paste AD FS values back into TrueFoundry

1

Locate the AD FS SAML sign-in URL

AD FS exposes its SAML endpoint at:
https://<adfs-server>/adfs/ls/
You can confirm this value by browsing to AD FS Management → Service → Endpoints and locating the row of type SAML 2.0/WS-Federation with URL path /adfs/ls/.
2

Export the token-signing certificate

In AD FS Management, expand Service → Certificates. Right-click the Token-signing certificate and choose View Certificate….
  1. Open the Details tab and click Copy to File….
  2. Choose Base-64 encoded X.509 (.CER) and save the certificate to disk.
  3. Open the saved .cer file in a text editor and copy the entire contents — including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.
3

Paste the values into TrueFoundry

Return to Settings → Security & Access → SSO in TrueFoundry and edit the SSO configuration you created in Step 1. Set:
  • Identity Provider Endpoint → https://<adfs-server>/adfs/ls/
  • X.509 Certificate → the PEM-encoded certificate text you just copied.
Click Save.
4

(Optional) Customise the login button

Expand Show advanced fields in the SSO form to set:
  • Button Text — for example, Login with AD FS.
  • Button Image URL — a public URL to your AD FS / corporate logo.
Leave Email Claim and Unique ID Claim at their defaults; the claim rules you added in Step 3 already emit the standard claim types TrueFoundry expects.

​
Step 6 — Test single sign-on

  1. Open a private/incognito window and go to your TrueFoundry login page.
  2. Click Login with AD FS (or the button label you chose).
  3. Authenticate with an Active Directory user that is permitted by your access control policy.
If sign-in succeeds you will land in the TrueFoundry dashboard. The user is created automatically when JIT provisioning is enabled; otherwise they must already exist in TrueFoundry or be invited first.

​
Troubleshooting

AD FS is sending NameID with Format="Unspecified". Re-open Edit Claim Issuance Policy on the Relying Party Trust and confirm the Email to NameID transform rule from Step 3 is present and ordered after the LDAP attribute rule.
AD FS only signed the assertion, not the response. Re-run the PowerShell command from Step 4:
Set-ADFSRelyingPartyTrust -TargetName "<display-name>" -SamlResponseSignature "MessageAndAssertion"
The token-signing certificate copied into TrueFoundry no longer matches the active certificate on AD FS — usually after an AD FS certificate rollover. Re-export the current Token-signing certificate from AD FS Management → Service → Certificates and paste the full PEM (including the BEGIN/END lines) back into TrueFoundry.
Confirm the Send LDAP Attributes as Claims rule emits email and sub as described in Step 3, and that the user has populated mail / userPrincipalName and objectGUID values in Active Directory. If your AD schema uses different attribute names, expand Show advanced fields in TrueFoundry and set Email Claim and Unique ID Claim to match the outgoing claim types you configured.
Your Access Control Policy on the Relying Party Trust is rejecting the user. Switch the policy to Permit everyone, or add the user’s AD group to the existing policy under Edit Access Control Policy….