Connect customer-portal sign-in to your identity provider with SAML

Updated Wednesday, October 28, 2026 · Marc Staine

SAML lets customers sign in to a Supportbench portal through an identity provider your organization trusts. It is useful when B2B customers need centrally managed sign-in while Supportbench continues to apply customer, company, case, and knowledge visibility rules. This guide covers customer-portal SAML; agent authentication is configured separately.

At a glance

For: portal administrators and identity administrators. Applies to: Supportbench Core.

Start here: Settings → Customer portal → select a portal → Security and sign-in → SAML

Prepare the identity and access plan · Match the provider and Supportbench values · Configure the portal · Locate the settings in common identity providers · Test identity and customer visibility · Maintain the connection · Understand the sign-in exchange before configuring it · Map the values with a fictional portal example · Run a small acceptance test before wider rollout · Troubleshoot a failed sign-in

Prepare the identity and access plan

Confirm permission to edit the portal or its security settings, and involve the administrator who controls the identity provider.
Identify the exact portal hostname customers will use. Preview and production hosts can require different SAML values.
Choose an existing, active test contact with the intended company and customer role. Confirm its sign-in identity and email match the identity-provider assertions.
Decide whether company mapping is required. Use a stable organization claim and an intentional company lookup field rather than a display name that can change.
Keep a working administrative access route while testing. Enable automatic SAML redirection only after the tested sign-in path works.

Match the provider and Supportbench values

Value	Purpose
Portal ACS / Reply URL	The public callback is https://your-portal-host/saml/auth. The provider posts the SAML response here. Use your actual active portal host.
Audience / Entity ID	For the portal flow, use https://your-portal-host, matching the active host and request audience.
SAML login URL	The identity provider’s sign-in endpoint, entered in Supportbench. This is different from the portal callback.
SAML certificate	The identity provider’s public signing certificate, used to validate signed assertions. Do not paste a private key.
Optional logout URL	The configured destination used for sign-out handling. Verify the intended provider behavior; a URL alone is not proof that every connected application session ends.
NameID and email claims	Identity information used to resolve or provision the customer contact. Test with the intended contact and company mapping.

Use HTTPS and the exact configured values. A valid provider login is only part of the flow: assertion signature, time validity, audience, recipient, customer state, and mapping must also pass.

Configure the portal

Open Settings → Customer portal, select the intended portal, then open Security and sign-in → SAML.
Configure the identity-provider application with the portal’s audience/entity ID and ACS URL. Obtain its login URL and public signing certificate.
In Supportbench, turn on Enable SAML and enter the SAML login URL, certificate, and optional logout URL. Review the available Username field and Allowed IP ranges with your identity plan; do not assume that choosing a field alone overrides the assertion’s contact-matching rules.
If needed, enable attribute mapping. Configure Company lookup attribute and Company lookup field, then add explicit SAML attribute → customer field mappings. Use only claims your identity provider controls.
Choose Save Changes. Test the normal portal sign-in route with the existing test contact and verify the resulting company and permissions.
After successful testing, enable Auto redirect to SAML if that is the intended customer experience, save, and test the entry route again.

Locate the settings in common identity providers

Provider menus can change. Use the current official instructions together with the Supportbench values above; do not copy a sample application’s URLs into your portal configuration.

Provider	Where the values belong
Microsoft Entra ID	Open the enterprise application → Single sign-on → SAML. In Basic SAML Configuration, set Identifier (Entity ID) and Reply URL (ACS) to the Supportbench portal values. Use the application’s login URL and public signing certificate in Supportbench, and assign the intended test user.
Okta	Create a SAML app integration. Set Single sign-on URL to the portal ACS and Audience URI (SP Entity ID) to the portal audience. Configure controlled user identity/claims and obtain the provider sign-in URL and signing certificate for Supportbench.

Provider references checked for this guide: Microsoft Entra SAML setup and Okta SAML field reference.

Test identity and customer visibility

