Merchant Portal Single-Sign-On
Security Assertion Markup Language (SAML) Setup
Security Assertion Markup Language (SAML) is an open standard for exchanging authentication data between an identity provider (IdP) and a service provider (SP). This guide walks through connecting your SAML IdP — Okta, Microsoft Entra ID (Azure AD), OneLogin, Ping, ADFS, or any SAML 2.0-compliant provider — to the Zentact Merchant Portal.
In this integration your IdP authenticates your users, and Zentact acts as the service provider that consumes the SAML assertion. Your connection is dedicated to your account: only users authenticated through your IdP can reach your merchant data.
Setup is a coordinated effort
Zentact provisions the SAML connection for you — it is not self-service. Plan for one round trip of information exchange before you can test.
Step 1: Register Zentact in your IdP
Create a new SAML 2.0 application in your IdP's administration console and configure it with the following service provider values.
Replace {connection-name} with the connection name Zentact assigns you during onboarding. Request this value before you begin — the URLs are not valid without it.
Live environment
| Field | Value |
|---|---|
| Assertion Consumer Service (ACS) URL | https://login.zentact.com/login/callback?connection={connection-name} |
| Entity ID / Audience URI | urn:auth0:prod-live-zentact:{connection-name} |
| Name ID format | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress |
| Binding | HTTP-POST |
Test environment
| Field | Value |
|---|---|
| Assertion Consumer Service (ACS) URL | https://prod-test-zentact.us.auth0.com/login/callback?connection={connection-name} |
| Entity ID / Audience URI | urn:auth0:prod-test-zentact:{connection-name} |
Depending on your IdP, the ACS URL may be labeled Single Sign-On URL, Reply URL, or Consumer URL. The Entity ID may be labeled Audience URI, Identifier, or SP Entity ID.
Step 2: Configure the attribute statements
Zentact requires the user's email address to identify and provision the user. Configure your IdP to release the following attributes in the SAML assertion.
| Attribute | Claim name | Required | Notes |
|---|---|---|---|
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress | Yes | Must be the user's email. Used as the primary identifier. | |
| First name | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname | Recommended | Displayed in the Merchant Portal UI. |
| Last name | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname | Recommended | Displayed in the Merchant Portal UI. |
| Full name | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name | Optional | Used when first and last name are not sent. |
If your IdP emits short attribute names (email, firstName, lastName) rather than the full schema URIs, let Zentact know — the attributes can be mapped on the Zentact side instead of changing your IdP.
Email must be unique and stable
Zentact matches users on email address. If a user's email changes in your IdP, they will be treated as a new user on their next login and will need to be re-invited to the appropriate merchant accounts.
Step 3: Collect your IdP metadata
Gather the following configuration values from your IdP so Zentact can create the connection.
| Field | Description |
|---|---|
| Sign In URL | The URL where SAML authentication requests are sent. This is also called the single sign-on (SSO) endpoint. |
| Sign Out URL | The URL where SAML logout requests are sent. This is also called the single logout (SLO) endpoint. Optional. |
| X509 Signing Certificate | The public-key certificate used to validate the signature of the authentication assertions that have been digitally signed by your IdP. The .pem and .cer formats are accepted. |
| IdP Entity ID / Issuer | The unique identifier for your IdP, sent as the Issuer in the SAML response. |
| User ID Attribute | The attribute in the SAML token that identifies the user. Optional — see the fallback order below. |
| Email domains | The email domains your users log in with (for example example.com). Used to route users to your IdP at the login prompt. |
If User ID Attribute is not set, the user identifier is retrieved from the following claims, in order:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifierhttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/upnhttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
Most IdPs let you download a federation metadata XML file that contains the sign-in URL, entity ID, and signing certificate in one document. Providing this file is the fastest path — you can send it in place of the first four fields above.
Step 4: Share the metadata with Zentact
Send the metadata XML file (or the individual field values) to your Zentact contact. Securely provide any sensitive material using a trusted method for sharing sensitive information, such as the secret sharing feature in a password manager.
Zentact will then configure the connection, enable it for your account, set up email domain routing so your users are directed to your IdP, and confirm back to you when it is live.
Step 5: Test the configuration
Once Zentact confirms the connection is live, navigate to your Merchant Portal URL and sign in. You should be redirected to your IdP, authenticate there, and land back in the Merchant Portal.
Test with at least one user who has an existing Merchant Portal account and one who does not, so you can confirm both login and first-time provisioning behave as expected.
Certificate rotation
Signing certificates expire. When you rotate the certificate in your IdP, send the new certificate to Zentact before the old one expires so the connection can be updated without an outage. Both the old and new certificate can be held during the overlap window.
Troubleshooting
| Symptom | Likely cause |
|---|---|
Invalid audience or AudienceRestriction error | The Entity ID in your IdP does not exactly match the value in Step 1. It is case-sensitive. |
Invalid signature error | The signing certificate on file does not match the key your IdP is signing with. Usually a rotated or stale certificate. |
| Redirected back to the login page with no error | The assertion is missing the email attribute, or the ACS URL is missing the ?connection= query parameter. |
| User authenticates but sees no merchant accounts | Authentication succeeded but the user has not been granted access to any merchant accounts. This is an authorization step, not a SAML issue. |