SAML SSO Setup Guide

SAML (Security Assertion Markup Language) is an industry-standard method that lets your organization's identity provider handle authentication for your Higher Logic Vanilla (Vanilla) community. This means your users sign in once through your company's login system (such as Okta, Azure AD, OneLogin, or PingIdentity) and are automatically signed into your community without entering a separate password.

This is the most common SSO method for enterprise organizations because it integrates with the identity systems most companies already use.

Is SAML right for your community?

SAML is likely the right choice if:

Your organization uses an identity provider like Okta, Azure AD, OneLogin, PingIdentity, or ADFS
You want users to sign in using their existing corporate credentials
Your IT team has mentioned "SAML" or "single sign-on" as your standard
You need to enforce your organization's security policies (password requirements, multi-factor authentication) for community access

If you're unsure which SSO method your organization uses, ask your IT team: "Do we use SAML for single sign-on with third-party applications?"

Before you begin

You'll need to coordinate with your IT team to complete this setup. Here's what to gather before you start.

The IDP Metadata Document

The easiest way to configure SAML is to ask your IT team for their IDP Metadata document (sometimes called "Federation Metadata" or "SAML Metadata XML"). This is a file or URL that contains most of the values you'll need to fill in the SAML settings form, including:

Sign In URL
Entity ID
X.509 Certificate
NameID Format

Ask your IT team: "Can you provide the IDP Metadata document or URL for our SAML integration?"

If your IT team needs your Service Provider Metadata first

Your IT team may ask for your Service Provider (SP) Metadata before they can configure their side. This is common.

To generate your SP Metadata:

Submit the SAML settings form with minimum required values (see Step 3 below).
Once saved, a link to your SP Metadata document will appear in the header section of the SAML Settings page.
Send this link or document to your IT team.

Don't worry about getting everything perfect on the first try — all values can be edited after the initial setup, except for the Connection ID.

What your IT team will provide

If your IT team doesn't have a metadata document, ask them to provide these values individually:

Sign In URL: The URL where users are sent to log in (sometimes called "SSO URL" or "Login URL")
Entity ID: A unique identifier for your identity provider (sometimes called "Issuer")
X.509 Certificate: A security certificate in PEM format (a block of text starting with -----BEGIN CERTIFICATE-----)
NameID Format: The format used to identify users (commonly EmailAddress, Persistent, or Unspecified)

Optional: User attributes to map

By default, your identity provider should send at minimum:

Email address
Display name (or first name and last name)

If your organization wants to pass additional information (like department, job title, or a unique employee ID), let your IT team know which attributes they should include in the SAML assertion. You'll map these in the Vanilla dashboard later.

Step-by-step setup in Vanilla

Step 1: Verify the SAML SSO addon is enabled

Sign in to your Vanilla community as an Administrator.
Access the Dashboard.
Navigate to Settings > Addons.
Look for SAML SSO in the list and make sure it's toggled On.

NOTE: If you don't see the SAML SSO addon, or it's not enabled, contact your Vanilla primary contact or Vanilla Support. The addon needs to be provisioned for your community before you can configure it.

Step 2: Access SAML settings

