Roles

These are the roles that are needed:

  • Admin

Microsoft AD FS

Active Directory Federation Services is the SSO offering from Microsoft which allows for SAML 2.0 integration with Active Directory.

iconik configuration

To configure iconik with AD FS you need to start by downloading the metadata XML from the AD FS IdP. This document from the url https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml for example via this command:

wget https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml

This file contains the public information about the AD FS IdP which is needed to setup iconik as a SAML Service Provider. You can then POST this to iconik via the https://app.iconik.io/API/auth/v1/auth/saml/idp/ endpoint. This will create the IdP object in iconik. You can also use the REST API reference to configure this.

The response to this query will contain a metadataService url on the form https://app.iconik.io/API/auth/v1/auth/saml/metadata// which you can download the SP metadata from. This can be used to configure the AD FS IdP. Save the contents of this url to a file named iconik-sp-metadata.xml

AD FS configuration

This guide assumes your organization already has AD FS installed and configured. The initial setup of AD FS is outside the scope of this guide, and the guide assumes you have familiarity with configuring AD FS.

Start by opening the mmc console and add the AD FS Management snap-in.

AD FS MMC snap-in

Select the Relaying Party Trust folder and click Add Relaying Party Trust. This brings up the Add Relaying Party Trust Wizard where you can add a new Relaying Party.

Add Relaying Party Trust

Select Claims aware and click Start. This brings you to the Select Data Source panel.

Select Data Source

In this step you need to upload the iconik-sp-metadata.xml file you obtained in the iconik configuration step. Select Import data about the relaying partyfrom a file and browse to the local copy of the SP metadata XML. Click Next to proceed with importing the XML file into AD FS. This brings you to a wizard step where you can select the display name.

Select Display Name

The default will be app.iconik.io but you can change this to any text you want to identify this integration by. You can also add your own notes about the integration. The next step will allow you to select which users in your directory should have access to the iconik integration.

Choose Access Control Policy

You can select Permit everyone to allow or select a more restrictive policy depending on your business use-case. Note that this only controlls who is allowed to log into iconik via the SAML integration. It does not control which resources the user has access to within iconik. Next you will be able to review the settings before adding the Relaying Party Trust.

Ready to Add Trust

No changes are required on this screen, but you can use this to modify any choices you made earlier if you wish. The final step in the wizard is to finish.

Finish

Make sure the Configure claims issuance policy for this application is checked as that is required to propagate the required user information from AD FS to iconik. Once you click Close a new wizard is opened.

Edit Claims Issuance Policy

Here you are going to add two rules, one which sends firstname, lastname and email address from the Active Directory to iconik and a second rule which also transforms the email address into the NameID attribute to identify it as a username. Start by clicking Add Rule.

Select Rule Template

Select Send LDAP Attributes as Claims and click Next.

Configure LDAP Attributes

On the next page, name the rule iconik attributes and select Active Directory as the Attribute store. At a minimum you need to send the following outgoing claims: Given-Name, Surname, E-Mail-Addresses. These attributes are required by iconik in order to create the user. Other attributes can be sent as claims but will be ignored. Click Finish and then add a second rule.

Transform an Incoming Claim

Select the Transform an Incoming Claim template.

Transform E-Mail to NameID

Name the rule Email as NameID and then select E-Mail Address as Incoming claim type, Name ID as the outgoing claim type and Email as the Outgoing name ID format. Select Pass through all claim values to copy the email unmodified as the NameID. Click on the Finish button.

The rules list should now look like this:

Rule List

At this point, users will be able to log into iconik using their AD FS login, but no group memberships will be propagated to iconik.

Groups

Group membership can be imported as claims from AD FS, but groups will not be automatically created in iconik. You will have to manually create groups with the same name as the group in your Active Directory and when the user logs in, they will be assigned to the corresponding groups in iconik.

In order to import group membership from AD FS to iconik you will have to set up three custom rules in the Claim Issuance Policy. Start by adding a Custom Rule.

Store DN

The first rule is used to store the Active Directory Distinguished Name (the unique identifier) for the user. This will not be sent to iconik and is only stored temporarily inside AD FS in order to allow lookup of the group membership.

Store DN

Add a Custom Rule with the rule text:

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
 => add(store = "Active Directory", types = ("http://contoso.com/UserDN"), query = ";distinguishedName;{0}", param = c.Value);

This will store the user's distinguishedName as the custom type http://contoso.com/UserDN. Next, we'll add a rule to store the groups which that user is a member of.

Store Group Membership

In this second rule, add the following text:

c1:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
 && c2:[Type == "http://contoso.com/UserDN"]
 => add(store = "Active Directory", types = ("http://schemas.xmlsoap.org/claims/Group"), query = "(member:1.2.840.113556.1.4.1941:={1});cn;{0}", param = c1.Value, param = c2.Value);

This will store all the groups the user is a member of in the temporary store.

Finally, add a rule which sends all the groups as claims to iconik.

Send Groups as Claims

Add the following rule text for this rule:

c:[Type == "http://schemas.xmlsoap.org/claims/Group"]
 => issue(claim = c);

This will send all the groups the user is a member of to iconik. You can tweak these rules to limit which groups are sent as claims but that is outside of the scope of this article.

Learn more