Configure Spotnana Single Sign-on (SSO) for your identity provider

TABLE OF CONTENTS

• Configure Spotnana Single Sign-on (SSO) for your identity provider
  • Introduction
  • Prerequisites
    • SAML
    • OpenID Connect
    • Google Standard
  • Configuration steps in the Spotnana Online Booking Tool
    • SAML
    • OpenID Connect
    • Google’s Standard
  • Testing 
    • General troubleshooting
    • Issues with Microsoft Entra configurations
      • Error when sign-on URL is incorrectly configured
      • Set the sign-on URL for OpenID Connect SSO
      • Email attribute is set incorrectly
  • Caveats
    • SAML
    • OpenID Connect
  • Related Topics

Introduction

These instructions explain how to configure Spotnana to connect to your Identity Provider (IdP) to support Single Sign-on (SSO). Once configured, your users will no longer need to enter a Spotnana-specific user ID and password and will instead use SSO to access Spotnana. To configure Spotnana to support SSO, there are some steps that must be completed (one time only). The steps are organized into 3 sections:

• Prerequisite tasks - Specific instructions on the information you need to gather from your IdP in advance. There are separate sections for SAML, OpenID Connect, and Standard (Google only).

• Configuration steps in the Spotana Online Booking Tool (OBT) - Specific instructions on how to configure the Spotnana connection to your IdP. There are separate sections for SAML, OpenID Connect, and Standard (Google only)

• Testing - Specific instructions on how to test your connection between Spotnana and your IdP and ensure the configuration is working properly.

Prerequisites

SAML

Your metadata will be provided either as a text input from an XML document or as a URL that designates the location where your metadata file is hosted. Have these ready before you start. 

