Identity providers

Connect Okta

Okta is the identity provider you will meet most often in enterprise deals, and its setup is the closest thing this field has to a standard shape. This guide covers a SAML connection and SCIM provisioning end to end, from either side of the table: yours, or your customer's IT admin working through an Admin Portal link.

Before you start

Two people are involved: somebody with super admin rights in the Okta org, and somebody who can create a connection in Paycux. If those are different people at different companies, send an Admin Portal link instead and let the Okta admin do their half without a screen share.

An organization in Paycux for this customer, with their email domain claimed.
Okta super admin access, or an admin with rights to create application integrations.
The ACS URL and entity ID from the Paycux connection. Both are shown on the connection screen and are unique per connection.
About twenty minutes, most of which is attribute mapping and testing.

Create the application in Okta

1In the Okta admin console open Applications, then Applications, and choose Create App Integration.
2Select SAML 2.0 and continue. Do not pick SWA or OIDC unless you have decided to run an OIDC connection instead.
3Give the integration the name your customer's staff will see in their launcher, and upload your product logo.
4On the SAML settings step, paste the Paycux ACS URL into Single sign-on URL, and leave Use this for Recipient URL and Destination URL checked.
5Paste the Paycux entity ID into Audience URI (SP Entity ID).
6Set Name ID format to EmailAddress and Application username to Email.
7Finish the wizard, choosing the internal-application option when asked why you are creating the integration.

The ACS URL and entity ID are different for every connection. Copying them from another customer's setup produces an audience mismatch that looks like a signature failure and wastes an afternoon.

Map the attributes

Still on the SAML settings step, add attribute statements. Okta sends nothing beyond the name ID unless you ask, so a connection with no attribute statements produces users with an email and no name.

Name	Name format	Value
email	Basic	user.email
firstName	Basic	user.firstName
lastName	Basic	user.lastName
id	Basic	user.id

Send groups, if roles depend on them

If you intend to map Okta groups onto roles in your product, add a group attribute statement as well. Filter it rather than sending everything: a large Okta org can put hundreds of group names into an assertion, and some providers truncate at a size limit rather than failing loudly.

okta-group-attribute

1Name:         groups
2Name format:  Basic
3Filter:       Starts with   ->   app-yourproduct-
4 
5# Yalnizca urununuz icin acilmis gruplar gelir; tum dizin gelmez.

Finish the connection in Paycux

1In Okta, open the Sign On tab of the new integration and choose View SAML setup instructions, or download the identity provider metadata.
2Copy the Identity Provider Single Sign-On URL and the X.509 certificate.
3Paste both into the Paycux connection — or upload the metadata file, which fills in every field at once and is less error-prone.
4Assign yourself to the application in Okta, under the Assignments tab. An unassigned user cannot sign in, and the error message does not say so clearly.
5Run a test sign-in, then activate the connection.

Turn on SCIM provisioning

SAML lets people sign in; SCIM is what creates and deactivates their accounts. Okta calls this API integration, and it lives on a separate tab of the same application.

1Create a directory in Paycux for the same organization, choose Okta SCIM v2.0, and copy the endpoint URL and bearer token.
2In Okta, open the General tab of the application and enable SCIM provisioning under App Settings.
3On the Provisioning tab, paste the endpoint as the SCIM connector base URL and set Unique identifier field for users to email.
4Tick the supported actions: Push New Users, Push Profile Updates, Push Groups.
5Choose HTTP Header authentication and paste the bearer token, then test the connector configuration.
6Under To App, enable Create Users, Update User Attributes and Deactivate Users, then save.

Test the connector before assigning anyone. Okta reports a bad token as a generic connection failure, and it is far easier to see that with an empty assignment list than with two hundred users queued behind it.

When it does not work

Symptom	Usual cause
User is not assigned to this application	The person is not in the Assignments tab, or is only in a group that has not been assigned.
Audience mismatch or invalid audience	The Audience URI in Okta is not the entity ID from this connection.
Signature verification failed	The certificate was pasted with a line break or truncated, or it has been rotated in Okta.
Profile arrives with no name	No attribute statements were configured; only the name ID was sent.
SCIM users created but never deactivated	Deactivate Users was left off under To App, so departures are silent.
Group names arrive unmapped	Groups are being sent but no mapping to a role exists yet in your product.

Enterprise SSO integrationThe code behind the connection you just made.Directory Sync integrationHandling the events SCIM will now send.SCIM provisioning basicsWhat the provisioning tab is actually doing.Admin Portal integrationLet the Okta admin do all of this themselves.