SAML SSO Setup

This guide walks through configuring SAML-based Single Sign-On for your Hinsley account. SAML SSO allows your team members to authenticate using your organization's Identity Provider (IdP), such as Microsoft Entra ID, Okta, OneLogin, or any SAML 2.0-compatible provider.

Prerequisites

  • A Hinsley account on the Enterprise plan
  • Admin access to your Hinsley account
  • Admin access to your organization's Identity Provider

Step 1: Navigate to the SAML Configuration Page in Hinsley

  1. Log in to Hinsley as an account administrator.
  2. Open the account admin area by clicking on your avatar in the top right and selecting Account Admin.
  3. Select the Authentication tab to access the SSO configuration pages.
  4. Click the SAML tab at the top of the page.
SAML configuration page in Hinsley showing the authentication settings

Step 2: Enable SAML Authentication

  1. In the Account SAML Authentication dropdown, select Required for all account users.
  2. Scroll to the bottom and click Save.
  3. Once enabled, Hinsley will display your SAML Metadata URL at the top of the form. This URL provides your IdP with Hinsley's Service Provider (SP) metadata. You can copy the URL to paste into your IdP's configuration or download the metadata as an XML file to upload to your IdP.

Step 3: Register Hinsley as a Service Provider in Your Identity Provider

You will need to register Hinsley as an application/service provider in your IdP. The specific steps vary by provider, but the general process is the same.

Most Identity Providers allow you to import Service Provider metadata, which automatically configures the required settings (Entity ID, ACS URL, etc.). Use the SAML Metadata URL displayed on the Hinsley SAML configuration page, or download the metadata XML file and upload it to your IdP.

Microsoft Entra ID (Azure AD)

  1. In the Azure Portal, go to Microsoft Entra ID > Enterprise applications > New application.
  2. Select Create your own application, give it a name (e.g., "Hinsley"), and choose Integrate any other application you don't find in the gallery (Non-gallery).
  3. Once created, go to Single sign-on > SAML.
  4. Click Upload metadata file and upload the metadata XML file downloaded from Hinsley. This will automatically populate the Entity ID and Reply URL. Click Save.
  5. In the Attributes & Claims section, configure the claims mapping (see Attribute Mapping below).
  6. In the SAML Certificates section, download the Federation Metadata XML file. You will upload this to Hinsley in the next step.

Okta

  1. In the Okta admin console, go to Applications > Create App Integration.
  2. Select SAML 2.0 as the sign-in method.
  3. When configuring the SAML settings, upload Hinsley's metadata XML file or use the metadata URL to automatically populate the SSO URL and Entity ID fields.
  4. Configure the attribute statements (see Attribute Mapping below).
  5. After completing the setup, navigate to the Sign On tab and download the IdP metadata or copy the Metadata URL.

Other SAML 2.0 Providers

Consult your IdP's documentation for adding a custom SAML application. Most providers support importing SP metadata via URL or file upload — use Hinsley's SAML Metadata URL or downloaded metadata file to configure the integration.

Step 4: Configure Hinsley with Your IdP's Information

There are two ways to configure the IdP details in Hinsley:

Option A: Upload IdP Metadata (Recommended)

  1. On the Hinsley SAML configuration page, find the Import from IdP Metadata section on the right side.
  2. Upload your IdP's metadata XML file by dragging it into the upload area or clicking to browse.
  3. This will automatically populate the SSO URL, SLO URL (if available), and signing certificates.
  4. Click Save.

Option B: Manual Configuration

If you cannot obtain a metadata file, you can configure the fields manually:

Field Description
IdP SSO Target URL The URL where Hinsley redirects users for authentication
IdP SLO Service URL (Optional) The URL for Single Logout, if your IdP supports it
IdP Signing Certificates The PEM-encoded X.509 certificate(s) your IdP uses to sign SAML responses. Paste the full certificate including the BEGIN and END headers. Multiple certificates can be pasted together.
IdP Encryption Certificates (Optional) PEM-encoded certificate(s) for encrypting SAML assertions. Usually not required.

Attribute Mapping

Hinsley expects certain user attributes from the SAML response. You can change these on the Hinsley SAML configuration page to match your IdP's attribute names.

Hinsley Attribute Default Claim URI Required Description
Email http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress Yes The user's email address. Used for user identification.
First Name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname No The user's first name.
Last Name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname No The user's last name.
User ID http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier No A unique, immutable identifier for the user from your IdP. Used for matching users across sessions.
Language not set by default No The user's preferred language.

Microsoft Entra ID Claims Configuration

When configuring claims in Microsoft Entra ID, set up the following attribute mappings:

Claim Name Source Attribute
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress user.mail (or user.userprincipalname)
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname user.givenname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname user.surname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier user.objectid
Tip: If your IdP only provides the user's email as the SAML NameID (and does not send a separate email attribute), you can enable the Use NameID for email fallback checkbox on the SAML configuration page. Hinsley will then use the NameID value as the email address when the email attribute is missing from the response.

Step 5: Assign Users in Your Identity Provider

Before users can log in via SSO, they must be assigned to the Hinsley application in your IdP.

  • Microsoft Entra ID (Azure AD): Go to the Enterprise application > Users and groups > Add user/group, and assign the relevant users or groups.
  • Okta: Go to the application's Assignments tab and assign users or groups.

Step 6: Test the Configuration

  1. Open a new browser window (or incognito/private window).
  2. Navigate to your Hinsley login page.
  3. You should see a Login with Single Sign-On button. Click it.
  4. You will be redirected to your IdP's login page. Authenticate with your credentials.
  5. After successful authentication, you will be redirected back to Hinsley and logged in.
Note: Users who are not yet in Hinsley will be automatically created upon their first SAML login, provided the account has not reached its user limit. If SCIM provisioning is enabled, new users must be provisioned through SCIM instead and will not be auto-created via SAML login.

Disabling SAML

To disable SAML:

  1. Navigate to the SAML configuration page.
  2. Change the Account SAML Authentication dropdown to Disabled.
  3. Click Save.

When SAML is disabled, all users who were authenticating via SAML will be switched back to password-based authentication. They will need to use the "Forgot Password" flow to set a password.