# Setup Single Sign On (SSO) with SAML EC3 supports integration with various [Identity Providers](#user-content-fn-1)[^1] (IdP) who implement the [SAML protocol](https://en.wikipedia.org/wiki/SAML_2.0). If your organization has a compatible, centralized user management system like Microsoft Entra ID, Active Directory or Google Workspaces this integration will enable your users to log into all BuildingTransparency services with your corporate authentication server. You can configure your server to decide which groups of users are eligible to login into EC3. ## Setting up the integration This section explains the complete flow for setting up a Single Sign-on (SSO) integration for Building Transparency products with SAML based IdP[^2]. The configuration process requires actions by the EC3 engineering team and yourselves. Before you start: * You have an EC3 subscription that supports SSO integration. (contact ) * Ensure you have access and **permissions to change SAML** configuration with your identity provider * You have received the following from BuildingTransparency: * Issuer/Identifier/Entity ID, for example “Entity ID: * ACS/Reply URL/Assertion Consumer Service, for example: “Reply URL (ACS): #### IdP Specific Instructions * [Microsoft Entra ID](#microsoft-entra-id) (formerly Azure AD, Azure Active Directory) ### Microsoft Entra ID #### Step 1 - Create a BuildingTransparency Application in Azure 1. In [Microsoft Entra ID](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview) 1. go to [**Microsoft Entra ID** > **Enterprise Applications**](https://portal.azure.com/#view/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/~/AppAppsPreview/menuId~/null), 2. click **+ New application** to display the Browse Microsoft Entra ID Gallery, and 3. click **+ Create your own application**.\ The Create your own application side panel is displayed.

Create new SAML application dialog (MS Entra ID)

4. Select **Integrate any other application you don’t find in the gallery (Non-gallery)** 5. click **Create**. #### Step 2 - Initial Configuration 1. Open your newly created application. 2. From the left navigation panel select **Single sign on** \

Single Sign-on of the SAML app (MS Entra ID)

Select **SAML** from the list of the proposed authentication options

3. Locate the **Basic SAML Configuration** section and click 3 dots icon in the right top corner;\ Choose **Edit** from the drop down menu.

Open basic SAML configuration editor (MS Entra ID)

4. The **Basic SAML Configuration** side panel is displayed.

1. Set **Identifier (Entity ID)** and **Reply URL (Assertion Consumer Service URL)**. You should ask Building Transparency support for this values. \ Click **Save** and close side panel. #### Step 3 - Configure Attribute Mapping {% hint style="info" %} Depending on the settings of your organization the attribute mapping might be slightly different. This guide assumes you use email as a user identifier and you didn't do any changes to the standard user fields. {% endhint %} 1. In section 2 "Attributes & Claims" click three dots icon and then Edit item from dropdown menu

Open attributes mapping dialog (MS Entra ID)

2. Attribute Mapping dialog will appear

3. Click on the Unique User Identifier field and make sure the configuration matches the screenshot below:

Unique User Identifier field mapping (MS Entra ID)

4. For each of the additional claims set mapping as per picture below.\ **IMPORTANT**: You must remove the namespace from each of the fields:

Repeat this procedure for each field so you have the following mapping: | SAML Claim | Source attribute | | ----------- | ---------------- | | email | user.mail | | first\_name | user.givenname | | last\_name | user.surname | | name | user.displayname | The final result should look like this:

5. Close the dialog to return back to your SAML app configuration. #### Step 4 - Collect credential Once you have configured your application, you will need to collect your application identifiers and certificate. You will be sending this information to Building Transparency. 1. In Section 3 "SAML Certificates". Locate field **Certificate (Base64)** and click Download

2. In section 4 "Set up" locate Login and Logout URLs and copy values

3. Send the following information to your contact at Building Transparency: 1. SAML Login URL 2. SAML Logout URL 3. Certificate in Base64 format #### Step 5 - Grant access to your users You can either allow anyone in your organization to use this app or configure strict rules to enable access for the selected users. To allow access for everyone within your organization: 1. Open Properties from the left navigation menu on your SAML app page 2. Select **Assignment required** = No\

Make application available for everyone within organization (MS Entra ID)

To restrict access for specific group or users: 1. Navigate to Users and Groups from the left navigation menu of your SAML app page. 2. Select Add user/group and configure access as needed\

Restrict access to the application (MS Entra ID)

#### Step 6 - Wait for notification by Building Transparency Building Transparency engineers will update configuration with the data you supplied and let you know when you can start testing the integration. [^1]: An identity provider (abbreviated IdP or IDP) is a system entity that creates, maintains, and manages identity information. Examples are Google Workspaces, Active Directory, etc. [^2]: Identity Provider