Connect AD FS

Before you start

Everything here happens on the customer's side. Your job is to supply two values, receive two back, and be precise about the claim rules — because AD FS sends nothing at all unless a rule says to.

• An organization in Paycux for the customer, with their email domain claimed.
• The ACS URL and entity ID from the Paycux connection, sent to their engineer in writing.
• Their federation metadata URL, usually at /FederationMetadata/2007-06/FederationMetadata.xml on the AD FS host.
• Confirmation that the AD FS endpoint is reachable from the public internet. If it is only published internally, sign-in works from the office and nowhere else, and this surfaces late.

Create the relying party trust

1. 1On the AD FS server, open AD FS Management and choose Add Relying Party Trust.
2. 2Select Claims aware, then Enter data about the relying party manually.
3. 3Give the trust a display name that identifies your product.
4. 4Skip the token encryption certificate unless the connection is configured to expect encrypted assertions.
5. 5Tick Enable support for the SAML 2.0 WebSSO protocol and enter the Paycux ACS URL as the service URL.
6. 6Add the Paycux entity ID as the relying party trust identifier.
7. 7Choose Permit everyone as the access control policy, or a specific group if the customer wants to restrict who reaches your product.
8. 8Finish, leaving the option to edit claim issuance policy ticked.

Write the claim rules

This is the step that decides whether the connection works. AD FS issues no claims by default, so a trust created without rules authenticates people and tells you nothing about them.

Two rules are needed: one that pulls attributes out of Active Directory, and one that transforms the email claim into the name ID. They must be in that order, because the second consumes the output of the first.

1# Kural 1 — Send LDAP Attributes as Claims
2# Attribute store: Active Directory
3E-Mail-Addresses      ->  E-Mail Address
4Given-Name            ->  Given Name
5Surname               ->  Surname
6objectGUID            ->  Name ID  (kalici kimlik icin tercih edilir)
7 
8# Kural 2 — Transform an Incoming Claim
9Incoming claim type:   E-Mail Address
10Outgoing claim type:   Name ID
11Outgoing name ID format: Email
12Pass through all claim values

The claim types you will see

AD FS uses long schema URIs as claim names. These are what arrive in the assertion, and what a connection's attribute mapping refers to.

Finish the connection in Paycux

1. 1Fetch the federation metadata from the AD FS host and upload it to the Paycux connection. This carries the sign-on URL and the token-signing certificate together.
2. 2If the customer cannot expose metadata publicly, ask for an exported copy of the file and for the token-signing certificate in Base64.
3. 3Run a test sign-in from outside the customer's network, not only from inside it.
4. 4Confirm the profile carries an email, both names and a stable identifier, then activate the connection.

Provisioning, which AD FS does not do

AD FS is a federation service. It authenticates people; it has no mechanism for telling your application that somebody was hired or has left. A connection built on AD FS alone means departures stop being able to sign in but their accounts and data access remain.

There are two workable answers. If the customer synchronises Active Directory into Entra ID, provision from Entra ID with SCIM while authenticating through AD FS. If they do not, fall back to just-in-time provisioning from the assertion and agree an explicit deprovisioning process — usually an admin action in your product, triggered by their offboarding checklist.

When it does not work

Related