Basics

Our Tech Stack

Data protection

Information security

App Customization & Deployment

Analytics

Project management

Miscellaneous

Languages

Introduction to SAML

In this article, you will learn how to set up Single Sign-On (SSO) using the SAML protocol in Microsoft Entra ID (formerly known as Azure Active Directory / Azure AD). Security Assertion Markup Language (SAML) is a technology that can help you leave all problems connected to remembering passwords in the past and log in to all of your digital tools with a single sign-on. In order to do so, you need to configure the SAML 2.0 Identity Provider. This will allow you to onboard your users using SSO and let them access the tchop platform using the same credentials they use to access other platforms in your organization.

Note that this guide uses the new Azure portal accessible from https://portal.azure.com.

Some important terms:

• SAML - Security Assertion Markup Language
• Identity Provider (IDP) - the client, side who provides access to list of users
• Service Provider (SP) - tchop, side who consumes/uses list of users

Setting Up SAML Single Sign-Оn with Microsoft Entra ID

Prerequisites

• You have an Entra ID tenant.
• You have one of the following permissions to configure provisioning in Entra ID:
• Application Administrator
• Cloud Application Administrator
• Global Administrator

Creating an Enterprise Application

➡️

If you want to use one of the existing application, skip this step.

You need to create an enterprise application in Entra ID to set up SSO.

1. In Microsoft Azure, under Azure services, click Microsoft Entra ID.

1. Navigate to Enterprise applications.

1. Click New application.

1. Click Create your own application.The Create your own application dialog opens.

1. Provide a name for the application. For example, tchop SSO or something similar to help you instantly identify the application.
2. Select Integrate any other application you don't find in the gallery (Non-gallery).
3. Click Create.You have created an application to authenticate users using SSO.

Assigning Users

After creating the enterprise application, you can decide on which Entra ID users need access to the tchop platform using SSO.

tchop recommends adding a few users initially to test that everything works as expected.

1. In the enterprise application you created, click Users and groups.

The Users and groups page opens.

1. Click Add user/group.

1. Click None Selected. The Users and groups dialog opens.
2. Search for the user or group you want to add and click Select.
3. Click Assign. You have assigned users or groups to the application.

Setting up SSO With SAML

Once you have created the application, you need to define the SAML protocol.

Learn how the Microsoft identity platform uses the SAML protocol.

Select SAML Method

1. In the enterprise application, navigate to Overview.
2. Under Set up single sign on, click Get Started.
3. Select SAML as the single sign-on method.

The Set up Single Sign-On with SAML page opens.

Receive Information from tchop

To continue setting up SSO with SAML, you will receive the following to complete the SSO setup:

• Reply URL (Assertion Consumer Service URL): The Reply URL directs Entra ID where to send its SAML Response after authenticating a user. https://<TCHOP_DOMAIN>/api/webapp/sso/saml/callback?organisatio=<ORGANISATION_SUBDOMAIN>(For example: https://tchop.it/api/webapp/sso/saml/callback?organisation=tchop)

For WebApp:

For Mobile Apps:

1. <android_bundle_id>://login-callback
2. <iOS_bundle_id>://login-callback
3. <android_bundle_id>://logout-callback
4. <iOS_bundle_id>://logout-callback
• Metadata URL: Each tchop organisation has own metadata endpoint (if SAML is enabled): https://<TCHOP_DOMAIN>/api/webapp/sso/saml/metadata.xml?organisation=<ORGANISATION_SUBDOMAIN> eg https://tchop.it/api/webapp/sso/saml/metadata.xml?organisation=tchop

Complete the SSO Configuration

After receiving the information from tchop, you can complete the SSO configuration.

Step 1: Basic SAML Configuration:

In the Set up Single Sign-On with SAML page, click Edit under Basic SAML Configuration.

1. Enter the Identifier (Entity ID): How to create EntityID:
• Open an application


• Open Expose an API page


• Create Application ID URI
• After opening modal with pre-filled ID field - save it

