Microsoft Active Directory Federation Services

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

Roles

These are the roles that are needed:

• Owner

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.

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.

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

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.

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.

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.

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.

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.

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 Send LDAP Attributes as Claims and click Next.

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.

Select the Transform an Incoming Claim template.

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:

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 (legacy), Teams & Role Groups

Group membership can be imported as claims from AD FS, but Groups (legacy) or Teams and Role Groups will not be automatically created in iconik. You will have to manually create Groups/Teams/Role 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/Teams/Role 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.

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.

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.

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.

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.