---
updatedAt: 2026-09-10T00:17:42.000Z
agentTools:
  projectIndex: https://developer.benjipays.com/llms.txt
---

# Customer Portal SSO with OAuth/OIDC

Connect an OpenID Connect identity provider to the Benji Pays Customer Portal.

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:

1. Enable the implicit grant option that allows the `id_token` response type.
2. Include the `openid`, `profile`, and `email` scopes.
3. Copy the **Login Redirect URL** from the Benji Pays SSO form and add it as an exact allowed sign-in redirect URI.
4. Do not configure a sign-out URI unless your deployment has a separately documented requirement for one.
5. 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**:

1. Select **Add SSO Configuration**.
2. Choose **Other** for a generic OIDC provider.
3. Enter a description.
4. Set **Issuer URL** to the provider tenant's HTTPS issuer URL.
5. Set **Client ID** to the OIDC application's client ID.
6. Keep response type `id_token` and scopes `openid profile email`.
7. Optionally customize the login button text.
8. 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

1. The customer clicks the configured SSO button on the Customer Portal login page.
2. Benji Pays starts an OIDC authorization request at your provider.
3. The provider authenticates the customer and returns an ID token to the Login Redirect URL.
4. Benji Pays validates the OIDC response and extracts the customer's identity.
5. 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

1. Open the Customer Portal in a private browser session and confirm the custom SSO button appears.
2. Click the button, authenticate at the provider, and confirm the browser returns to the Customer Portal.
3. With an email not previously verified for this configuration, complete the Benji Pays verification email before continuing.
4. Confirm the signed-in email opens the expected portal company.
5. Test an identity whose email does not have Portal Access.
6. Change the provider callback temporarily to confirm a redirect URI mismatch is reported, then restore the exact Login Redirect URL.
7. 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](https://support.benjipays.com/support/solutions/articles/150000197750-sso-with-oauth-for-benji-pays-customer-portal).