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