Skip to content

Set up SAML#

/// info | Feature availability * Available on Enterprise plans. * You need access to the Ensemble instance owner account to enable and configure SAML

Available from version 0.225.0 onwards. ///

This page tells you how to enable SAML SSO (single sign-on) in Ensemble. It assumes you're familiar with SAML. If you're not, SAML Explained in Plain English can help you understand how SAML works, and its benefits.

Enable SAML#

  1. In Ensemble, go to Settings > SSO.
  2. Make a note of the Ensemble Redirect URL and Entity ID.
    1. Optional: if your IdP allows you to set up SAML from imported metadata, navigate to the Entity ID URL and save the XML.
  3. Set up SAML with your IdP (identity provider). You need the redirect URL and entity ID. You may also need an email address and name for the IdP user.
  4. After completing setup in your IdP, load the metadata XML into Ensemble. You can use a metadata URL or raw XML:
    1. Metadata URL: Copy the metadata URL from your IdP into the Identity Provider Settings field in Ensemble.
    2. Raw XML: Download the metadata XML from your IdP, toggle Identiy Provider Settings to XML, then copy the raw XML into Identity Provider Settings.
  5. Select Save settings.
  6. Select Test settings to check your SAML setup is working.
  7. Set SAML 2.0 to Activated.

Generic IdP setup#

The steps to configure the IdP vary depending on your chosen IdP. These are some common setup tasks:

  • Create an app for Ensemble in your IdP.

  • Map Ensemble attributes to IdP attributes:

    Name Name format Value (IdP side)
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress URI Reference User email
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/firstname URI Reference User First Name
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/lastname URI Reference User Last Name
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn URI Reference User Email

Setup resources for common IdPs#

Documentation links for common IdPs.

IdP Documentation
Authentik Applications and the SAML Provider
Azure AD SAML authentication with Azure Active Directory
Keycloak Choose a Getting Started guide depending on your hosting.
Okta Ensemble provides a Workforce Identity setup guide
PingIdentity PingOne SSO

IdP-specific guidance#

This section contains notes on IdP-specific quirks and tips.

Azure#

The Azure metadata XML is a combination of the SAML 2.0 definition and the WS-Federation definition. This means you can't use the App Federation Metadata Url to automatically load the XML. Instead:

  1. Download the Federation Metadata XML.
  2. Open the file in your text editor.
  3. Remove the RoleDescriptor sections. Anything with the fed: namespace is part of the WS-Federation definition.
  4. Paste the edited XML into Identity Provider Settings in Ensemble's SSO settings.