Skip to content

sso.mdx

Latest commit

 

History

History
211 lines (151 loc) · 8.26 KB

sso.mdx

File metadata and controls

211 lines (151 loc) · 8.26 KB
title SSO (SAML / OIDC)
icon Shield
description Configure Single Sign-On for your organization using SAML 2.0 or OpenID Connect. Scale plan only.

Single Sign-On (SSO) lets your team authenticate to PgBeam using your existing identity provider — Okta, Azure AD, Google Workspace, or any SAML 2.0 / OIDC provider. Team members sign in with their corporate credentials instead of managing separate PgBeam passwords.

SSO requires the **Scale plan**. See [Plans & Pricing](/docs/plans) for details.

Supported protocols

Protocol Use case
SAML 2.0 Enterprise IdPs (Okta, Azure AD, OneLogin)
OpenID Connect Modern IdPs and custom OAuth2 providers

Choose whichever protocol your identity provider supports. If your IdP supports both, OIDC is generally simpler to configure.

SAML 2.0 setup

### Create a SAML application in your IdP 
In your identity provider (Okta, Azure AD, Google Workspace, OneLogin, etc.),
create a new SAML 2.0 application. Most providers have a "custom SAML app"
option.
### Get PgBeam's SAML configuration 
Go to **Settings > Security > Configure SSO** in the PgBeam dashboard. You will
see two values to copy into your IdP:

| Field                                    | Description                         |
| ---------------------------------------- | ----------------------------------- |
| **ACS URL** (Assertion Consumer Service) | Where your IdP sends SAML responses |
| **Entity ID** (SP Entity ID)             | PgBeam's SAML identifier            |
### Configure attribute mapping 
Map the following SAML attributes in your IdP. PgBeam uses these to identify
users:

| SAML attribute      | Required | Maps to      |
| ------------------- | -------- | ------------ |
| `email` or `NameID` | Yes      | User email   |
| `firstName`         | No       | Display name |
| `lastName`          | No       | Display name |
### Add IdP metadata to PgBeam 
Copy your IdP's **metadata URL** into PgBeam's SSO configuration page and
save. PgBeam fetches the IdP certificate, SSO URL, and entity ID from this
URL automatically.

If your IdP does not provide a metadata URL, you can paste the metadata XML
directly.
### Test the connection 
Click **Test** in the PgBeam dashboard to verify the SAML flow. This opens a
new window that walks through the full sign-in process. If the test succeeds,
you will see a confirmation with the authenticated user's details.

OIDC setup

### Create an OIDC application in your IdP 
In your identity provider, create a new OpenID Connect (OIDC) application.
Choose "Web Application" as the application type.
### Configure the redirect URI 
Set the **redirect URI** to the value shown in PgBeam's SSO configuration page
(under **Settings > Security > Configure SSO**).
### Add credentials to PgBeam 
Copy the following from your IdP into PgBeam:

| Field             | Where to find it                                                |
| ----------------- | --------------------------------------------------------------- |
| **Client ID**     | Application settings in your IdP                                |
| **Client secret** | Application settings in your IdP                                |
| **Discovery URL** | Usually `https://your-idp.com/.well-known/openid-configuration` |

PgBeam uses the discovery URL to automatically fetch authorization endpoints,
token endpoints, and signing keys.
### Test the connection 
Click **Test** in the PgBeam dashboard to verify the OIDC flow. This redirects
to your IdP for authentication and confirms the user details returned.

Supported identity providers

SSO works with any SAML 2.0 or OIDC-compliant identity provider. Commonly used providers include:

Provider SAML OIDC Notes
Okta Yes Yes Both protocols fully supported
Azure AD / Entra ID Yes Yes Use "Enterprise Application" for SAML
Google Workspace Yes Yes SAML via Admin Console
OneLogin Yes Yes Both protocols fully supported
Auth0 Yes Yes Use "Regular Web Application"
JumpCloud Yes Yes Both protocols fully supported

Just-in-time provisioning

When a user authenticates via SSO for the first time, PgBeam automatically creates an account for them in your organization with the Member role. This means you do not need to invite users individually — anyone who can authenticate through your IdP is automatically provisioned.

Admins and Owners can change a user's role after they have been provisioned.

SSO enforcement

Once SSO is configured and tested, you can enforce it for your organization. Enforcement means:

  • All organization members must authenticate via SSO
  • Password-based login is disabled for the organization
  • Existing sessions are invalidated when enforcement is enabled
  • New invitations require the recipient to sign in via SSO
Organization owners retain the ability to log in with email/password even when SSO enforcement is enabled. This serves as a recovery mechanism in case the IdP is unavailable or misconfigured.

Enable enforcement

Go to Settings > Security in the dashboard. After configuring SSO, toggle Require SSO for all members. Confirm the action — all non-owner members will be signed out immediately.

Troubleshooting

SAML issues

Problem Likely cause Fix
"Invalid ACS URL" error ACS URL mismatch between IdP and PgBeam Copy the exact ACS URL from PgBeam
"Audience mismatch" error Entity ID mismatch Verify SP Entity ID matches in both systems
User lands on error page Attribute mapping missing email Ensure email or NameID is mapped
Certificate validation failed IdP certificate rotated Re-import the metadata URL in PgBeam

OIDC issues

Problem Likely cause Fix
"Invalid redirect URI" Redirect URI mismatch Copy the exact redirect URI from PgBeam
"Invalid client" error Wrong client ID or secret Re-copy credentials from your IdP
Discovery URL fails URL is incorrect or not publicly reachable Verify the URL returns JSON in a browser

General issues

Problem Likely cause Fix
Users can still use passwords SSO enforcement not enabled Toggle "Require SSO" in Security settings
New user gets wrong role Default JIT role is Member Change role after provisioning
IdP is down and nobody can log in SSO enforcement is enabled Owner can log in with email/password and disable enforcement

Further reading