Single Sign-On (SAML)

Connect PetroBench to Microsoft Entra ID, Okta, Google Workspace or any SAML 2.0 identity provider, and enforce SSO for your organization.

This page explains how to connect your identity provider to PetroBench with SAML 2.0 Single Sign-On.

Key points

Providers: Microsoft Entra ID, Okta, Google Workspace, Ping, Auth0, Keycloak and any SAML 2.0 identity provider.
Per organization: Each organization gets its own SAML endpoints and certificate.
Enforceable: You can turn off password sign-in so every user signs in through your identity provider.
MFA: Your identity provider handles MFA for SSO users.

Note: Single Sign-On (SSO/SAML) and SCIM provisioning are available as paid add-ons. The features and packages included in your subscription are set out in your subscription plan or order form.

Each PetroBench organization gets its own SAML endpoints. Users must exist in PetroBench with email addresses that match the values provided by your identity provider.

At a glance

Question	Answer
Protocol	SAML 2.0 (SP- and IdP-initiated login, optional Single Logout)
Scope	Configured per organization, with its own endpoints and certificate
Enforcement	Optional. When enforced, password login and password reset are disabled for the organization
MFA	Handled by your identity provider, so your existing MFA and conditional access policies apply
Provisioning	Manual, or automatic with SCIM 2.0 (requires docs login)
Setup	PetroBench configures the connection with your identity team, then tests both login flows before go-live

SAML endpoint pattern

PetroBench uses organization-specific SAML routes. Append each path to your deployment's base URL (e.g. https://app.petrobench.com).

Route	Purpose
`/saml/{organization-id}/metadata`	SP metadata / Entity ID
`/saml/{organization-id}/login`	SP-initiated login
`/saml/{organization-id}/acs`	Assertion Consumer Service (reply URL)
`/saml/{organization-id}/logout`	Single Logout (optional)

Your PetroBench account team provides the {organization-id} for your environment. The exact, copy-ready URLs are in What you receive from us below.

How setup works

PetroBench configures the SAML connection on your behalf. The exchange is:

We send you our SP details

Your account team provides the Service Provider (SP) endpoints below. Register PetroBench as a SAML application in your IdP using these values.

You send us your IdP details

Send us your IdP's SAML federation metadata (XML file or URL). The metadata contains everything we need; if you cannot share metadata, send the individual values in the intake list below.

We configure and test

PetroBench enters your values, then we test SP- and IdP-initiated login together before enabling SSO for your users.

What you receive from us (SP details)

Configure these Service Provider values in your IdP. {organization-id} is the identifier your account team provides.

SP Entity ID / Identifier

https://app.petrobench.com/saml/{organization-id}/metadata

Use this as the Entity ID / Identifier in your IdP.

ACS URL (Assertion Consumer Service)

https://app.petrobench.com/saml/{organization-id}/acs

Where your IdP sends SAML responses. Also called Reply URL or Callback URL.

https://app.petrobench.com/saml/{organization-id}/login

Where users initiate SSO login. Also called Sign-On URL.

SLO URL (Single Logout, optional)

https://app.petrobench.com/saml/{organization-id}/logout

Optional. Logs users out of both PetroBench and your IdP.

The ACS binding is HTTP-POST. NameID format must be email address. Sign the assertion; do not require signed AuthnRequests or encrypted assertions.

What we need from you (IdP details)

Send these to your account manager (see How to submit your details). The easiest path is your IdP federation metadata (XML or URL), which contains the required items below. PetroBench enters them in the Configure SAML 2.0 form (a staff-operated screen in the Admin Panel; customers do not access it directly). Required items are marked with an asterisk.

Identity Provider Configuration

Field	Required	What it is
Identity Provider		Select your IdP (Microsoft Entra ID, Okta, Google Workspace, Ping Identity, Auth0, Keycloak, AWS IAM Identity Center, WorkOS, or Custom SAML Provider). Choosing a provider shows provider-specific "where to find" hints for the remaining fields.
IdP Entity ID		The IdP's issuer / entity identifier (e.g. `https://sts.windows.net/<tenant-id>/`).
IdP SSO URL		The IdP's SAML 2.0 sign-on endpoint that PetroBench redirects users to.
IdP x509 Certificate		The IdP's Base64 (PEM) signing certificate, used to validate the SAML assertion.

Attribute Mapping

