Setting up SSO with Azure AD for Leadr

Leadr allows for the connection between Azure AD and our platform via the SAML protocol to enable users to sign into the platform with an existing Azure AD login, eliminating the need for an additional login for your users to manage.

To begin setting up the connection, please follow the steps shown below using the information provided by Leadr to set up and configure the Azure AD application.

There are two parts to setting up SSO with Leadr:

To create and configure the SSO connection, you will need the following values provided by Leadr as referenced in bold in the guide below. These values consist of the following:

If you did not receive any one or more of the above values from your Leadr contact, please reach out for assistance before proceeding with the application setup.

In order to allow Leadr to communicate with Azure AD, a custom Enterprise Application must be created and configured with the necessary credentials provided by Leadr.

Firstly, log into Azure AD with an administrator account and navigate to the homepage.

Type “Enterprise” in the Search bar at the top of the portal and choose “Enterprise applications”.

Next, click the “New application” button in the top left corner of the “All applications” tab.

When redirected to the Azure AD gallery page, click the “Create your own application” button in the top left corner of the page.

Enter an application name that will help you identify this app in the future and ensure the “Integrate any other application you don't find in the gallery (Non-gallery)” option is selected.

Click the “Create” button at the bottom of the drawer to create the application and be redirected to the application page.

Now that the application has been created, you can begin configuring the settings to perform the connection between Azure AD and Leadr.

On the page for the newly created application, click the “Single sign-on” menu item, and then select “SAML” as the single sign-on method.

Once redirected to the “SAML-based Sign-on” settings page, click the “Edit” button in the top right corner of the “Basic SAML Configuration” section to begin configuring the SAML connection.

In the “Basic SAML Configuration” drawer that appears on the right side of the screen, under the “Identifier (Entity ID)” section at the top, click the “Add identifier” button and enter the SAML Identifier provided by Leadr.

While still in the “Basic SAML Configuration” drawer, click the “Add reply URL” button under the “Reply URL (Assertion Consumer Service URL)” section and enter the SAML Reply URL provided by Leadr.

Once both sections are completed using the details provided by Leadr, click the “Save” button in the top left corner of the “Basic SAML Configuration” drawer.

Next, click the “Edit” button in the top right corner of the “Attributes & Claims” section to be redirected to the Attributes & Claims configuration page for the application.

On the Attributes & Claims configuration page, click the “Add new claim” button in the top left corner of the page to create a new claim to be utilized by the SAML connection.

On the “Manage claim” page that appears after clicking “Add new claim”, set the “Name”, “Namespace”, and “Source attribute” fields to be equal to the values shown below:

When completed, click the “Save” button in the top left corner of the “Manage Claim” page to create the claim. Once the new claim has been created, the Attributes & Claims page should look as shown below.

Now, on the “Attributes & Claims” page, click the “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name” claim to be redirected to the Manage Claim page for the “name” claim.

On this page, change the value of the “Source attribute” field from “user.userprincipalname” to “user.displayname” as shown below.

Once updated, click the Save button in the top left corner to save your changes.

Navigate back to the Enterprise Application Single sign-on configuration page and scroll down to the “SAML Certificates” section. In this section, find the “Certificate (Base64)” field and click the “Download” button next to it.

Once downloaded, save this certificate and provide it to your contact at Leadr who is facilitating the setup of the connection once completed with all steps in this guide.

After downloading the SAML Certificate, scroll down the “Set up [application name]” section and locate the “Login URL” field.

Once located, click the copy icon to the right of the URL to copy this value to your clipboard.

Along with the certificate from the previous step, this value will also need to be provided to your Leadr contact to finalize the SAML connection.

Now that the application has been created and configured within Azure AD using the information provided by Leadr, navigate to the “Users and groups” tab in the sidebar on the left side of the Enterprise Application management page and click the “Add user/group” button on the top left of the “Users and groups” page.

Depending on how you utilize the Azure AD user management system, this step may vary, but for this example, we will be granting access to the application to individual users. If your organization utilizes groups, you may grant access to a group/role instead.

On the “Add assignment” page that appears when the “Add user/group” button is clicked, click the “None Selected” button under the “Users” section to select a set of users to assign to the application.

In the “Users” drawer that appears on the right side of the page once the “None Selected” button is clicked, select the users that you would like to assign to the application to grant them access to log in via the SAML connection, and click the “Select” button at the bottom of the drawer once completed.

Once the users have been selected, click the “Assign” button in the bottom left corner of the “Add Assignment” page to assign the users to the application.

Now that the application has been configured utilizing the information provided by Leadr and users have been assigned to the application, the final step is to provide the SAML Certificate file and Login URL value from the previous steps to your contact at Leadr who is facilitating the setup of the connection to finalize the process on the Leadr side.

If you run into any issues or difficulties completing any of the above steps, you may reach out to your contact at any time for direct assistance from a member of our technical team to guide you through the process.