eg api://e39244c9-565c-4fbb-b5fd-b83d77eeb511

1. Add Reply URL (Assertion Consumer Service URL) you received from tchop.

Step 2: Attributes & Claims

1. Under SAML Signing Certificate, click Edit.The Attributes & Claims page opens.

You can modify a claim and adjust its values according to your business requirements.

At minimum, you need the following claims configured:

email:

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

sub (external user id):

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

screen name:

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

➡️

tchop route documentation:

• https://tchop-staging.com/api/docs#/webapp/SamlController_samlCallback
• https://tchop-staging.com/api/docs#/webapp/SamlController_samlLogin
• https://tchop-staging.com/api/docs#/webapp/SamlController_getMetadata

Step 3: SAML Signing Certificate

The values are auto-filled based on your enterprise application and Entra ID tenant.

Step 4: Set up

The values are auto-filled based on your enterprise application and Entra ID tenant.

Step 5: Test single sign-on

1. Under Test single sign-on, click Test.
2. Select a way to test sign in and click Test sign in. The sign in page opens for you to test.
3. Ensure the sign in functions as expected.

Assigning All Users

After testing the SSO authentication works as expected, you can add all users in Entra ID to the enterprise application.

1. In the enterprise application you created, click Properties.
2. Set Assignment required? to No.

1. Click Save.

You have configured and enable SSO for your tchop platform.

Provide tchop Your Enterprise Application Details

Once you are done with the SAML configuration on your end, simply provide the following information to tchop and rest will be taken care by tchop.

Provide the following information to tchop:

• Identifier (Entity ID)
• App Federation Metadata Url

You can copy App Federation Metadata Url from Set up Single Sign-On with SAML page under the SAML Signing Certificate section.

Alternatively: Replace the TenantDomainName substring in the URL with the copied value.

https://login.microsoftonline.com/<TenantDomainName>/FederationMetadata/2007-06/FederationMetadata.xml

e.g. https://login.microsoftonline.com/3facffa7-34b0-4fe1-b89e-4deef5510293/FederationMetadata/2007-06/FederationMetadata.xml

➡️

TenantDomainName can be found by opening Microsoft Entra ID for workforce page > App registrations > All applications > Select an appication > copy Directory (tenant) ID field under Essential section

You can configure the SAML domain hints to ensure that users don't attempt to authenticate with the identity provider (IdP) using domains that are not allowed when using the tchop platform. To activate this feature, contact tchop Support. Learn more about domain hints.

Troubleshooting

‣

tchop returns error code SAML top level signature is invalid for ADFS Identity Provider:

the issue describes here https://github.com/node-saml/node-saml/issues/211.

In short - ID attribute from root tag should be equal to URI attribute in Reference tag

saml response from Auth0 - works fine

saml response from adfs - doesn’t work

https://learn.microsoft.com/en-us/powershell/module/adfs/set-adfsrelyingpartytrust?view=windowsserver2022-ps#-samlresponsesignature

➡️

based on this info https://learn.microsoft.com/en-us/answers/questions/483078/(adfs)(saml)(response)(signature)-adfs-doesnt-send#answer-483504 value must be MessageAndAssertion or MessageOnly

‣

tchop returns error code SAML top level signature is invalid for Azure Identity Provider:

The issue is the same as above. You need to Change certificate signing options to use Sign SAML response and assertion value. Learn more here: https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/certificate-signing-options#change-certificate-signing-options-and-signing-algorithm

• Introduction to SAML
• Setting Up SAML Single Sign-Оn with Microsoft Entra ID
• Prerequisites
• Creating an Enterprise Application
• Assigning Users
• Setting up SSO With SAML
• Receive Information from tchop
• Complete the SSO Configuration
• Provide tchop Your Enterprise Application Details
• Troubleshooting
• tchop returns error code SAML top level signature is invalid for ADFS Identity Provider:
• tchop returns error code SAML top level signature is invalid for Azure Identity Provider: