Customer Portal SSO with OAuth/OIDC

Use the generic OAuth/OIDC option when customer identities are managed by an OpenID Connect (OIDC) provider such as Okta, Auth0, or Microsoft Entra ID.

Although the setting is commonly called OAuth SSO, Benji Pays relies on OIDC identity data in an ID token. An OAuth authorization server that does not support OpenID Connect is not sufficient.

Supported flow

The generic provider integration currently uses the OIDC implicit flow with:

response type id_token;
scopes openid profile email; and
the Benji Pays Login Redirect URL as an allowed sign-in callback.

Configure the provider application for this exact flow. Authorization code and SAML flows are not supported by the generic Customer Portal configuration.

Configure your identity provider

Create a web application in your OIDC provider:

Enable the implicit grant option that allows the id_token response type.
Include the openid, profile, and email scopes.
Copy the Login Redirect URL from the Benji Pays SSO form and add it as an exact allowed sign-in redirect URI.
Do not configure a sign-out URI unless your deployment has a separately documented requirement for one.
Record the provider's HTTPS issuer URL and Client ID.

Redirect URI comparison is exact at most providers. Scheme, host, path, port, and trailing slash differences can cause a mismatch.

Configure Benji Pays

In Benji Pays, open Settings → Customer Portal Settings → SSO Single Sign-On Configuration:

Select Add SSO Configuration.
Choose Other for a generic OIDC provider.
Enter a description.
Set Issuer URL to the provider tenant's HTTPS issuer URL.
Set Client ID to the OIDC application's client ID.
Keep response type id_token and scopes openid profile email.
Optionally customize the login button text.
Save and enable the configuration.

Use the issuer identifier itself, not an authorization endpoint URL. Your provider should publish OIDC discovery metadata relative to that issuer.

HaloPSA has a separate OIDC preset in Benji Pays. Use that preset for HaloPSA; use Other for generic providers.

Login sequence

The customer clicks the configured SSO button on the Customer Portal login page.
Benji Pays starts an OIDC authorization request at your provider.
The provider authenticates the customer and returns an ID token to the Login Redirect URL.
Benji Pays validates the OIDC response and extracts the customer's identity.
Benji Pays matches the asserted email to a customer with Portal Access and creates the portal session.

The email asserted by the provider must be usable for customer matching. A successful provider login does not grant Customer Portal access when the email is missing, does not match a portal-enabled customer, or belongs to a disabled account.

Email verification

Generic OIDC providers do not bypass Benji Pays email verification. On first login, a customer whose email has not already been verified for this SSO configuration receives a Benji Pays verification email and must complete that step before entering the portal.

The provider's email_verified claim does not skip this requirement for the generic Other configuration.

Provider checklist

Provider terminology differs, but these values map consistently:

Benji Pays value	Common provider label
Login Redirect URL	Sign-in redirect URI, callback URL, or allowed callback URL
Issuer URL	Issuer, authority, tenant URL, or OIDC issuer
Client ID	Application ID or OAuth client ID
`openid profile email`	Allowed or requested scopes
`id_token`	Response type / implicit ID token flow

Test the integration

Open the Customer Portal in a private browser session and confirm the custom SSO button appears.
Click the button, authenticate at the provider, and confirm the browser returns to the Customer Portal.
With an email not previously verified for this configuration, complete the Benji Pays verification email before continuing.
Confirm the signed-in email opens the expected portal company.
Test an identity whose email does not have Portal Access.
Change the provider callback temporarily to confirm a redirect URI mismatch is reported, then restore the exact Login Redirect URL.
Confirm disabled customer accounts cannot enter the portal.

For failures before the provider login page:

verify the Issuer URL is HTTPS and points to the correct tenant;
verify the Client ID belongs to the application you configured;
verify the provider permits id_token;
compare the redirect URI character for character; and
confirm the required OIDC scopes are permitted.

For the corresponding settings walkthrough, see SSO with OAuth for the Benji Pays Customer Portal.