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
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:
- 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.
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:
-
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
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:
- EU - https://yourcompanyname.immersivelabs.online
- US - https://yourcompanyname.us.immersivelabs.com
- UAE - https://yourcompanyname.uae.immersivelabs.com
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
|
|
US Region
|
|
UAE Region
|
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.
Comments
0 comments
Article is closed for comments.