Setting up single sign-on (SSO) | Documentation

Plan: SSO is available on the Agentic plan. If you are on the Team plan and need SSO, contact your account team about upgrading. The rest of this guide assumes Agentic.

Single sign-on lets your organization delegate authentication for Performance Blocks to your existing identity provider (IDP). Once SSO is configured, employees sign in with their corporate identity instead of a per-product password, and your IDP enforces multi-factor authentication, password policy, and account lifecycle.

This article covers the standards Performance Blocks supports, the high-level setup flow, attribute mapping, provisioning options, enforcement, the break-glass account, and the most common failure modes.

What you can connect

Performance Blocks supports two industry-standard SSO protocols.

Protocol	Use it when
SAML 2.0	Your IDP is enterprise-focused (Okta, Azure AD/Entra, Ping, OneLogin, ADFS).
OIDC	Your IDP exposes OpenID Connect (Google Workspace, Auth0, Keycloak).

Both protocols give you the same end-user experience: the user lands on the Performance Blocks sign-in page, clicks the SSO button (or is automatically redirected if SSO is enforced), authenticates with your IDP, and returns to Performance Blocks signed in.

This guide refers to the IDP in generic terms because the exact field names and screen layouts differ between products. Use your IDP's documentation alongside this guide for the literal field labels.

Before you start

You will need:

A user with the org_admin role in Performance Blocks. SSO setup is restricted to administrators.
Administrative access to your IDP, with permission to create a new application and view its metadata.
An email domain (or list of domains) that you control and that all SSO-managed users will sign in from.
A separate break-glass admin account for Performance Blocks that does not sign in via SSO. Create this before you enforce SSO. (See Break-glass admin account below.)

Where SSO is configured

In Performance Blocks, SSO settings live at:

Settings -> Security -> SSO

This page shows your current SSO status (not configured, configured but not enforced, or enforced), the protocol in use, the IDP metadata, and the test sign-in tool.

Step 1 — Create the application in your IDP

In your IDP, create a new application of type SAML 2.0 or OIDC depending on which protocol you are using.

When the IDP asks for the service provider URLs, you will need values from the Performance Blocks SSO settings page. Open Settings -> Security -> SSO in a separate tab and copy:

Entity ID (sometimes called Audience or SP Identifier)
ACS URL (sometimes called Reply URL, Single Sign-On URL, or Callback URL)
Sign-in URL (sometimes called Initiator URL, used for IDP-initiated sign-in)

Paste each into the matching field in your IDP. Do not change the values — they are tenant-specific and must match exactly.

For OIDC, the matching pieces are:

Redirect URI (paste from Performance Blocks)
Logout URI (optional, for federated logout)
The IDP will generate a Client ID and Client Secret that you will paste back into Performance Blocks in Step 3.

Step 2 — Configure attribute mapping in your IDP

Performance Blocks needs at least the user's email address. The other attributes are optional but recommended because they allow the directory to populate cleanly when a new user signs in for the first time.

