Skip to content
Paycux

Identity providers

Connect OneLogin

OneLogin's custom SAML connector asks for more fields than most providers, and two of them — Recipient and ACS URL Validator — are the ones people get wrong. Work through them in order and the connection comes up on the first try.

Before you start

  • An organization in Paycux for the customer, with their email domain claimed.
  • OneLogin account administrator access.
  • The ACS URL and entity ID from the Paycux connection.
  • A regular expression escape of the ACS URL for the validator field, which OneLogin requires and which is the most common source of a failed first sign-in.

Add the application

  1. 1In the OneLogin admin area open Applications, then Add App.
  2. 2Search for SAML Custom Connector (Advanced) and select it. The basic connector omits fields you will need.
  3. 3Set the display name and icon, then save. The configuration tabs only appear after the first save.

Fill in the Configuration tab

Four fields carry the connection. Audience and Recipient are usually identical to the entity ID and ACS URL respectively, and the validator is a regular expression that must match the ACS URL exactly.

FieldValueNotes
Audience (EntityID)Paycux entity IDUnique per connection
RecipientPaycux ACS URLSame value as the consumer URL
ACS (Consumer) URL ValidatorEscaped regex of the ACS URLAnchored, with dots and slashes escaped
ACS (Consumer) URLPaycux ACS URLWhere the assertion is POSTed
SAML nameID formatEmailKeeps the subject readable and stable enough for most estates
SAML signature elementResponseUnless the connection is configured to expect a signed assertion
acs-url-validator
1# ACS URL
2https://api.paycux.com/sso/saml/acs/conn_01HQZX8N4T
3 
4# Validator alanina yazilacak kacisli surum
5^https:\/\/api\.paycux\.com\/sso\/saml\/acs\/conn_01HQZX8N4T$

If the validator does not match, OneLogin refuses to send the assertion at all and reports a generic configuration error. When a sign-in fails before the browser ever reaches your ACS URL, this field is where to look first.

Add the parameters

OneLogin calls attributes parameters. Each one needs the include in SAML assertion flag ticked; a parameter without it is stored and never sent, which produces a connection that works but yields nameless users.

Field nameValueFlags
emailEmailInclude in SAML assertion
firstNameFirst NameInclude in SAML assertion
lastNameLast NameInclude in SAML assertion
idOneLogin IDInclude in SAML assertion
groupsUser RolesInclude in SAML assertion, if roles depend on them

Finish the connection in Paycux

  1. 1Open the SSO tab of the OneLogin application.
  2. 2Copy the SAML 2.0 Endpoint (HTTP) and the Issuer URL, and view the X.509 certificate.
  3. 3Paste them into the Paycux connection, or use the Issuer URL to fetch metadata directly if the customer's OneLogin instance exposes it.
  4. 4Assign yourself under the Users tab or through a role, then run a test sign-in.
  5. 5Activate the connection once a test profile arrives with the attributes you expect.

Turn on SCIM provisioning

  1. 1Create a directory in Paycux for the same organization, choose OneLogin SCIM, and copy the endpoint URL and bearer token.
  2. 2Back in the OneLogin application, return to the Configuration tab and fill in SCIM Base URL and SCIM Bearer Token.
  3. 3Set the SCIM JSON Template to the default unless you have a reason to change it, then enable the API connection.
  4. 4On the Provisioning tab, tick Enable provisioning and decide which actions require admin approval. Requiring approval for deletions is a common and sensible choice.
  5. 5Choose what happens when a user is deleted or suspended in OneLogin: suspend is the safer default for most products.

When it does not work

SymptomUsual cause
Sign-in fails before reaching your appThe ACS URL Validator regex does not match the ACS URL.
Audience mismatchThe Audience field holds another connection's entity ID.
Attributes missing from the profileParameters exist but Include in SAML assertion was not ticked.
User is not in this appNot assigned directly or through a role.
SCIM connection refusedThe bearer token was pasted with surrounding whitespace, or into the wrong field.
Deletions never arriveProvisioning actions are held for admin approval and nobody has approved them.

Related

Enterprise SSO integrationThe code behind the connection.SCIM provisioning basicsWhat provisioning sends, and when.SSO glossaryAudience, recipient, name ID — defined.Admin Portal integrationLet the customer's admin fill these fields in.