Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt

Use this file to discover all available pages before exploring further.

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 Platform → Settings → 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 → SSO in your browser. Keep both open in adjacent windows to copy values across.

​
Configuration overview

1

Create the SSO configuration in TrueFoundry

Save an empty SAML configuration in TrueFoundry to surface the Callback URL and Issuer that AD FS needs.
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 Platform → Settings → SSO and click Configure.
2

Fill in the basic fields

  • Enabled: turn this on.
  • Name: a label such as AD FS SAML.
  • SSO Provider: choose Custom.
  • Authentication Configuration: select SAML v2.
Leave Identity Provider Endpoint and X.509 Certificate blank for now — you will fill them in after configuring AD FS.
3

Save to reveal the Callback URL and Issuer

Click Save. TrueFoundry will display two values you will need on the AD FS side:
  • Callback URL — used as the Assertion Consumer Service (ACS) URL in AD FS.
  • Issuer — used as the Relying Party Identifier in AD FS.

​
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
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 Platform → Settings → 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.
Check that the Send LDAP Attributes as Claims rule is sending E-Mail Address and that the user has a populated mail / userPrincipalName attribute in Active Directory. If your AD schema uses a different attribute, expand Show advanced fields in the TrueFoundry SSO form and explicitly set:
  • Email Claim → http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • Unique ID Claim → http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
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….