As an added benefit of the SSO via SAML integration, Leadr also supports the ability to utilize the SCIM (System for Cross-domain Identity Management) protocol to allow for automatic provisioning of user accounts within Leadr directly from Azure AD.

To begin setting up the SCIM integration, please follow the steps shown below using the information provided by Leadr to set up and configure the integration within your existing Azure AD application.

To create and configure the SCIM integration, you will need the following values provided by Leadr as referenced in bold in the guide below. These values consist of the following:

If you did not receive any one or more of the above values from your Leadr contact, please reach out for assistance before proceeding with the application setup.

In order to allow Leadr to communicate with the Azure AD provisioning service, you must have a custom Enterprise Application with provisioning enabled and configured with the necessary credentials provided by Leadr.

Firstly, log into Azure AD with an administrator account and navigate to the custom Enterprise Application that was created by following the above steps from the SAML based authentication setup guide.

Once on the Enterprise Application management page, click the “Provisioning” button on the left-hand sidebar.

Once on the Provisioning overview page, click the “Get Started” button to begin setting up provisioning.

On the setup page, click the “Provisioning Mode” dropdown and change “Manual” to “Automatic”.

After changing the Provisioning Mode to “Automatic”, additional configuration options will appear on the page, allowing you to input the credentials necessary to enable the integration.

In the “Admin Credentials” section that appears, set the Tenant URL to be the Leadr-provided SCIM Endpoint URL and the Secret Token to be the Leadr-provided SCIM Authentication Token as shown in the below screenshot.

Once the values have been added, click the “Test Connection” button to ensure a successful connection to the Leadr SCIM integration. If successful, a notification will be shown in the top right corner as shown in the below screenshot.

Once verified, click the Save button in the top left corner to save the connection.

Once the connection has been verified and saved, scroll down to and expand the section titled “Mappings” and click on the “Provision Azure Active Directory Users” text to be redirected to the mappings management page for user provisioning.

In the Attribute Mapping page that appears, scroll down to the Attribute Mappings section and locate the attribute that has externalId as the customappsso Attribute, and click on it to modify the attribute.

Once redirected to the Edit Attribute page, locate the “Source attribute” section and click the dropdown to modify the mapped attribute value. In the dropdown, change the default selection to be objectId and click the “Ok” button in the bottom left corner to add the changes to the mapped attribute.

When redirected back to Attribute Mapping page, click the Save button in the top left corner to save the changes to the mapped attributes.

After updating the mappings to include the newly required fields, you will want to ensure you’ve removed all fields that Leadr does not support to prevent any validation errors from occurring when provisioning users. To simplify this process, take the example mapping screenshot shown below and simply remove any existing fields from your mapping that are not shown in the screenshot.

Once you’ve removed all unsupported mappings and have verified that your mappings shown match the above example exactly, click the Save button in the top left corner to save your changes to the attribute mappings.

If you do not have the manager or department fields available, you can add them by toggling “Advanced Options” on the attribute mapping page and then selecting “edit attribute list for customappsso”, as shown below:

To add the new fields, use the following values as the attribute names, and ensure the dropdown values are set to match what is shown in the table/screenshot below.

Once you’ve added the missing custom fields and saved your changes, the fields should now be available to map within your integration.

As of now, Leadr currently supports the following custom/non-standard fields to be used as mappings within the SCIM integration:

To support these custom fields, you will need to navigate back to the attribute mapping screen and then click the “Show advanced options” checkbox to reveal the “Edit attribute list for customappsso” link.

After clicking on the link to navigate to the “Edit Attribute List” page, scroll to the bottom of the attribute list and add the following new attributes, leaving all other fields blank:

Once these fields have been added to the attribute list, they then become available to be mapped within the integration via the Attribute Mapping page.

With the new attribute added to the integration attribute list, you can then map the value for the user’s Hire Date using the built-in employeeHireDate field within Azure AD.

The Leadr SCIM integration requires this field to be in the date format of YYYY-MM-DD, which is easily doable using Function Expressions within the attribute mapping.

To ensure the date is formatted correctly within the integration, navigate to the Attribute Mapping page and click “Add New Mapping” at the bottom of the table.

On this page, set the target attribute to be the urn:ietf:params:scim:schemas:extension:Leadr:2.0:User:hireDate attribute that we recently added to the attribute list.

At the top of the page, set the Mapping type to “Expression” and then paste the following into the text box directly underneath the mapping type dropdown:

FormatDateTime([employeeHireDate], , , "yyyy-MM-dd")

This will ensure that the employee hire date value is formatted as YYYY-MM-DD to ensure the integration can validate it properly.

Once completed, the mapping for this attribute should look like this:

Since there are no built-in fields within Azure AD to store a user’s birthday, we will need to create a new custom attribute for our application that will allow us to set and use the attribute for each user within the integration.

To get started, visit the Microsoft Graph Explorer and sign in to your tenant on the right side of the UI next to the URL bar. Ensure you are using an account with the necessary permissions to access and modify application/user resources within Azure.

