Guides

SAML Configuration for Single Sign-On (SSO) Across Multiple Workspaces

This document provides a comprehensive guide for setting up Single Sign-On (SSO) across multiple teams in V7 using SAML. It includes the steps for configuring SSO, a SAML metadata template, and an example SAML response.

Suggest Edits

Overview

V7 supports SAML 2.0 for enabling SSO. This allows customers to control access to V7 teams and assign roles automatically based on team membership.

For multi-team setups:

  • The groups attribute is used to specify the team slugs a user has access to. This attribute name can be different.
  • Team slugs can optionally include prefixes and/or suffixes to distinguish them from other group entries in the payload.
  • Only the parent/root team should have an SSO setup; child teams rely on the parent team's configuration.

Setting Up SSO for Multiple Workspaces

  1. Create a SAML Application:
    • Configure the parent team (root workspace) as an application in your Identity Provider (IdP).
    • Use the following mandatory parameters:
      • Entity ID: https://darwin.v7labs.com
      • Assertion Consumer Service (ACS) URL: https://darwin.v7labs.com/api/users/authenticate/sso/saml/validate
  2. Configure Attributes and Claims:
    • The following attributes must be configured in your IdP:
      • Given Name: Maps to the user's first name.
        • Azure AD: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
        • Okta: user.firstName
      • Surname: Maps to the user's last name.
        • Azure AD: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
        • Okta: user.lastName
      • Email: Maps to the user's email address.
        • user.mail
      • Groups: Maps to an array of team slugs the user has access to.
        • Azure AD/Okta: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
    • Prefixes and/or suffixes may be added to group values to identify V7-specific team slugs (e.g. in the example SAML below ALL-365-G-APP_DarwinV7_).
  3. Share Metadata with V7:
    • After configuring the application, you have to communicate to the V7 team:
      • The name of the groups attribute (often Groups as above, but can be custom)
      • The prefix (if any). In the example below ALL-365-G-APP_DarwinV7_
      • The suffix (if any). Not present in the example below.
    • Once the V7 team confirms that this custom configuration has been updated for your team, download the SAML metadata file and upload it to V7 under Team Settings > Configure SSO.
  4. Testing:
    • Test with users from both parent and child teams to ensure they have appropriate access.

📘

Testing

We recommend that steps 3 and 4 are executed with the assistance of the V7 team to avoid any unwanted lockout of users during this procedure.

SAML Metadata Template

The following template should be customized to match your SAML configuration:

<md:EntityDescriptor ID="{{unique_id}}" cacheDuration="PT1440M" entityID="https://darwin.v7labs.com"
  xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
  <md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"
    WantAuthnRequestsSigned="false">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>
            {{x509_certificate}} <!-- Replace with your X.509 certificate -->
          </ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
      Location="https://darwin.v7labs.com/api/users/authenticate/sso/saml/validate" />
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
      Location="https://darwin.v7labs.com/api/users/authenticate/sso/saml/validate" />
    <saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
        NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
        xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" />
    <saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
        NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
        xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" />
    <saml:Attribute Name="user.mail"
        NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
        xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" />
    <saml:Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"
        NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
        xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
      <!-- This groups claim is only mandatory to configure SSO across V7 workspaces -->
    </saml:Attribute>
  </md:IDPSSODescriptor>
  <md:ContactPerson contactType="technical">
    <md:Company>{{company_name}}</md:Company>
    <md:GivenName>{{contact_name}}</md:GivenName>
    <md:EmailAddress>{{contact_email}}</md:EmailAddress>
  </md:ContactPerson>
</md:EntityDescriptor>

Example SAML Token Response

Here’s an example SAML response that matches the above metadata configuration:

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    Destination="https://darwin.v7labs.com/api/users/authenticate/sso/saml/validate"
    ID="_123456789abcdef"
    IssueInstant="2024-12-06T12:00:00Z"
    Version="2.0">
  <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">https://idp.example.com</saml:Issuer>
  <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
      ID="_abcdef123456789"
      IssueInstant="2024-12-06T12:00:00Z"
      Version="2.0">
    <saml:Subject>
      <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">[email protected]</saml:NameID>
    </saml:Subject>
    <saml:AttributeStatement>
      <saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname">
        <saml:AttributeValue>John</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname">
        <saml:AttributeValue>Doe</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="user.mail">
        <saml:AttributeValue>[email protected]</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/groups">
        <saml:AttributeValue>ALL-365-G-APP_DarwinV7_Team1</saml:AttributeValue>
        <saml:AttributeValue>ALL-365-G-APP_DarwinV7_Team2</saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

Updated 12 days ago