Field	Required	Default
Email Attribute		`email` - the assertion attribute carrying the user's email. Must match the user's email in PetroBench.
First Name Attribute	—	`firstName` - used for new-user provisioning.
Last Name Attribute	—	`lastName` - used for new-user provisioning.

Optional Configuration

Field	What it is
IdP Single Logout URL	The IdP's SLO endpoint, if Single Logout is supported.
Domain Verification	Your email domain (e.g. `example.com`) to associate with the organization.

SSO Requirements

Field	What it does
Require SSO	When enabled, all users in the organization must authenticate through the IdP. See Enforced SSO below.

How to submit your details

Send your identity provider details to your PetroBench account manager by email. The values exchanged are not sensitive, so email is fine.

We provide our SP details

Your account manager sends you PetroBench's Service Provider endpoints. Use them to register PetroBench as a SAML application in your identity provider.

You return your IdP details

Reply with the information listed below. We recommend a metadata URL rather than a pasted certificate: if your identity provider rotates its signing certificate, a URL continues to work, whereas a pasted certificate must be re-sent.

We configure and validate

PetroBench enters your configuration and schedules a brief test of both login flows before enabling SSO for your users.

Copy the following into your reply:

Reply to your account manager

1
IdP federation metadata URL (preferred), or the metadata XML fileIf neither is available: IdP Entity ID, IdP SSO URL, and Base64 x509 signing certificate
2
Email attribute name (default: email)
3
Optional: first/last name attribute names, IdP Single Logout URL
4
Your email domain (e.g. acme.com)
5
Users who need access: list of emails, or confirm SCIM provisioning

Identity provider requirements

Your IdP configuration should meet the following requirements:

Requirement	Detail
NameID format	Email address (`urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`)
NameID value	The user's email address
Email attribute	Include an email attribute in the SAML assertion that matches the Email Attribute mapping above
User matching	Users must exist in PetroBench with matching email addresses

Provisioning users

Before enabling SSO, ensure everyone who needs access exists in PetroBench with an email address that matches what your IdP sends. Users can be created manually in the Admin Panel or provisioned automatically via SCIM if enabled for your organization.

PetroBench supports two SSO login flows:

IdP-initiated: The user starts at your identity provider, selects PetroBench from the app catalog, and is redirected to PetroBench with a SAML assertion. No additional authentication is required.

SP-initiated: The user navigates to the PetroBench login page and selects "Sign in with SSO." PetroBench redirects to your IdP for authentication, then back to PetroBench after successful login.

Both flows produce the same session. The user is authenticated and placed in the correct organization based on their email address.

Enforced SSO

Organizations can enable enforced SSO, which requires all authentication to go through the IdP. When enforced SSO is active:

Local password login is disabled for all users in the organization
Password reset is disabled
All login attempts redirect through the SAML flow
API keys continue to work independently of SSO

You can also start with a password fallback during rollout and switch to enforced SSO once every user signs in through the IdP. Enforced SSO and the password fallback cannot be on at the same time.

SSO and MFA

When a user signs in through SSO, your identity provider handles the second factor. PetroBench does not ask SSO users for a separate PetroBench MFA code, so your existing MFA and conditional access policies stay the single place to manage it.

Users who still sign in with a password follow your organization's MFA policy.

Contact your PetroBench account team to enable enforced SSO.

SCIM provisioning

For automated user lifecycle management, PetroBench supports SCIM 2.0. When a user is onboarded or offboarded in your identity provider, the change propagates automatically to PetroBench.

See the SCIM Provisioning guide (requires docs login) for setup instructions and configuration details.

Troubleshooting

Issue	Resolution
User sees "No account found" after SSO	The user's email in PetroBench does not match the NameID or email attribute from the IdP. Verify the email mapping in your IdP configuration.
SAML assertion rejected	Check that the ACS URL in your IdP matches the PetroBench ACS endpoint exactly. Trailing slashes and protocol (https) matter.
User lands in wrong organization	The user may have accounts in multiple PetroBench organizations. Contact support to resolve the mapping.
IdP shows "unknown service provider"	Re-import the PetroBench SP metadata in your IdP. The metadata URL is always available at your organization's `/metadata` endpoint.

Supported identity providers

Microsoft Entra ID (Azure AD)
Okta
Google Workspace
Ping Identity
OneLogin
Auth0
Keycloak
Any other SAML 2.0 identity provider