Once signed in, we need to fetch the internal application ID belonging to our custom application within Azure AD that is used for the integration. You can do this by making a request in the Graph Explorer via the following URL:

https://graph.microsoft.com/v1.0/applications?$search="appId:YOUR-APP-ID-HERE"&$select=id,displayName

To make this request, you will need to get the “Application ID” for your application within Azure AD on the application overview page.

Simply click the “copy” button next to the Application ID field on the overview screen for your application, and then replace the “YOUR-APP-ID-HERE” in the above request URL with your copied application ID.

After updating the request URL, click the “Request Headers” tab and add the following header to your request (required to use the $search parameter):

ConsistencyLevel: eventual

Your request headers should look like the following when set:

Once the URL and request headers have been set, you can click the “Run query” button on the right side of the Graph Explorer.

If successful, you should receive a 200 status code as well as a response that looks like the following:

After obtaining the internal ID for your application, navigate to this Microsoft documentation page which details how to define a custom attribute within your application. Following this guide, set the application ID in the request URL to be the internal ID you copied from the previous step.

After setting the request URL, you can use the following payload to create a new attribute named “birthday”:

{

"name": "birthday",

"dataType": "String",

"targetObjects": [ "User" ]

}

Once you have defined a new custom attribute, copy the extension field ID from the attribute creation response, which should look something like:

extension_b4d9d13227f44b83a59f0c63a2ae49df_birthday

Note: The newly created extension attribute will have unique characters in the middle, so make sure to copy the one from the create attribute response and not the one shown here.

With the extension attribute created and the ID copied, you can set the value for this attribute for any user by making a request similar to the one in this step of the documentation.

Simply navigate to the Users page in Azure AD in another tab while leaving Microsoft Graph open in the other. Once on the users page, select the user you’d like to set the birthday for, and click on their profile.

On the user’s profile page, click the “copy” icon next to the “Object ID” field to copy the user’s ID to be used in the subsequent request.

After copying the user’s Object ID from the profile page, switch back over to the Microsoft Graph Explorer and set the request URL to be the following:

https://graph.microsoft.com/v1.0/users/YOUR-USER-ID-HERE

Then, set the request payload to the following, swapping out the “YOUR-EXTENSION-ID-HERE” for the extension field ID that was shown in the response when the extension field was created.

{

“YOUR-EXTENSION-ID-HERE”: “1985-10-26”

}

After updating the values within the URL and payload, set the request type to PATCH and then hit the “Run query” button to set the property for the user.

To observe that the property was indeed set for the user, change the request type to GET and add “?$select=YOUR-EXTENSION-ID-HERE” to the end of the request URL and then run the query to see that it properly shows the value for the user in the response.

Now that you’ve set the value for the user using the Microsoft Graph explorer, you’re ready to map the value within the integration to allow it to be ingested into Leadr alongside the existing properties.

To map this field, navigate to the Attribute Mapping page for the application used within the integration, and click “Add New Mapping” at the bottom of the page.

On this page, set the “Mapping type” to “Expression” and then paste the following into the text field directly below the Mapping type dropdown.

FormatDateTime([YOUR-EXTENSION-ID-HERE], , , "yyyy-MM-dd")

This expression will ensure that the value will be normalized to the required format for the integration regardless of the input structure.

After setting the expression mapping, click the “Target attribute” dropdown and select the urn:ietf:params:scim:schemas:extension:Leadr:2.0:User:birthday entry that we added earlier via the changes to the application attribute list.

Once completed, the mapping for this attribute should look like the following:

Lastly, once satisfied with the settings for this attribute mapping, click the “Save” button at the bottom to apply the changes to your application, which completes the setup for this custom attribute within the integration.

Due to a limitation within Azure, the profile images uploaded to a user’s profile are not able to be transmitted via SCIM. In order to work around this, a custom property must be created to store the profile image URL for each user. Please follow the steps for creating a custom property defined in the Birthday section of the documentation.

Once created, you can simply map the custom attribute to the urn:ietf:params:scim:schemas:extension:Leadr:2.0:User:profileImageUrl property in the SCIM request.

Please note that the link must be a publicly accessible direct link to the image, and the file type must be either .png or .jpg.

Please also note that in Azure, custom property values are limited to 256 characters in length, so please ensure your image URLs are within this threshold or Azure will be unable to store them.

Provided you have already assigned users to your custom Enterprise Application as directed in the SAML setup portion of this guide, you are ready to begin provisioning users.

To initiate provisioning, navigate back to the Provisioning Overview page and click the “Start Provisioning” button to start the initial provisioning cycle.

Once the provisioning job has been completed, you can view the results of each provisioned user by navigating to the Provisioning Logs page by clicking the button in the left-hand sidebar or via the “View provisioning logs” on the Provisioning Overview page.

Groups are supported via provisioning, where each group in Azure is meant to represent a team within Leadr. When a group is provisioned, it will create a team in Leadr and update it to match the state of the group within Azure. A few things to note when provisioning groups: