Skip to main content

Single Sign On (SSO) Setup Guide

Immersive
Updated

This document outlines the steps required to set up a SAML SSO integration between your IdP and the Immersive platform. We have simplified the process to help you get access to the platform using your SSO IP for authentication.

 

This process consists of the following steps:

  1. Add Immersive to your IdP

  2. Immersive Metadata

  3. Configuring SAML in your IdP

  4. Attribute Mapping

  5. Download your Metadata and send to us

  6. Your SSO Enabled Landing Page

  7. Customized Landing Page (optional)

     

 

1. Add Immersive to your IdP

To begin implementing SSO, as the customer, you must first set up your side of the integration through your Identity Provider (IdP).

All IdPs are slightly different in their interface, but the basics are all the same (just with potentially different names). 

To begin, you will need to open your IdP and under create Immersive as a new SAML application.

Here are some examples of a couple of popular IdPs and how that looks in each one:

AZURE

Go to Azure Active Directory > Enterprise Applications > + New Application > SAML

OKTA

Go to Applications > Applications > Add Application > Create New App > SAML 2.0

 

2. Immersive Metadata

The Immersive platform is hosted in AWS, and when you begin your subscription with Immersive, your data center region is auto-provisioned based on your geographic region. This will be one of the following regions:

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

The Immersive metadata (links to view this below) contains all the technical details you need to integrate with Immersive, and is fully dependent on which region you have been provisioned, so it is important that you select the correct Immersive SAML Configuration below corresponding to your data center region:

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

 

3. Configuring SAML in your IdP

Our SAML Configuration information can be found below, and this again can appear as slightly different names/fields within your IdP, depending on which one you have.

Once again, this information must match the region your data is hosted in, otherwise the connection will not work.

Here are some examples of a couple of popular IdPs and how that looks in each one:

AZURE

Basic SAML Configuration:

OKTA

SAML Settings:

 

4. Attribute Mapping

Also known as Attributes & Claims, or Attribute Statements, you will need to add at least the mandatory two attributes in order for the connection to work.

We require you to set up one attribute for EMAIL, and one attribute for UNIQUE IDENTIFIER or UID. 

For the UID, the value of this attribute you send can be anything that is unique and unchanging for a user, so select a value that makes the most sense from your IdP, a couple of examples from different IdPs are:

  • user.mail
  • user.userprincipalname

Once you have selected the values, you MUST add the attribute using the following naming format, otherwise, the connection will not work.

For the name (not the value) of the EMAIL attribute, you must name it exactly as follows:

  • urn:mace:dir:attribute-def:email

For the name (not the value) of the UNIQUE IDENTIFIER attribute, you must name it exactly as follows:

  • urn:mace:dir:attribute-def:uid

So once these attributes are set up you should have something that looks similar to this:

Attribute Name Attribute Value
urn:mace:dir:attribute-def:email user.email
urn:mace:dir:attribute-def:uid user.userprincipalname

 

We also have two optional attributes that you can add for a user’s first name and last name. If you choose to use either or both of these attributes, the names must be formatted exactly as follows, and for the value, choose whatever is appropriate from your IdP:

Attribute Name Attribute Value
urn:mace:dir:attribute-def:first-name user.firstname
urn:mace:dir:attribute-def:last-name user.lastname

 

If you require Team Mapping, we do offer an additional attribute that can be included. Please refer to the Team Mapping article.

 

5. Download your Metadata and send to us

Once you have completed all necessary sections of the SAML integration, you will then be given the option to download the metadata file from your IdP.

Download and save this metadata file as an .xml file (if possible) and share it with the Immersive Customer Support Team at support@immersivelabs.com. 

Once we receive, this, we will then be able to complete the setup of the SSO integration on our side.

 

6. Your SSO Enabled Landing Page

As part of the integration, we will create you a bespoke landing page, that must be used in order to utilize SSO access. Depending on your data region, your new landing page will be a version of one of the following URLs:

Once the SSO integration has been completed, we will give you the green-light to test out your new landing page.

 

Important! Before testing your landing page, we strongly recommend that you add these new URLs to your allow list, depending on your region:

EU Region

  • yourcompanyname.immersivelabs.online
  • yourcompanyname.api.immersivelabs.online
  •  

US Region

  • yourcompanyname.us.immersivelabs.com
  • yourcompanyname.api.us.immersivelabs.com

 
 

UAE Region

  • yourcompanyname.uae.immersivelabs.com
  • yourcompanyname.api.uae.immersivelabs.com

 

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.

 

7. Customized Landing Page (Optional feature)

If you would like to have a customized landing page, this can be done by sending the Immersive Customer Support Team the following information to support@immersivelabs.com:

  • Background image (Max File Size: 1MB)
  • Company logo (Max file size: 512kb)
  • Text to be included on landing page

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

 

 

Related articles

Comments

0 comments

Article is closed for comments.