Microsoft Entra ID

Microsoft Entra ID (Formerly known as Azure Active Directory) is a directory service provided as part of Microsoft Azure cloud.

Roles

These are the roles that are needed:

• Owner

Azure Configuration

You need to start by setting up an Enterprise Application in Microsoft Entra ID. To do this, log into https://portal.azure.com and select Microsoft Entra ID -> Enterprise Applications.

Add a new application and select Create your own application. This will open a popup where you should enter a suitable name for your application and select the option to create a Non-Gallery application.

Assign the users you want to grant access to Iconik for. This allows you to control which users in your directory has access to Iconik.

After this, go back to the overview page and select 2. Set up single sign on.

Select SAML as the sign-on method.

This brings you to a screen labeled Set up Single Sign-On with SAML. You must first enter some required dummy values into Section 1 before we can proceed. Click on the Edit button for Section 1.

This brings up the Basic Saml Configuration form. Enter a dummy URL into the values for Identified (Entity ID) and Reply URL (Assertion Consumer Service URL). The actual values does not matter as long as Azure accepts them. We will go back and edit these fields later on.

Save and close the form and go back to the Set up Single Sign-On with SAML page.

In section 3, download the Federation Metadata XML which will be used to create the configuration on the Iconik side.

Iconik configuration

Now, switch to another tab in your browser and log into Iconik.

Go to Admin -> Settings -> Identity Providers and select NEW IDENTITY PROVIDER.

This will open a popup where you can upload the XML downloaded in the previous step. This will automatically configure Iconik with the correct settings for Microsoft Entra ID. You can change the name of the Identity Provider but leave the other settings as they are.

Finalize the creation and then open the settings for the newly created Identity Provider. On the left-hand side of the screen you will see a list of URLs. These will be used to configure the Microsoft Entra ID side of the integration.

Azure SAML Configuration

Now switch back to the Azure tab and go back to the Set up Single Sign-On with SAML page if you have navigated away from it.

Open section 1 Basic SAML Configuration again. You will have to copy the settings from Iconik into Azure. On the Iconik Identity Provider Settings page, you can copy the values by clicking the little icon next to the text url.

• Copy Entity ID url from Iconik into the field labeled Identifier (Entity ID) in Azure.
• Copy Assertion Consumer Service url from Iconik into the field labeled Reply URL (Assertion Consumer Service URL) in Azure.
• Copy Logon URL from Iconik into the field labeled Sign on URL in Azure.
• Copy Single Logout Service from Iconik into the field labeled Logout Url in Azure (this is optional and only required if you want Iconik to log the user out from Microsoft Entra ID when they log out from Iconik).

Finally, save the settings.

Next, open section 2 User Attributes & Claims. In this section you need to change the attribute Azure sends as the Unique User Identifier. By default, this is a generated identifier but Iconik expects an email address as the identifier. Change the value for Unique User Identifier (Name ID) to user.mail. The other settings can remain set to their defaults.

Configuring Group Membership

If groups are configured in Entra such that they match the names of Teams or Role Groups in Iconik exactly, Iconik Teams and Role Groups can be automatically assigned to users when they sign in through Entra.

Additionally, if a user was previously added to a group in Azure, and are now no longer are a member of the group, then they will also be removed from the Group/Team/Role Group in Iconik when they log in. 

 

On Premise Active Directory Groups

If groups are synced to Microsoft Entra ID from an on-premise Active Directory then you can set the group Source Attribute to be sAMAccountName. This will make sure Azure sends the group name rather than the group identifier, which Microsoft Entra ID sends as the default. 

Cloud Active Directory Groups

If the group is a Cloud group in Azure then you will need to assign that group to the app. Navigate to Manage - Users and Groups and select + Add user/group. From there, add the groups you've created to map to Iconik

If you are unable to add a group due to your license type, see Configuring mapping via the API.

Once the group has been assigned, navigate back to the Single Sign-On configuration page and edit the Attributes and Claims. Add a new group claim and select the following:

Make sure that the "Emit group name for cloud-only groups" is enabled and save the claim

 

Configuring Mapping via the API

If you are unable to assign groups to your Entra app due to your license type, you can map the group object ID to a group in Iconik via the Iconik API. To do so, follow these instructions:

1. Navigate to your Group in Entra and make note of the Object ID: 

2. Navigate to the corresponding group in Iconik, and make note of the Object ID:

3. Click on your profile icon in the top right corner and then Developer Docs and API. (It is recommended that Owner users complete the following steps to ensure correct permissions)

4. In that tab, paste in the following: https://app.iconik.io/docs/apidocs.html?url=/docs/users/spec/#/default/post_v1_groups_mappings_

5. Click on the "Try it Out" button. You should see an app-id and auth-token automatically filled in. If you do not see these values, you will need to create an application token tied to an owner user.

 

6. Fill in the request body like so:

{
  "group_id": "iconik_group_id",
  "name": "entra_group_id"
}

For example, if a Iconik Group/Role/Team ID is: 25d15fbc-29e4-11f1-b095-76e14dcd3389

And the Group ID in Entra is: 361546f9-d9c8-40e2-b369-d900489e9e8b

The values should be set to:

{
  "group_id": "25d15fbc-29e4-11f1-b095-76e14dcd3389",
  "name": "361546f9-d9c8-40e2-b369-d900489e9e8b"
}

7. Click Execute to make the API call. You should see a 201 response:

The group is now mapped correctly to the team/role group/group object in Iconik.

 

Test the Configuration

You should now be able to test the Azure Login at the bottom of the Set up Single Sign-On with SAML page.

You should now be logged into Iconik.