Setup Single Sign On (SSO) with SAML

EC3 supports integration with various Identity Providers (IdP) who implement the SAML protocol. 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. 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 [e-mail])

• 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: https://auth.buildingtransparency.org/source/saml/acme-saml”

  • ACS/Reply URL/Assertion Consumer Service, for example: “Reply URL (ACS): https://auth.buildingtransparency.org/source/saml/acme-saml/acs/”

IdP Specific Instructions

• 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

   1. go to Microsoft Entra ID > Enterprise Applications,

   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

   

   Select SSO method (MS Entra ID)
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)

1. The Basic SAML Configuration side panel is displayed.

Basic SAML editor (MS Entra ID)

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

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.

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

   

   Attribute Mapping dialog (MS Entra ID)
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:

Final attributes mapping (MS Entra ID)

1. 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

   

   Download SAML certificate (MS Entra ID)

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

   

   SAML App URLS (MS Entra ID)

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.