Skip to main content

SSO/SAML Setup

Control Zero supports SAML 2.0 Single Sign-On for Teams-tier organizations. This guide covers setup for the four supported identity providers plus general SAML configuration.

Prerequisites​

  • A Control Zero organization on the Teams tier
  • Organization owner role (only owners can manage SSO)
  • Admin access to your identity provider (IdP)

Supported Identity Providers​

IdPStatusSCIM Provisioning
OktaSupportedSupported
Azure AD (Entra ID)SupportedSupported
Google WorkspaceSupportedNot available
OneLoginSupportedSupported

General Setup Flow​

  1. In Control Zero, go to Settings > SSO
  2. Copy the Entity ID and ACS URL shown on the page
  3. Create a SAML application in your IdP using these values
  4. Copy the IdP's metadata URL back to Control Zero
  5. Click Test Connection to auto-populate the IdP entity ID and SSO URL
  6. Paste the IdP signing certificate (PEM format)
  7. Choose a default role for new SSO users
  8. Click Enable SSO

Okta​

Step 1: Create a SAML App in Okta​

  1. In Okta Admin Console, go to Applications > Create App Integration
  2. Select SAML 2.0 and click Next
  3. Enter the app name: Control Zero
  4. For Single sign-on URL, paste the ACS URL from the Control Zero SSO page
  5. For Audience URI (SP Entity ID), paste the Entity ID from the Control Zero SSO page
  6. Set Name ID format to EmailAddress
  7. Under Attribute Statements, add:
    • Name: email, Value: user.email
    • Name: groups, Value: user.groups (for role mapping)
  8. Click Next, then Finish

Step 2: Get the IdP Metadata​

  1. On the app's Sign On tab, find the Metadata URL link
  2. Copy this URL
  3. In Control Zero SSO settings, paste it into IdP Metadata URL and click Test Connection

Step 3: Download the Certificate​

  1. On the app's Sign On tab, click View SAML setup instructions
  2. Copy the X.509 Certificate (the full PEM block including BEGIN/END lines)
  3. Paste into the IdP Certificate field in Control Zero

Azure AD (Entra ID)​

Step 1: Register a SAML Application​

  1. In Azure Portal, go to Enterprise Applications > New application > Create your own application
  2. Name it Control Zero and select Integrate any other application (Non-gallery)
  3. Go to Single sign-on > SAML
  4. Under Basic SAML Configuration:
    • Identifier (Entity ID): paste the Entity ID from Control Zero
    • Reply URL (ACS URL): paste the ACS URL from Control Zero
  5. Under User Attributes & Claims, ensure emailaddress claim maps to user.mail

Step 2: Get the Federation Metadata​

  1. Under SAML Certificates, copy the App Federation Metadata URL
  2. Paste into Control Zero and click Test Connection

Step 3: Download the Certificate​

  1. Under SAML Certificates, download Certificate (Base64)
  2. Open the downloaded file and copy the entire PEM content
  3. Paste into Control Zero's IdP Certificate field

Google Workspace​

Step 1: Create a SAML App​

  1. In Google Admin Console, go to Apps > Web and mobile apps > Add App > Add custom SAML app
  2. Enter Control Zero as the app name
  3. On the Google Identity Provider details page, download the Certificate and copy the SSO URL
  4. On Service provider details:
    • ACS URL: paste the ACS URL from Control Zero
    • Entity ID: paste the Entity ID from Control Zero
    • Name ID format: EMAIL
  5. Under Attribute mapping, add groups mapped to the desired Google Groups attribute

Step 2: Configure Control Zero​

  1. Paste the SSO URL as the IdP SSO URL
  2. Paste the downloaded certificate as the IdP Certificate
  3. Set the IdP Entity ID to https://accounts.google.com/o/saml2?idpid=YOUR_IDP_ID

OneLogin​

Step 1: Create a SAML Connector​

  1. In OneLogin Admin, go to Applications > Add App
  2. Search for SAML Custom Connector (Advanced)
  3. Under Configuration:
    • Audience (EntityID): paste Entity ID from Control Zero
    • ACS (Consumer) URL: paste ACS URL from Control Zero
    • SAML nameID format: Email

Step 2: Get the Metadata​

  1. Under SSO, copy the Issuer URL (this is the metadata URL)
  2. Paste into Control Zero and click Test Connection

Step 3: Download the Certificate​

  1. Under SSO, click View Details next to the X.509 Certificate
  2. Copy the full PEM block and paste into Control Zero

SCIM Provisioning​

For IdPs that support SCIM (Okta, Azure AD, OneLogin), Control Zero supports automatic user provisioning and deprovisioning.

Enable SCIM​

  1. In the SSO settings, check Rotate SCIM Token when saving the SSO configuration
  2. The SCIM token will be displayed exactly once -- copy it immediately
  3. The SCIM Base URL is: https://api.controlzero.ai/scim/v2
  4. Configure your IdP's SCIM integration with these values

SCIM Operations Supported​

OperationStatus
Create UserSupported
Update UserSupported (PATCH)
Deactivate UserSupported
List UsersSupported
Get UserSupported

Role Mapping​

Control Zero maps IdP group attributes to roles:

IdP Group (contains)Control Zero Role
ownerOwner
adminAdmin
billingBilling Admin
developer or engineerDeveloper
viewer or readViewer

If no group mapping matches, the default role configured in SSO settings is used.

Enforce SSO​

When Enforce SSO is enabled:

  • All org members must sign in through the IdP
  • Password and social sign-in are disabled for the org
  • Existing sessions continue until they expire
  • The org owner can still disable SSO from the dashboard (as a safety valve)

Troubleshooting​

"SAMLResponse signature verification failed"​

  • Ensure the certificate in Control Zero matches the one from your IdP
  • Check that the IdP is signing the assertion (not just the response)
  • Regenerate the certificate in your IdP and update it in Control Zero

"SAMLResponse expired (NotOnOrAfter)"​

  • Check that the server clocks on your IdP and the user's machine are synchronized
  • The default validity window is 5 minutes; adjust in your IdP if needed

"SAML not configured for this org"​

  • Ensure you saved the SSO configuration in Control Zero
  • Verify the org ID in the login URL matches your organization

"idp_sso_url must be https"​

  • Control Zero requires all IdP URLs to use HTTPS
  • If your IdP is behind a proxy, ensure the proxy terminates TLS

Users are assigned the wrong role​

  • Check the Attribute Statements in your IdP to ensure the groups attribute is sent
  • Verify the group names contain the expected keywords (see Role Mapping above)
  • The default role applies when no group mapping matches