SAML with ADFS

Overview

Microsoft Active Directory Federation Services (ADFS) has had support for SAML 2 integrations since ADFS v2.0. Integrating ADFS with IE's applications requires configuration in ADFS and also in the specific IE application that is being used. If more than one IE's application is being used, then the integration needs to be completed for each application.

Configuring the SAML IdP (ADFS)

In this scenario, ADFS will be acting as the SAML identity provider (IdP). To configure an ADFS Relying Party Trust (ADFS's term for a service provider), you'll need the SP (service provider) metadata from IE.

Create the Relying Party Trust

To complete the IdP configuration, in ADFS we need to make ADFS aware of the relying party:

1. Navigate to the Relying Party Trust node.

2. Click Add Relying Party Trust... in the Actions pane.

3. If you are prompted about the application is "Claims aware" or not, choose Claims aware.

4. In the Select Data Source step, select the Import data about the relying party from a field radio button, Browse... to the metadata file provided by IE, and click Next.

5. On the next step, enter a desired name into Display Name. This is a free form field, but it is recommended to enter the Innovative Educator's application name.

6. If prompted about an access control policy, choose Permit everyone, unless you have a reason to choose something else.

7. Finish up the wizard.

ADFS now knows about IE's application.

Releasing user attributes

We need to instruct ADFS to send some information about the user to the SP.

1. Select the newly create relying party trust, and select Edit Claims Issuance Policy... from the Action pane.

2. From the Edit Claim Issuance... dialog, click Add Rule...

3. Add AD Attributes attribute definition:

   1. From the Add Transform Claim Rule Wizard, select Send LDAP Attributes as Claims, and click Next.

   2. In the Claim rule name field, type AD Attributes.

   3. In the Mapping of LDAP attributes to outgoing claim types, add the following entries:

      1. Given-Name -> firstName

      2. Surname -> lastName

      3. E-Mail-Addresses -> email

      4. Optional data to be associated with the user -> ref1

      5. Optional data to be associated with the user -> ref2

      6. Optional data to be associated with the user -> ref3

   4. Click Finish to create the rule.

   5. Add the LicenseIds attribute definition:

      1. From the Add Transform Claim Rule Wizard, select Send Claims Using a Custom Rule, and click Next.

      2. In the Claim rule name field, type licenseIds.

      3. In the Claim rule field enter the following string: => issue(Type = "licenseIds", Value = "<licIds>");

      4. Replace the string, <licIds> with the value provided by Innovative Educators.

      5. Click Finish to create the rule.

Configuring the NameId (Name Identifier)

The Name Identifier is the unique ID that will identify SAML users coming from the IdP (identity provider).

Requirements

• Must be unique across the instance: This value of the NameId must be unique across all learners of every client in an instance. This means that if you share an instance with other clients (almost everyone), then your ID must not clash with other client's learners. Some good options include:

  • Email Addresses

  • Appending the school domain name to a name or ID

  • Or utilizing an ID random enough to sufficiently collision resistant

Recommendations

• Use an ID that doesn't change: Since this value used to sync learner to their accounts or create a new account if one doesn't exist for a learner, it's recommended that this value be from a source that doesn't change. If the value does change, then the learner will receive a fresh account upon authenticating and will lose all previous progress.

  • Email Address as NameId will suffice : Sending an email as the NameId can cause the problem mentioned above when a learner's email changes due to a name change. That said, email addresses are used by many clients without much headache. Though it isn't the "perfect" option, we considered it "good enough".

  • Unique IDs are a better option: If available, an ID with sufficient randomness to be collision resistant, or appending a domain or school name to less random ID, has the benefits of being both unique and unchanging.

Using sAMAccountName for NameID (optional)

1. Add the Get Stripped sAMAccountName attribute definition:

   1. From the Add Transform Claim Rule Wizard, select Send Claims Using a Custom Rule, and click Next.

   2. In the Claim rule name field, type Get Stripped sAMAccountName.

   3. In the Claim rule field enter the following string: c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => issue(store = "Active Directory", types = ("urn:strippedaccountname"), query = ";sAMAccountName;{0}", param = c.Value);

   4. Click Finish to create the rule.

2. Add the Transform Stripped sAMAccountName to Name ID attribute definition (ensure that this entry is ordered after the Get Stripped sAMAccountName attribute definition):

   1. From the Add Transform Claim Rule Wizard, select Send Claims Using a Custom Rule, and click Next.

   2. In the Claim rule name field, type Transform Stripped sAMAccountName to Name ID.

   3. In the Claim rule field enter the following string: c:[Type == "urn:strippedaccountname"] => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified");

   4. Click Finish to create the rule.

3. Click OK to close the Edit Claim Issuance... dialog.

Dialog Box Examples

Logging In

Users can access the SSO login by visiting the SP initiated URL. This URL is typically provided by IE, but you can see construction documentation below for more details.

• https://<ie product domain>/access/saml/login/<client-slug>

• The ie product domain is the domain of the particular IE product being accessed

• The client-slug is the shorthand id for referencing you (the client).

• Example: https://www.go2knowledge.org/access/saml/login/abcdefg