Single Sign On (SSO) Setup Guide

This guide covers how to set up a SAML SSO integration between your identity provider and the Immersive platform, including the optional SSO team mapping configuration.

Step 1 – Add Immersive to your IdP

To start implementing SSO, set up your side of the integration through your IdP. All IdPs differ slightly in their interface, but the basics are the same — open your IdP and create Immersive as a new SAML application.

• Azure: Go to Azure Active Directory > Enterprise Applications > + New Application > SAML
• Okta: Go to Applications > Applications > Add Application > Create New App > SAML 2.0

Step 2 – Immersive metadata

The Immersive platform is hosted in AWS, and your data center region is auto-provisioned based on your geographic region — one of:

• EU (Ireland eu-west-1)
• US (us-east-1)
• UAE (me-central-1)

The Immersive metadata contains all the technical details you need. Select the metadata link for your region:

• EU Region Metadata -  https://api.immersivelabs.online/saml
• US Region Metadata - https://api.us.immersivelabs.com/saml
• UAE Region Metadata - https://api.uae.immersivelabs.com/saml

If you are unsure which region to choose, please verify this with your Customer Success Manager.

Step 3 – Configure SAML in your IdP

The SAML configuration values below may appear with slightly different field names in your IdP. The values must match the region your data is hosted in.

AZURE - Basic SAML Configuration:

• Identifier (Entity ID):
  • EU = https://api.immersivelabs.online/saml
  • US = https://api.us.immersivelabs.com/saml
  • UAE = https://api.uae.immersivelabs.com/saml
• Reply URL (Assertion Consumer Service URL):
  • EU = https://api.immersivelabs.online/accounts/saml/auth
  • US = https://api.us.immersivelabs.com/accounts/saml/auth
  • UAE = https://api.uae.immersivelabs.com/accounts/saml/auth

OKTA - SAML Settings:

• Single sign on URL:
  • EU = https://api.immersivelabs.online/accounts/saml/auth
  • US = https://api.us.immersivelabs.com/accounts/saml/auth
  • UAE = https://api.uae.immersivelabs.com/accounts/saml/auth
• Tick the box ‘Use this for Recipient URL and Destination URL’
• Audience URL SP entity ID:
  • EU = https://api.immersivelabs.online/saml
  • US = https://api.us.immersivelabs.com/saml
  • UAE = https://api.uae.immersivelabs.com/saml

Step 4 – Attribute mapping

Also known as Attributes and Claims, or Attribute Statements, you'll need to add at least two mandatory attributes for the connection to work: EMAIL and UNIQUE IDENTIFIER (UID).

For the UID, the value can be anything unique and unchanging for a user — for example: user.mail or user.userprincipalname.

The attribute names must be formatted exactly as follows:

• Email attribute name: urn:mace:dir:attribute-def:email
• UID attribute name: urn:mace:dir:attribute-def:uid

Example mapping:

Two optional attributes for first name and last name:

If you need Team Mapping, see the Team Mapping section below.

Step 5 – Download metadata and send to us

Once you've completed all sections of the SAML integration, download the metadata file from your IdP. Save it as an .xml file (if possible) and send it to the Immersive Customer Support Team at support@immersivelabs.com. Once we receive it, we'll complete the SSO setup on our side.

Step 6 – Your SSO landing page

As part of the integration, we'll create a bespoke landing page for you. Depending on your data region:

• EU: https://yourcompanyname.immersivelabs.online
• US: https://yourcompanyname.us.immersivelabs.com
• UAE: https://yourcompanyname.uae.immersivelabs.com

Once the SSO integration is complete, we'll let you know when you can test your new landing page.

Before testing, add these URLs to your allowlist:

When testing the new SSO landing page, click on the blue ‘Sign in with single sign on’ button, and on your first time you will be re-directed to your IdP to log in. After this, unless you are signed out for any reason, clicking this button should take you directly to the main dashboard.

Step 7 – Customized landing page (optional)

To get a customized landing page, send the following to support@immersivelabs.com:

• Background image (max file size: 1 MB)
• Company logo (max file size: 512 KB)
• Text to include on the landing page

For additional information regarding SSO, please refer to the SSO FAQ.

Team mapping (optional)

Team Mapping lets you manage your organization's teams from within your IdP. Users are assigned to a team automatically when they first register or sign in to the platform.

To set up Team Mapping, we need:

• The groups to be configured by your Integrations Team
• The 'team_title' attribute set up, as described below
• The values you've assigned to each group and the corresponding Immersive team you want them mapped to

If you'd like different teams to have different licenses, let us know which license each team should have. As users register or move into a different team, they'll be assigned the associated license.

The team_title attribute

The 'team-title' attribute tells us which IdP group a user belongs to. Since users can be in multiple teams, we accept multiple values for this attribute.

The attribute must be named exactly as follows: urn:mace:dir:attribute-def:team-title

Share the values you've chosen for each group and the corresponding Immersive team. Example:

Nested teams

Document and share the Prefix and Delimiter you'll use in the claim/attribute value for nested teams.

Example — where the prefix is {PREFIX} and the delimiter is /: {PREFIX}team_1/Sub_team_1

Configuration options

We can configure SSO team mapping to meet your specific requirements. Two options: