Identity providers

Connect Microsoft Entra ID

Entra ID — the directory formerly called Azure AD — sits behind a very large share of corporate identity, and its setup differs from the others in one important respect: claim names are long URIs rather than short labels. Once you know that, the rest is a familiar shape.

Before you start

An organization in Paycux for the customer, with their email domain claimed.
An account in the Entra admin centre with the Application Administrator or Cloud Application Administrator role.
The ACS URL and entity ID from the Paycux connection.
For provisioning, an Entra ID plan that includes automatic user provisioning. This is a licensing question, and it is worth confirming before promising a customer a date.

Create the enterprise application

1In the Microsoft Entra admin centre open Enterprise applications, then New application.
2Choose Create your own application, name it what your customer's staff will recognise, and select the option for an application not in the gallery.
3Open Single sign-on and choose SAML.
4Edit the Basic SAML Configuration. Put the Paycux entity ID into Identifier (Entity ID), and the Paycux ACS URL into Reply URL (Assertion Consumer Service URL).
5Leave Sign on URL empty unless the customer wants identity-provider-initiated sign-in from their launcher.
6Save, then assign yourself under Users and groups so you can test.

Configure the claims

Entra ID sends a default claim set whose names are schema URIs. They work, but the unique user identifier is the one to check: the default is user.userprincipalname, which is not always the person's email address and can change when an account is migrated between domains.

Set the unique identifier to user.objectid — a stable GUID that never changes for the life of the account — and send the email separately as an attribute.

Claim name	Source attribute	Notes
Unique User Identifier (Name ID)	user.objectid	Stable across renames and domain moves
emailaddress	user.mail	Falls back to userprincipalname if mail is unset
givenname	user.givenname	First name
surname	user.surname	Last name
groups	Security groups	Only if roles depend on them — see below

If user.mail is empty for some accounts, the directory has never had a mailbox assigned for them. Ask the customer to populate it rather than falling back to the principal name, which is not guaranteed to be a deliverable address.

Group claims, carefully

Entra ID emits group claims as object GUIDs by default, not names, which makes them unreadable in your admin interface. It also has a hard limit: past roughly 150 groups the claim is replaced by a link to the Graph API, and your assertion silently arrives without groups.

Send only the groups assigned to the application, and switch the claim to sAMAccountName if the directory is synchronised from on-premise Active Directory and readable names matter to you.

entra-group-claim

1Group Claims  ->  Groups assigned to the application
2Source attribute  ->  Cloud-only group display names
3                      (sAMAccountName for AD-synchronised groups)
4 
5# "All groups" secilirse buyuk dizinlerde claim tamamen dusebilir.

Finish the connection in Paycux

1In the SAML Certificates section, download Federation Metadata XML.
2Upload that file to the Paycux connection. It carries the sign-on URL, the entity ID and the signing certificate together, which avoids the transcription errors that come from copying a certificate by hand.
3Run a test sign-in as an assigned user and confirm the profile arrives with an email, a first name and a last name.
4Activate the connection.

Turn on provisioning

1Create a directory in Paycux for the same organization, choose Entra ID SCIM, and copy the endpoint URL and bearer token.
2In the enterprise application, open Provisioning and set the mode to Automatic.
3Paste the endpoint into Tenant URL and the token into Secret Token, then choose Test Connection.
4Under Mappings, review Provision Microsoft Entra ID Users. Confirm externalId is mapped to objectId — this is what keeps records matched after a rename.
5Set the scope to Sync only assigned users and groups unless the customer explicitly wants their whole directory in your product.
6Turn Provisioning Status on and save.

Entra ID provisioning runs on a cycle of roughly forty minutes, and the first cycle is a full sync. Do not judge a connection broken because a user created a minute ago has not appeared; check the provisioning logs instead.

When it does not work

Symptom	Usual cause
AADSTS50105 — user not assigned	The account is not in Users and groups for this application.
Reply URL does not match	The ACS URL in Basic SAML Configuration differs, often by protocol or a trailing slash.
Identifier changes between sign-ins	The name ID is still user.userprincipalname and an account was migrated.
Groups missing from the assertion	The group count exceeded the claim limit, or All groups was selected.
Provisioning quarantined	Repeated failures against the endpoint. Fix the cause, then restart provisioning explicitly.
Users provisioned but never removed	Scope is set to all users, or the account was unassigned rather than disabled.

Enterprise SSO integrationThe code behind the connection.Connect ADFSThe on-premise sibling you will meet in older estates.SCIM provisioning basicsWhat the provisioning cycle is doing.Admin Portal integrationHand this whole page to the customer's admin.