Configuring ADFS 2.0 for itslearning eLogin.

Introduction

These are instructions for itslearning customers to set up ADFS for integration with itslearning's elogin component.

Prerequisites

• A working ADFS installation.
• Make sure the site is SSL enabled with commercial certificates. Attempts to use self signed certs have been unsuccessful.
• A site on itslearning which has eLogin enabled.
• The site must have users imported through IMS E, IMS ES or CSV, and they must have a SyncID in itslearning that correspond to a claim / attribute exposed via ADFS.

Setting up ADFS 2.0 for use with itslearning elogin

Exchange SAML metadata

Unless already done, you will have to obtain itslearning's metadata, and itslearning will need your metadata.

Contact your itslearning consultant for assistance.

We firstly need to enable a trust relationship between the ADFS service and eLogin. 

1. In AD FS 2.0 Managemetn application, in the console tree, right-click the Trust Relationships -> Relying Party Trusts folder, and then click Add Relying Party Trust to start the Add Relying Party Trust Wizard.
2. On the Select Data Source page, enter a URL to the metadata for elogin or browse to it on the local computer.
3. Select the display name (eg. MyService or elogin), I will assume this is itslearning.com
4. Permit all users to access the relying party
5. Review the settings and click Next, and then Close.
6. Right click on the relying party for elogin under Relying Party Part Trust.
7. Under Advanced, make sure the Secure Hash Algorithim is correct. From R74, elogin supports both SHA-1 and SHA-256, but selected value needs to correspond to the secure hash algorithm specified in the elogin configuration.
8. Click OK to save the changes.

Edit Claim Rules for Relying Party Trust

This step will allow the correct attributes to be retrieved from ADFS

1. The Edit Claim Rules dialog box should already be open. If not, In the ADFS 2.0 centre pane, under Relying Party Trusts, right-click elogin.mydomain.com, and then click Edit Claim Rules.
2. On the Issuance Transform Rules tab, click Add Rule.
3. On the Select Rule Template page, select Send LDAP Attributes as Claims, and then click Next.
4. On the Configure Rule page, in the Claim rule name box, type Get Data.
5. In the Attribute Store list, select Active Directory.
6. In the Mapping of LDAP attributes section, create the following mappings

Itslearning requires one attribute to be set as "NameID". This must be a value that uniquely identifies the user within Active Directory.

In addition, there must be at least one other attribute issued. This attribute must uniquely identify the user in itslearning, and may be the same LDAP attribute as the "NameID"

A typical setup would look like this:

Custom rules

In the event that there is no single field in AD that also exists in itslearning, it will in many cases be possible to create custom rules to transform attributes into something that has been imported to itslearning from the MIS.

A common scenario is the use of eduPersonPrincipalName as an attribute imported from an MIS. This may not exist as a standalone attribute in Active Directory, but have in many cases been created in the MIS using sAMAccountName in Active Directory as a source.

See http://technet.microsoft.com/en-us/library/ee913558%28v=ws.10%29.aspx for more information on the claim rule language.

1. On the Issuance Transform Rules tab, click Add Rule.
2. On the Select Rule Template page, select Send Claims Using a Custom Rule and click Next.
3. In the Configure Rule page, in the Claim rule name box, type Transform samAccountName to ePPn
4. In the Custom Rule window, type or copy and paste the following:

In the above example, @mydomain.com is appended to the samAccountName to generate an ePPn of [email protected] This should be customised to individual customer requirements. (e.g. [email protected]). 

The object-identifier-style uniform resource name (URN) string urn:oid:1.3.6.1.4.1.5923.1.1.1.6 is the formal SAML 2.0 name for the eduPersonPrincipalName attribute—a name that the Shibboleth SP software understands by default.. Elogin also understands this from the web.config file.

Seamless logon with IWA

For the ADFS site in IIS, the default authentication method should be changed to IWA (Integrated Windows Authentication). This will turn off the form based authentication prompt, and login directly to the learning platform. To accomplish this, changes need to be made to the web.config file which is usually located in C:\inetpub\adfs\ls. Look for a section which starts microsoft.identityServer.web and change the section labelled localAuthenticationTypes so that it looks like this

With this configuration, if a Windows PC is logged into the same domain as the Active Directory server, the user will already be authenticated to ADFS upon accessing an ADFS protected resource. Outside of the domain (e.g. from home) authentication will fall back to basic authentication.

Browser Considerations

In order for seamless logins to work, the browser must trust the URI of the ADFS site (e.g. adfs.mydomain.com). The following changes need to be made depending on the browser that is utilized by the end user.

Chrome and Internet Explorer 8 and above

• Open the Control Panel in Windows and choose All Control Panel items in the address bar
• Select Internet Options
• Select the Security tab
• Select Local Intranet
• Click on Sites
• Click on Advanced
• Add the site for the ADFS service e.g. https://*.mydomain.com

Firefox

• In a Firefox browser window enter in the text about:config into the URL bar
• In the search bar type network.automatic-ntlm-auth.trusted-uris
• Choose Modify and enter the domain of the ADFS site e.g. mydomain.com

Troubleshooting

Certificate Management

The ADFS service must be able to read the certificate for the URL it is hosted on  (e.g. https://adfs.mydomain.com). In order to import the commercial certificate correctly into Windows, the following stops should be followed:

Firstly if the certificate is in PEM format it is necessary to merge it with  the private key into a PKCS7 format certificate (PFX file). This can be done using the openssl tool as follows:

Then follow these steps on the Windows Server:

1.) Start the Management Console.

Start --> Run --> MMC

2.) Add the Certificate Management Snap-In for a Computer Account.(Local Computer)

3.) Add the Certificate Mangement Snap-In for a Service Account (ADFS 2.0 Windows Service)

3.) For each of the Certificate Snap-Ins add the PFX certificate in to the Personal store.

4.) Under the Certificates folder within Certificates - Local Computer, right click on the certificate just imported and select All Tasks --> Manage Private Keys

5.) Within the security tab make sure full access is given to the NETWORK SERVICE account.

6.) Click OK and end all MMC snap in dialogues.

An ADFS error is encountered as follows

This usually has two possible explanations:

i.) The ADFS service account does not have access to the private key within the certificate for the site. To correct this make sure the certificate is imported as a PFX file which contains both key and certificate. Also make sure the service account has access to the key by doing the following:

• Start MMC (Start --> Run --> MMC)
• Add the Certificates snap-in for a Computer Account (Local Computer)
• In Certificates, right click the certificate for ADFS and click All Tasks --> Manage Private Keys
• Make sure NETWORK SERVICE has access to the key. If not click Add to add permission. (NETWORK SERVICE is usually the service account used for ADFS 2.0 Windows Services, check in services to be sure )
• Restart ADFS 2.0 Web Services, under the services manager (Run services.msc)

ii) Another program is using the ADFS TCP ports (1500 and 1501). To correct this try the following:

• Launch PowerShell
• Add the AD FS 2.0 PowerShell snap-in:

• Configure the Services net.tcp port via the Set-ADFSProperties cmdlet:

• Confirm the change

• Restart the AD FS 2.0 service in the Services console and then:  Get a WMI object into a $temp variable:

• Set the ConfigurationServiceAddress property to the new net.tcp address using the new port:

•  Write your change back to the object:

• Restart the AD FS 2.0 service in the Services console

The customer's original metadata file can be retrieved from https://adfs.customerdomain.tld/FederationMetadata/2007-06/FederationMetadata.xml or the customer can send it to you.