Sign in through the intended portal host with the pre-existing test contact. Confirm the displayed identity and company.
Open a case and article the customer should see. Also check a representative item the customer should not see; never broaden access merely to make the test pass.
Test the company claim and mapped customer fields. An unmatched organization claim can stop sign-in.
Check sign-out and the next sign-in, then test automatic redirection if enabled.
Record the provider application, portal host, certificate expiry, and the responsible administrator so later changes have an owner.

New identities can create contacts

If no matching contact exists and the assertion contains a valid email, the sign-in flow can provision a contact. A later company-mapping failure can still prevent admission. Use a known existing test contact first rather than repeatedly trying invented email addresses.

Maintain the connection

Coordinate certificate renewal before expiry. When the portal domain changes, update the provider’s audience and callback values and complete the portal’s SAML-metadata acknowledgement only after the provider change is actually done. Retest sign-in and customer visibility on the new host.

Company association, customer roles, and article/case restrictions still apply after SAML authentication. A successful identity-provider login does not grant access to all records for the organization.

Understand the sign-in exchange before configuring it

The identity provider is the system that verifies the person’s identity, such as Microsoft Entra ID or Okta. Supportbench is the application they are trying to enter. After sign-in, the provider sends a signed message called an assertion. It says who signed in and can include controlled attributes such as email or organization.

The ACS (also called Reply URL) is where Supportbench receives that assertion. The Entity ID/Audience identifies the intended receiving portal. The signing certificate lets Supportbench verify the provider’s signature. These values have different jobs; the provider’s login address is not a substitute for the portal’s ACS.

The identity administrator configures the provider application; the Supportbench administrator configures the portal. The test customer only follows the normal portal sign-in experience. Give the two administrators a shared value checklist and an agreed test contact before enabling automatic redirection.

Map the values with a fictional portal example

Suppose the portal hostname were https://help.example.com. This is an illustration only: replace it with the real active portal hostname, not a guessed address.

Configure where	Example or source	Purpose
Identity-provider application: ACS/Reply URL	https://help.example.com/saml/auth	Receives the signed response at the portal.
Identity-provider application: Audience/Entity ID	https://help.example.com	Identifies this portal as the intended receiver.
Supportbench: SAML login URL	Copy the sign-in endpoint supplied by the provider application.	Starts the provider-side sign-in.
Supportbench: SAML certificate	Copy/export the provider application’s public signing certificate.	Validates the signed assertion; never use a private key.
Controlled identity/company claims	Use agreed claims whose values match the intended contact and company lookup.	Resolves the right customer rather than merely accepting a valid provider login.

Preserve the public certificate boundaries where provided by the certificate export and avoid copying surrounding explanatory text. Have the identity administrator confirm which certificate is active, when it expires and who owns rotation.

Run a small acceptance test before wider rollout

Start with an active existing contact whose intended company and role are known. Record a case/article they should see and a representative restricted item they should not see.
Sign in through the intended portal hostname. Confirm the displayed customer identity and company association, then test both permitted and restricted items.
If sign-in succeeds but the company is wrong, fix the identity/mapping issue before continuing. Successful authentication alone is not proof of correct customer visibility.
Test sign-out and the next sign-in, then enable/test automatic redirection only after the ordinary route works.
Document the non-secret configuration, certificate renewal owner and a working administrative access route. Repeat the test after a hostname, claim or certificate change.

Troubleshoot a failed sign-in

Symptom	Checks and correction
Provider succeeds but the portal rejects sign-in	Compare the actual portal host, audience, recipient/ACS, certificate, assertion validity, and controlled identity claims.
The wrong contact or company is selected	Review NameID/email, existing contact credentials, and company lookup claims. Correct the identity mapping before wider rollout.
Company mapping fails	Check that the signed claim resolves to the intended existing company field value.
A previously working connection fails	Check certificate expiry/rotation, provider policy changes, and portal hostname changes.
The customer signs in but cannot see an item	Review the customer role, company/case scope, article publication and restrictions, and portal/topic access separately.

Was this article helpful?