Skip to main content

Configure SAML Single Sign-On (SSO): Site Managers

Information for Site Managers about configuring SAML

Written by Brittany Crow
Updated yesterday

Heads up! This article is intended for Site Managers.

By the end of this article, you will be able to:

  • Configure SAML SSO directly within the platform

  • Connect your Identity Provider (IdP)

  • Test and validate your SSO setup

What Is SAML SSO?

SAML (Security Assertion Markup Language) allows your organization's Identity Provider (IdP)—such as Microsoft Entra ID, Okta, OneLogin, or Google Workspace—to handle user authentication on your behalf.

Once configured:

  • Users click a button on the login page

  • Authenticate with their IdP using existing credentials

  • Are signed in automatically (no separate password required)

Before You Begin

You will need:

  • Administrator access to this platform (Site Admin role)

  • Administrator access to your Identity Provider

  • About 15–20 minutes

You do not need to contact support before starting. The platform generates everything on the Service Provider (SP) side for you.

Navigate to the SAML Configuration Page

  • Log in as a Site Administrator

  • Go to Settings → SAML

Configuration Steps

Initialize Your Configuration

The first time you visit the SAML page, no configuration exists. You must initialize one to generate a Service Provider certificate.

  • Enter a Configuration Name

    • Use default if you have one IdP

    • Use descriptive names (e.g., employees, contractors) for multiple integrations

    • Allowed: lowercase letters, numbers, hyphens, underscores

  • Click Initialize

The platform will:

  • Generate an SP certificate

  • Set default values

  • Display all configuration sections

Multiple configurations

  • Click + Add New to create another configuration

  • Repeat this step with a different name

Copy Your SP Details Into Your IdP

The SP Configuration section contains values your IdP needs:

  • Entity ID — Unique identifier for this platform

  • Metadata URL — Used to automatically import SP settings (including ACS URL)

  • SP Certificate — Public certificate used to verify requests

Best practice

  • Paste the Metadata URL into your IdP’s Import from URL field

Manual setup

  • Open the Metadata URL in your browser

  • Locate the AssertionConsumerService Location (ACS URL)

Import Your IdP Metadata

After configuring your IdP, return here to import metadata.

Option A — Load from URL (recommended)

  • Paste your IdP Metadata URL

  • Click Load

Option B — Upload XML

  • Click Browse

  • Select your metadata XML file

  • Click Load

If recognized (Microsoft, Okta, OneLogin), Claim Mappings will auto-fill.

Save IdP Configuration

Review the populated fields:

  • IdP Entity ID

  • Single Sign-On URL

  • Single Logout URL (if supported)

  • IdP Certificate (x509)

  • Additional Certificates (if provided)

  • IdP Metadata URL

Click Save IdP Configuration

Verify Claim Mappings

SAML claims define how user data is passed.

  • First Name Key — User’s first name

  • Last Name Key — User’s last name

  • Email Key — Must match the user’s account email

  • External ID Key (optional)

If not auto-filled:

  • Enter values manually

  • Confirm with your IdP administrator

Click Save Claim Mappings

General Settings

  • Login Button Label

    • Default: SSO Login

    • Example: Sign in with Contoso

  • Custom Logout Return URL (optional)

  • NameID Format

    • Default works for most IdPs

    • Only change if required

Click Save General Settings

Advanced Settings (Optional)

Most organizations do not need to change these.

Only enable if instructed by your IdP administrator:

  • Strict Mode

  • Want Messages Signed

  • Want Assertions Signed

  • Want Assertions Encrypted

  • AuthnRequests Signed

  • Logout Request / Response Signed

  • Sign Metadata

  • Debug Mode (temporary use only)

Click Save Security Options if changes are made.

Test Your Configuration

  • Open an incognito/private browser

  • Go to your platform login page

  • Click the SSO button

  • Sign in via your IdP

  • Confirm you are logged in

Tip: Test with a non-admin account first.

Managing Multiple Configurations

  • Click + Add New

  • Enter a name and click Initialize

  • Repeat setup steps

Each configuration appears as its own tab.

Deleting a Configuration

  • Scroll to the Danger Zone

  • Click Delete Configuration

Warning:
This action is permanent and will immediately disable SSO for that configuration.

Provider-Specific Instructions

Microsoft Entra ID (Azure Active Directory)

Step A — Create the Enterprise Application

  • Sign in to Azure Portal

  • Go to Microsoft Entra ID

  • Select Enterprise Applications → + New application

  • Click Create your own application

  • Choose Integrate any other application and create

Step B — Configure SAML

  • Go to Single sign-on → SAML

  • Enter:

    • Entity ID

    • ACS URL

  • Or upload Metadata URL

Step C — Get Metadata URL

  • Copy App Federation Metadata URL

  • Paste into platform → click Load

Step D — Assign Users

  • Go to Users and groups

  • Assign access

Claim Keys (auto-filled)

  • First Name → givenname

  • Last Name → surname

  • Email → emailaddress

Okta

Step A — Create App

  • Applications → Create App Integration

  • Select SAML 2.0

Step B — Configure

  • SSO URL = ACS URL

  • Audience URI = Entity ID

Attribute Statements

  • firstName → user.firstName

  • lastName → user.lastName

  • email → user.email

Step C — Metadata URL

  • Copy from Sign On tab

  • Paste into platform

Step D — Assign Users

OneLogin

Step A — Create App

  • Add SAML Custom Connector (Advanced)

Step B — Configure

  • Entity ID

  • ACS URL

Step C — Parameters

  • firstName

  • lastName

  • email

Step D — Metadata

  • Upload XML or paste URL

Step E — Assign Users

Google Workspace

Step A — Create App

  • Add custom SAML app

Step B — Download Metadata

  • Download XML (no persistent URL)

Step C — Configure

  • ACS URL

  • Entity ID

  • Enable signed response

Step D — Attribute Mapping

  • firstName

  • lastName

  • email

Step E — Enable App

Step F — Import Metadata

  • Upload XML into platform

FAQ

Q. The Load button did not populate any fields. What went wrong?
​A. Ensure the metadata URL is publicly accessible or use XML upload.

Q. Users see an error after clicking the SSO button.
​A. Enable Debug Mode temporarily and review logs.

Q. Claim mappings were not auto-filled after importing metadata.
​A. Only Microsoft, Okta, and OneLogin auto-fill. Enter manually for others.

Q. Do I need to re-initialize if my IdP renews its signing certificate?
​A. No. Re-import metadata and save.

Q. What is the difference between the Entity ID and the Metadata URL?
​A. Entity ID = identifier. Metadata URL = full XML configuration.

Q. Can SSO and regular password login coexist?
​A. Yes, unless password login is disabled separately.

Need Help?

Contact support and include:

  • Your Identity Provider

  • The error or behavior

  • When the issue occurs

Security reminder:
Do not share private keys, certificates, or credentials. Only share metadata URLs and claim keys.

Did this answer your question?