Access the Dashboard.
Navigate to Settings > SAML SSO.
(or go directly to: https://[your-community-domain]/settings/samlsso)
Click Add Connection to create a new SAML configuration.

Step 3: Configure your connection

You can configure your connection in one of two ways:

Option A: Using the IDP Metadata document (recommended)

If your IT team provided a metadata document or URL, you can use it to auto-populate most fields. Look for an "Import Metadata" option or paste the metadata URL where indicated.

Option B: Manual configuration

Fill in the following fields using the information from your IT team:

Connection ID: Create a short identifier using only letters and numbers (no spaces or special characters). This becomes part of your login URL. Example: "corporatesso" or "okta"

IMPORTANT: The Connection ID cannot be changed after the initial setup. It will appear in the URL of SAML requests. Choose carefully.

Site Name: The name that will appear on the sign-in button. Example: "Sign in with Corporate SSO" or "Company Login."
Sign In URL: Paste the Sign In URL provided by your IT team.
Entity ID: Paste the Entity ID (or Issuer) provided by your IT team.
IDP Certificate: Paste the full X.509 certificate from your IT team, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.
Identifier Format (NameID Format): Select the format provided by your IT team. Common options are EmailAddress, Persistent, or Unspecified. This must match what your identity provider is configured to send.

Step 4: Save and retrieve your SP Metadata

Click Save.
A link to your Service Provider Metadata will now appear in the header section of the SAML Settings page.
If your IT team requested your SP Metadata, send them this link now.
Your IT team may need to complete their configuration before you can test.

Step 5: Configure attribute mapping (if needed)

The SAML SSO Settings Form contains a Profile Fields section for mapping values that will be passed from the IDP to their corresponding values on the Vanilla platform.

If your identity provider uses different names for user attributes, you can map them here. Common mappings include:

Vanilla expects	Your IDP might send
email	emailAddress, mail, Email
name	displayName, fullName, cn
uniqueID	employeeID, uid, userPrincipalName

Your IT team can tell you the exact attribute names they're sending.
Other values that can be mapped are Roles and User Profile fields.

Step 6: Toggle the connection on

Toggle the connection On.
Optionally, check Set as Default if you want this to be the primary sign-in method.

Test your configuration

Test sign-in URL

Once configured, your SAML sign-in URL will be:

https://[your-community-domain]/entry/saml/[connection-id]

For example, if your connection ID is corporatesso:

https://community.yourcompany.com/entry/saml/corporatesso

How to test

Open a private/incognito browser window (to avoid using an existing session).
Navigate to your community.
Click Sign In.
You should see a button with your Site Name (e.g., "Sign in with Corporate SSO").
Click the button — you should be redirected to your identity provider.
Sign in with your corporate credentials.
You should be redirected back to your community and signed in.

What success looks like

You're redirected to your identity provider's login page.
After authenticating, you return to the community signed in.
Your display name and email appear correctly in your profile.

Troubleshooting common issues

"I click Sign In but nothing happens" or the button doesn't appear

The connection may not be fully configured or toggled on. Verify:

The connection is toggled On in the SAML settings
All required fields are filled in (Sign In URL, Entity ID, Certificate)
The Connection ID contains only letters and numbers

"Invalid certificate" or certificate errors

The certificate may not be in the correct format. Verify:

The certificate includes the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines
There are no extra spaces or line breaks
The certificate hasn't expired (ask your IT team to confirm)

"User not found" or attribute errors

The identity provider may be sending attributes with different names than Vanilla expects. Ask your IT team what attribute names they're sending, then update your attribute mapping in the SAML settings.

Users are created but names or emails are wrong

Check your attribute mapping. The attributes being sent may not match what Vanilla is expecting.

"I'm stuck in a redirect loop"

This usually means the sign-in succeeded but something went wrong creating the user session. Contact Vanilla support with details about when this happens.

Information for your IT Team

You can copy this section and send it to your IT team to help them configure your identity provider.

SAML Configuration Request for Vanilla Community

We're setting up SAML single sign-on for our Vanilla community.

Option 1: Send us your IDP Metadata

The easiest way to proceed is to send us your IDP Metadata document or URL. This contains all the information we need to configure our side.

Option 2: If you need our SP Metadata first

If you need our Service Provider Metadata to configure your side, let us know and we'll generate it for you.

Option 3: Manual exchange

If metadata documents aren't available, here's what we need from each other:

What we need from you:

Sign In URL (SSO URL)
Entity ID (Issuer)
X.509 Certificate in PEM format
NameID Format you'll be sending
List of attribute names in the SAML assertion

What you'll need from us (once we complete initial setup):

ACS URL: https://[your-community-domain]/entry/saml
Entity ID / Audience: https://[your-community-domain]
Or we can provide our full SP Metadata document

Attributes we expect:

email: User's email address
name: User's display name (or send firstName and lastName separately)

Optional Attributes (if applicable):

uniqueID: A persistent identifier for the user
photo: URL to user's profile photo
roles: Community roles to assign

Glossary

SAML (Security Assertion Markup Language): An open standard for exchanging authentication data between an identity provider and a service provider.
Identity Provider (IDP): The system that manages user identities and handles authentication. Examples: Okta, Azure AD, OneLogin, PingIdentity.
Service Provider (SP): The application that users want to access. In this case, your Vanilla community.
Entity ID: A unique identifier for either the identity provider or service provider in a SAML configuration.
ACS URL (Assertion Consumer Service): The URL where the identity provider sends the SAML response after authentication.
X.509 Certificate: A digital certificate used to verify the identity of the identity provider and ensure the SAML response hasn't been tampered with.
PEM Format: A text-based format for certificates that begins with -----BEGIN CERTIFICATE----- and ends with -----END CERTIFICATE-----.
NameID: The unique identifier for a user in a SAML assertion, typically an email address or persistent ID.
Just-In-Time (JIT) Provisioning: Automatically creating a user account in Vanilla the first time they sign in via SSO.

Need help?

If you encounter issues not covered here, contact Vanilla support with:

Your community URL
The SSO method you're configuring
A description of what happens when you try to sign in
Any error messages you see