• If using a metadata XML, you will provide us with the SAML XML metadata and the SAML email attribute during the configuration process in the OBT (using the Enter your company's information screen). The email attribute should correspond to the user’s email address.

• If using a metadata document URL, you will provide us with the Endpoint URL where your metadata document is hosted and the SAML email attribute during the configuration process in the OBT (using the Enter your company's information screen). This email attribute should correspond to the user’s email address.

OpenID Connect

You must provide Spotnana with the following information.

• Client ID - Your identity provider’s public identifier for your account.

• Client Secret - A private key only known to your identity provider that is unique to your account and used to authenticate users.

• Attribute request method (either GET or POST) - The HTTP method used to fetch the user details.

• Issuer URL - The URL used to receive authentication requests.

• OpenID connect email attribute - The attribute used to identify individual users. This attribute should correspond to the user’s email address.

Google Standard

There are no prerequisites for this configuration option.

Configuration steps in the Spotnana Online Booking Tool

SAML

To begin configuring your SSO connection, log into the OBT, select Company from the Program menu, expand the Configuration menu (on the left) and select Integrations. Then select the SSO tab and click Connect next to the SAML option. 

1. The Configuring SAML in your IdP screen will appear. This screen supplies you with two values, ACS/Reply URL and Entity ID, that can be used to configure your IdP to accept requests from and send responses to us. Use the copy button to copy each of these values into your clipboard and paste them into the corresponding field in your IdP. Once you have done that and saved the values in your IdP, click Next. The Select SAML source screen will appear.  

2. Specify the source of your SAML metadata document. Select either Metadata XML or Metadata document endpoint URL. 

   1. If you selected Metadata XML:

      • You will be prompted to provide the XML data from your IdP. Copy and paste the XML data into the dialog box.

        • Note: Be sure to include the following in your XML:

          <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="yourIdPSAMLredirectURL"/>

          If you are unable to edit your XML directly, be sure to set your IdP to Require IDP Redirect URL.

      • Enter your SAML email attribute when prompted and click Connect. Here is an example: 

        http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

   2. If you selected Metadata document endpoint URL:

      • Enter the URL where your metadata document is hosted in the Endpoint URL field.

      • Enter your SAML email attribute in the relevant field. Here is an example:  

        http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

3. Click Connect when done.

OpenID Connect

To begin configuring your SSO connection, log into the OBT, select Company from the Program menu, expand the Configuration menu (on the left) and select Integrations. Then select the SSO tab click Connect next to the OpenID Connect option. 

1. Specify the values for the following fields

   • Attribute request method (GET or POST).

   • Client ID

   • Client Secret

   • Issuer URL

   • Open ID connect email attribute 

2. Click Connect when done.

Google’s Standard

To begin configuring your SSO connection, log into the OBT, select Company from the Program menu, expand the Configuration menu (on the left) and select Integration. Then select the SSO tab and click Connect next to the Google Standard option. 

The Connect to Google window will be displayed. Click Connect.

Testing 

Once you have configured Spotnana to connect to your IdP, you and your users should test that the SSO functionality is working properly. You will be prompted to do the following: 

1. Log out of Spotnana.

2. Access the login page.

3. Select the SSO login option. You will be redirected to your IdP’s login page.

4. Enter your user ID and password for your IdP. You will be redirected back to Spotnana and logged in automatically.

Note: If this SSO redirect does not function properly for any of your users, they will still be able to log in using their Spotnana user ID and password credentials.

If you change any of your SSO connection settings in Spotnana, this test workflow will be re-initiated. 

General troubleshooting

If all users at your company encounters issues during the testing phase, try the following:

• Ensure all connection details are accurate and have been entered correctly in Spotnana.

• Ensure your identity provider (IdP) system is configured correctly and is accessible.

If only a few individual users at your company have issues, it’s likely that those users don’t yet exist in either Spotana or your IdP or both.

Issues with Microsoft Entra configurations

Some solutions for configuration issues with Microsoft Entra as described in this section. 

Error when sign-on URL is incorrectly configured

If the sign-on URL is incorrectly set, you will see a relay state error.

What causes the error?

This relay state error is displayed when you (or another user) try to login using a workflow that is initiated by an IdP (Microsoft MyApps https://myapplications.microsoft.com/) when the sign-on URL has not been configured correctly. 

This error will not occur if you navigate directly to the Spotnana application page ( https://app.spotnana.com/).

How can it be fixed?

You must update your SSO configuration with the correct sign-on URL. 

Obtain the correct sign-in URL from Spotnana

1. Open the Spotnana platform and sign on.

2. Select Company from the Program menu.

3. Select Integrations from the Configuration menu (on the left).

4. Select the SSO tab.

5. Click Manage for OpenID Connect or SAML (depending on your configuration)

6. Scroll to the bottom of the modal and locate the Sign-on link. Copy that URL into your clipboard (you will use it in the next procedure).

7. Depending on whether you are using SAML or OpenID connect, follow one of the following procedures below.

Set the sign-on URL for SAML SSO 

1. Open https://entra.microsoft.com/

2. Navigate to Enterprise apps (in the left hand menu).

3. Select your app’s name.

4. Navigate to Single sign-on.

5. Click Edit on the Basic SAML Configuration card.

6. Paste the URL you copied into your clipboard into the Sign on URL field to enable Spotnana-initiated SSO.

7. Click Save.

Set the sign-on URL for OpenID Connect SSO

1. Open https://entra.microsoft.com/

2. Navigate to App Registrations (in the left hand menu).

3. Select your app’s name.

4. Navigate to Branding & properties.

5. Paste the URL you copied into your clipboard into the Home page URL field to enable Spotnana-initiated SSO.
   

6. Click Save. 

Email attribute is set incorrectly

The SSO login attempt results in an endless loop.

What causes the error?

This occurs due to the email attribute being incorrectly set.  

How can it be fixed?

1. Open the Spotnana platform and sign on.

2. Select Company from the Program menu.

3. Select Integrations from the Configuration menu (on the left).

4. Select the SSO tab.

5. Click Manage for OpenID Connect or SAML (depending on your configuration).

6. Depending on whether you are using OpenID or SAML, follow the relevant steps. 

   • For SAML: 

     • Click Edit in the Edit connection section.

     • Click Next on the Configuring SAML in your IDP modal.

     • Click Next on the Select SAML Source modal. 

     • Enter the following attribute value in the SAML Email Attribute field in the Enter your company’s information modal:   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

   • For OpenID Connect: 

     • Click Edit in the Edit connection section.

     • Enter the following attribute value in the OpenID connect email attribute field in the Enter your company’s information modal: 
       http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

7. Click Save.

Caveats

SAML

• Identifiers: We do not support identifiers which are used to redirect users to the IdP in multi-tenant apps.

• Automatic sign out: We automatically log the user out of Spotnana when they are logged out of their IdP.

• IdP-initiated SAML sign in: We require SP-initiated SAML assertions (industry best practice).

• SAML signing and encryption: We do not support the signing of SAML requests or the requiring of encrypted SAML assertions.

OpenID Connect

• Identifiers: We do not support identifiers which are used to redirect users to the IdP in multi-tenant apps.

• Retrieve OpenID Connect endpoints: We only support Autofill through issuer URL and do not allow Manual Input for endpoints. We autofill the following: authorization endpoint, token endpoint, userinfo endpoint, and jwks_uri.

Related Topics

• Set automatic user session timeout