Setting up Single Sign-On (SSO)

SSO allows users to log in to the SCAYLE Panel using a central identity provider (e.g., Entra ID or Google Workspace) without needing separate credentials for the SCAYLE Panel.

Preconditions

• Access to the SCAYLE Panel with administrator privileges
• Access to Microsoft Entra ID or Google Workspace with permissions to create and configure Enterprise or Custom SAML Applications
• Basic understanding of authentication concepts

Technical Overview (Simplified)

SSO with Microsoft Entra ID (Azure AD)

Preamble

To enable SSO, you must create a dedicated Enterprise Application in Entra ID.

In this guide, we refer to this application as the “Entra ID Panel Integration.”

This application will connect Entra ID as the IDP and the SCAYLE Panel as the Service Provider (SP) using the SAML 2.0 protocol.

Entra ID Configuration

Step 1: Create a Service Provider in the Panel

1. In your SCAYLE Panel, navigate to Settings ➜ General ➜ Configurations ➜ SSO Configurations.
2. Create a new SAML Service Provider configuration for Entra ID.
3. After creating the provider, note down the following values since you’ll need them in Entra ID:
4. Entity ID (Identifier)
   • Reply URL (Assertion Consumer Service / ACS URL)
   • Sign-on URL
   • Logout URL
   • Relay State (if provided)
   • Panel encryption certificate
5. Configure Default Company and Default Shop for new users created via this SSO.
   • Administrators can later adjust these assignments to fine-tune each user’s access rights as needed.
   • Adjusted permissions made by administrators are not overwritten after initial user creation.

Step 2: Create the Entra ID Application

1. Log in to your Microsoft Entra Admin Center.
2. Go to Entra Admin Center ➜ Enterprise Applications ➜ + New application
3. Select Create your own application e.g. Entra ID Panel Integration.
4. Optionally add a logo or description, these fields have no effect on Panel configuration.

Step 3: Configure SAML-based Single Sign-On

1. In your new application “Entra ID Panel Integration”, open Single Sign-On ➜ SAML.
2. Under Basic SAML Configuration, fill in the following fields with the values from your SCAYLE Panel’s Service Provider:
   • Identifier (Entity ID)
   • Reply URL (ACS)
   • Sign-on URL
   • Relay State (optional)

Step 4: Configure Attributes & Claims

1. Go to the Attributes & Claims section.
2. Make sure at least the following attributes are provided:
   1. Unique User Identifier (Name ID)
   2. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
   3. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
   4. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
   5. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/roles

The following table shows the claims and their respective source attributes and the required formatting:

Step 5: Configure the SAML Signing Certificate

1. In SAML Certificates, create a new certificate pair.
2. Download one of the certificates (Base64 format recommended).
3. Upload the certificate to your Scayle Panel under the respective Service Provider.
4. Ensure the following options are configured in Entra ID:
   • Signing Options: Sign SAML response and assertion
   • Signing Algorithm: SHA-256

Step 6: Configure SSO URLs

1. In the section Set up “Entra ID Panel Integration”, copy the following values:
   • Azure AD Identifier (Issuer)
   • Login URL
   • Logout URL
2. Paste these into the Identity Provider configuration fields in your SCAYLE Panel.
   • Azure AD Identifier (Issuer) into Identifier (Entity ID)
   • Login URL into Sign on URL
   • Logout URL into Logout URL

Step 7: Configure Token Encryption

1. Under Token Encryption, import the Panel certificate (available in the SCAYLE Panel Service Provider configuration).
2. This ensures that SAML responses from Entra ID are encrypted and secure.

General

Logout Users

In Entra ID, there are two ways to log out a user:

1. From the Identity Provider (Entra ID):
   When a user logs out from Entra ID, a SAML Single Logout (SLO) request is sent, which also terminates the user’s session in the SCAYLE Panel.
2. From the SCAYLE Panel:
   When a user logs out directly from the SCAYLE Panel, the SAML logout flow is triggered, logging the user out from Entra ID as well.

This ensures a consistent logout experience and session termination on both sides.

Assign Users and Groups

1. In the Entra ID Application, navigate to Users and Groups.
2. Click Add user/group.
3. Select users or groups who should have access to the Panel.
4. Assign the appropriate role on the right-hand side.

Create Custom Roles

1. Navigate to your Entra Admin Center ➜ App registrations ➜ Entra ID Panel Integration. Open App roles ➜ + Create app role.
2. Define roles that can later be mapped in the Panel:
   • Display name: e.g., Administrator
   • Allowed member types: Both
   • Value: internal role name (available via Panel Role Overview ➜ Export CSV)
3. Internal names follow these rules:
   • lowercase only
   • underscores instead of spaces
     no special characters or umlauts

Frequently Ask Questions

User Defaults During Service Provider Creation

When creating a service provider, administrators can define default settings for new users. These defaults determine which companies and shops a user can access after a successful login.

Setting these defaults is mandatory, ensuring that new users do not automatically gain access to all shops and companies within the system.

Administrators can later adjust these assignments to fine-tune each user’s access rights as needed. The adjustments made by administrators are not overwritten by the default settings, as these defaults are applied only once during the initial creation of an SSO user after their first successful login.

Example: If the user defaults are set to Shop 1001 and Company 1000, the first time the user signs in, their account is created in the Panel with these access permissions automatically applied.

How does a User flow works in the panel

Users identification

To provide a seamless and secure Single Sign-On (SSO) experience, our user identification strategy prioritizes the unique identifier provided by the Identity Provider (IdP). This ensures that users can always log in, even if their email address changes at the IdP, and protects against account takeover scenarios.

The Core Principle: NameID is the Source of Truth

While users are unique by email within our application, for SSO logins, the primary identifier will be the persistent SAML NameID provided by the Identity Provider.

• Upon a user's first SSO login, we will store this NameID and associate it with their local user account and the specific SSO configuration they are using.
• On all subsequent logins, we will use this stored NameID to find and authenticate the user.

Handling Email Address Changes

If a user’s email address changes in the Identity Provider (IdP), it is not automatically updated in the SCAYLE Panel. The existing email address in our system remains unchanged until it is manually updated by an administrator.

Session duration and timeout

The session duration is primarily managed by the Identity Provider (IdP). Each IdP handles session lifetime differently, and some may not support configuring it.

In the SCAYLE Panel, user sessions last 24 hours by default. Fifteen minutes before expiration, a notification banner appears, allowing users to extend their session if needed. If the user chooses not to extend it, only the Panel session will expire and the IdP session remains active.

To synchronize the Panel session duration with the IdP session, the IdP must include the SessionNotOnOrAfter attribute in the ACS (Assertion Consumer Service) response.

Multi-Factor Authentication (MFA) Handling

Both the SCAYLE Panel and the Identity Provider (IdP) can enforce Multi-Factor Authentication (MFA).

To ensure a seamless user experience, users who sign in via SSO will only be prompted for MFA by the IdP.

In this case, the Panel’s built-in MFA will not be enforced.\