Performance Blocks attribute	IDP claim (typical SAML)	IDP claim (typical OIDC)
Email (required)	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` or `email`	`email`
First name	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` or `givenName`	`given_name`
Last name	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` or `surname`	`family_name`
Display name	`displayName`	`name`
Department	`department`	`department`
Job title	`title`	`title`
External ID	`nameID` (with format `persistent`)	`sub`
Roles	`roles` (multi-value) — see Mapping roles	`roles`

The exact claim names depend on your IDP. The important thing is that the values arrive in the assertion under the names you tell Performance Blocks to look for in Step 4.

Step 3 — Paste IDP metadata into Performance Blocks

Back in Performance Blocks, on Settings -> Security -> SSO:

Choose the protocol (SAML or OIDC).
Paste the IDP metadata. For SAML, this is the IDP metadata XML — most IDPs let you download it as a file or expose it as a URL. For OIDC, paste the issuer URL, the client ID, and the client secret.
Save.

Performance Blocks parses the metadata and shows the resolved values (issuer, signing certificate fingerprint, single sign-on URL). Confirm the values match what your IDP shows.

Step 4 — Map attributes to Performance Blocks fields

Below the metadata block on the SSO settings page is the Attribute mapping section. For each Performance Blocks attribute (email, first name, last name, etc.), specify the claim name your IDP sends.

Save the mapping. Performance Blocks will use it for every SSO sign-in from this point on, both for new and existing users.

What "metadata" means in practice

If you have not configured SAML before: the IDP metadata is an XML document that describes how Performance Blocks should talk to your IDP. It contains the issuer URL, the public part of the IDP's signing certificate, the URL to redirect users to for sign-in, and the supported bindings. Most IDPs publish it at a static URL or let you download it from the application's settings page; both work.

For OIDC, the equivalent is the issuer's discovery document at <issuer>/.well-known/openid-configuration. Performance Blocks reads that document at configuration time and again periodically so that key rotations in your IDP do not require re-pasting on your side.

Step 5 — Test the connection

The SSO settings page has a Test sign-in button. Use it before enforcing SSO.

Click Test sign-in. A new tab opens.
Sign in to your IDP if you are not already signed in.
The tab returns to Performance Blocks and shows a result panel: claims received, attributes mapped, the user record that was matched (or that would be created).

If the test succeeds and the resolved attributes look right, you are ready to invite users or to enforce SSO. If it fails, see Troubleshooting.

Provisioning models

There are two ways for users to end up in Performance Blocks once SSO is configured.

Just-in-time (JIT) provisioning

The default. The first time a user signs in via SSO with an email address from an allowed domain, Performance Blocks creates the user record automatically using the attributes from the assertion. The user lands on the welcome screen and can begin using the product immediately.

JIT is the right choice if:

Your directory grows organically and you do not want to pre-populate it.
You enforce role assignment from the IDP (so the role is set correctly on first sign-in).
You do not need to assign managers or org-specific metadata before the user arrives.

Pre-provisioning (invite first)

You invite users from Performance Blocks first (Settings -> Members) and then have them sign in via SSO. The invite reserves their record and lets you set role, manager, and team membership before the user ever logs in.

Pre-provisioning is the right choice if:

You want to assign managers and roles in advance.
Your IDP does not send a roles claim and you assign roles in Performance Blocks.
You are migrating an existing org and want to map who reports to whom before turning on SSO.

You can mix the two: pre-provision your administrators and managers, then let everyone else arrive via JIT.

SCIM provisioning

For larger organizations that need automatic deprovisioning and group sync from the IDP, SCIM 2.0 provisioning is supported. SCIM lets your IDP push directory changes (create, update, deactivate, group membership) to Performance Blocks without anyone signing in to trigger them.

To enable SCIM, contact your account team to have the SCIM endpoint provisioned for your tenant. They will return:

The SCIM base URL (tenant-specific).
A bearer token used by the IDP to authenticate.

You then configure your IDP's SCIM client with those values and pick which directory groups to sync. Group-to-role mapping is configured in Performance Blocks under Settings -> Security -> SSO -> SCIM.

Mapping IDP attributes to roles

Performance Blocks roles are employee, manager, and org_admin. There are two ways to set them via SSO.

Via a role claim

If your IDP sends a multi-value roles (or similar) claim in the assertion, map it under attribute mapping. Performance Blocks will trust the assertion and set the user's roles on every sign-in.

This is the cleanest model when your IDP is the source of truth for role membership (for example, you have an Okta group called perfblocks-admins and you map group membership to the org_admin role).

Via Performance Blocks (manual)

If your IDP does not send a roles claim, leave the role mapping blank. Performance Blocks will assign new SSO users the employee role by default, and an org admin can promote them in the directory afterward.

You can also choose a hybrid model: trust the IDP for org_admin (so admins are gated by your IDP groups) and let managers be promoted manually inside Performance Blocks.

Enforcing SSO

By default, configuring SSO does not prevent users from signing in with email and password. Both work in parallel during the rollout phase. Once you are ready to make SSO the only way in:

Go to Settings -> Security -> SSO.
Toggle Enforce SSO on.
Specify the allowed email domains. Any sign-in attempt with an email at one of these domains will be redirected to your IDP. Sign-ins with email and password will be rejected for these domains.
Confirm.

Once enforced:

New invitations sent to allowed domains only allow SSO sign-up.
Existing password sessions for users with allowed-domain emails are revoked.
Password reset is disabled for those users (they reset in the IDP instead).

You can change the list of enforced domains or turn enforcement off again at any time as long as you can sign in.

Break-glass admin account

If your IDP is unreachable or misconfigured, you must still be able to sign in to Performance Blocks to fix it. That is the purpose of the break-glass admin account.

Recommended setup

Create a dedicated administrator account using a non-corporate email address that is not in the list of SSO-enforced domains. A shared mailbox owned by IT (e.g. it-emergency@your-company.com aliased outside the enforced domain, or a vendor-managed email) is appropriate.
Give that account the org_admin role and 2FA.
Store its credentials in your shared password manager with documented break-glass procedure.
Do not add its email domain to the SSO enforcement list.
Test the break-glass sign-in once a quarter and rotate its password and 2FA backup codes after each test.

When to use it

Only when SSO is broken (IDP outage, certificate rollover gone wrong, misconfigured attribute mapping). Routine administration should still happen through your normal SSO-backed admin account so the audit log reflects the real actor.

Audit trail of role changes

Whether roles are set by a claim or assigned manually, every role change is recorded in the audit log. Filter by actor to see who promoted whom, or by target to see the role history of a single user. If a role claim from your IDP changes a user's roles, the audit entry shows the actor as system:sso along with the assertion id so you can correlate back to your IDP's logs.

Federated logout

Performance Blocks does not currently propagate logout from your IDP to active Performance Blocks sessions. If a user is signed out in the IDP, their existing Performance Blocks session continues until it expires or until an admin revokes it.

If you require strict session revocation (for example after offboarding), you have two options:

Use SCIM to deactivate the user. Deactivation revokes all sessions immediately.
Manually revoke the session from Settings -> Members -> [user] -> Revoke sessions.

Troubleshooting

"Email not in an allowed domain"

The user's email is not in the SSO enforcement list. Either add the domain to the list or pre-provision the user in the directory before they sign in.

"No user found and JIT provisioning is disabled"

JIT is off (you are running pre-provisioning only). Invite the user first, then have them sign in.

"Signature validation failed" or "Invalid assertion"

The signing certificate Performance Blocks has on file does not match the one your IDP is using. This is usually caused by a certificate rotation. Re-paste the IDP metadata in Settings -> Security -> SSO and save.

Attribute mapping shows the wrong value

Use the test sign-in tool. The result panel shows the raw claims received and how each one mapped. If the claim name your IDP is sending differs from what you have in the mapping, fix the mapping.

If you are mapping roles via a claim, verify the claim is being sent (test sign-in) and that the value contains one of employee, manager, org_admin. If not, either correct the IDP claim or remove the role mapping and assign roles inside Performance Blocks.

Loop: IDP returns the user, Performance Blocks redirects back to IDP

This usually means the assertion is being received but does not contain the email claim under the expected name. Open the test sign-in result panel and confirm the email claim resolves.

SCIM provisioning is failing

SCIM errors are returned to the IDP and visible in the IDP's provisioning logs. If you do not see what is wrong, contact your account team — they can pull the SCIM request log on their side.

Rolling out SSO without disruption

A staged rollout reduces the chance that someone is locked out at the wrong moment.

Phase 1 — Pilot

Configure SSO end to end and test sign-in successfully.
Invite or pre-provision two or three pilot users (typically the IT team plus one organization administrator).
Have the pilots sign in via SSO over the course of a week. They keep their existing password sign-in as a safety net.
Inspect the audit log to confirm SSO events are recorded with the right actor.

Phase 2 — Opt-in for the wider team

Email everyone in the organization explaining what is changing, when, and what they need to do.
Encourage members to sign in via SSO at least once before enforcement so any directory mismatches surface early (typo in email, wrong department).
Use Settings -> Members to spot anyone with a bounced email or who has not signed in recently and chase them directly.

Phase 3 — Enforce

Confirm the break-glass admin account works and its credentials are stored.
Toggle enforcement on for the relevant email domains.
Watch the audit log and the support inbox for the next 24 hours. Most issues surface within the first day.

Phase 4 — Decommission passwords

After two to four weeks of clean enforcement, reset stored passwords for SSO users so the password fallback cannot be triggered later. Use Settings -> Members -> [user] -> Reset password to invalidate.

When to roll back

If a problem surfaces after enforcement (a large group of members suddenly cannot sign in, an attribute claim broke), rolling back to password sign-in is fast:

Sign in with the break-glass admin account.
Settings -> Security -> SSO -> Toggle Enforce SSO off.
Members can sign in with their existing passwords (or via Forgot password? if they no longer remember the password).
Investigate and fix the SSO issue offline. Re-enable enforcement when ready.

The audit log records both the disable and re-enable events, so you have a clear timeline of when password fallback was active.

Maintenance

Certificate rotation

SAML signing certificates have a finite lifetime. Most IDPs will warn you 30 days before expiry. When you rotate the certificate in your IDP, re-paste the IDP metadata in Performance Blocks (Settings -> Security -> SSO -> Update metadata) within the rotation window so signed assertions continue to validate.

A failed certificate validation results in 401-style errors at sign-in. The audit log records the rejected assertion with reason "signature validation failed."

Adding domains

If your organization acquires another company or adds a new email domain, add it to the allowed email domains list and (if you enforce) the enforced domains list under Settings -> Security -> SSO. Existing users continue to work; new users at the new domain will be routed through SSO from then on.

Removing a domain

Removing a domain from the enforced list does not delete users at that domain — they remain in the directory and continue to sign in via SSO. To stop those users entirely, deactivate them through Settings -> Members or via SCIM deprovisioning.