Single Sign On

Active Directory Federation Services 2016 (ADFS 2016)


Initial setup

Prerequisites

1. A fully installed and operational AD FS 2016 server

You must have AD FS 2016 (4.0) fully installed and running as an Identity Provider. This includes having valid certificates installed, and having the AD FS server connected to your Active Directory domain. These instructions do not cover setting up AD FS itself or installing certificates, however there are several guides published on the Internet. Note that if you use 12 month certificates you will need to update them every year and follow the instructions at the bottom of this article to update the Skills Base configuration accordingly.


2. A local Skills Base Administrator account

You will require a local Administrator account in Skills Base. A local account has a local password stored within Skills Base and so can be accessed even when Single Sign On services are unavailable. This is important in case the SSO integration breaks and you become unable to log in via Single Sign On. Note that a local account can also be accessed via SSO as long as the email address in Skills Base exactly matches that in your IdP.


Step 1 - Download the Skills Base metadata file

Download the Service Provider metadata file from Skills Base which will be used to provide your AD FS server with all of the information it needs to know about Skills Base.

  1. Log in to Skills Base as an administrator
  2. Click the "Admin > Authentication" menu item
  3. For "Single Sign On", select "SAML 2" from the drop down list
  4. Click the link that states "Download the Service Provider (SP) metadata for this instance" and save the resulting file which you will use to configure AD FS in the next step.


Step 2 - Set up a Relying Party Trust in AD FS

In this step we provide your AD FS server with the information it needs about Skills Base by using the Service Provider metadata file that we downloaded in step 1.

  1. Under AD FS click the "Relying Party Trusts" folder
  2. In the "Actions" list on the right-hand side, click "Add Relying Party Trust"
  3. Select "Claims aware"
  4. Select "Import data about the relying party from a file"
  5. Select the metadata file you downloaded from Skills Base in the previous step
  6. You may receive a warning stating "Some of the content in the federation metadata was skipped because it is not supported by AD FS". It's safe to ignore this warning.
  7. For "Display Name" enter "skills-base.com"
  8. Choose an appropriate access control policy based on the needs of your organization and complete the wizard.
  9. Ensure "Configure claims issuance policy for this application" is ticked and click "Close"


Step 3 - Edit the Claim Rules

Here we define claim rules that detail the attributes that are required by Skills Base and which must be provided by AD FS upon each sign on.

In the "Edit Claim Issuance Policy" window for the Relying Party Trust that you just added:

  1. Click "Add rule"
  2. Select "Send claims using a custom rule"
  3. Give the rule the name "Create transient user ID"
  4. Enter the following into the "Custom rule" field and then click "Finish":
c1:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"] && 
c2:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationinstant"]
 => add(
       store = "_OpaqueIdStore", 
       types = ("http://mycompany/internal/sessionid"), 
       query = "{0};{1};{2};{3};{4}", 
       param = "useEntropy", 
       param = c1.Value, 
       param = c1.OriginalIssuer, 
       param = "", 
       param = c2.Value);
  1. Click "Add rule" again
  2. Select "Transform an incoming claim"
  3. For "Claim rule name" enter "Send email as NameID"
  4. For "Incoming claim type" enter "http://mycompany/internal/sessionid"
  5. For "Outgoing claim type" select "Name ID"
  6. For "Outgoing name ID format" select "Transient Identifier" and click "Finish"
  7. Click "Add rule" again
  8. Select "Send LDAP Attributes as Claims"
  9. For "Claim rule name" enter "Send attributes"
  10. For "Attribute store" select "Active Directory"
  11. Set the mapping table as follows and then click "Ok":
LDAP Attribute Outgoing Claim type
E-Mail-Addresses E-Mail Address
Given-Name Given Name
Surname Surname


Step 4 - Download your AD FS IdP metadata file

We need to now download the Identity Provider metadata file from your AD FS server which contains all of the information that Skills Base needs to know about your AD FS server.

Your metatdata file is generally available by opening a web browser and appending the following after your AD FS domain:


/federationmetadata/2007-06/federationmetadata.xml


For example: https://adfs.example.com/federationmetadata/2007-06/federationmetadata.xml


Note that you must use https to access this, and not http. Once you have the file, save it somewhere for use in the next step.


Step 5 - Configure Skills Base

We will now provide Skills Base with all of the information it needs to know about your AD FS server by giving Skills Base your Identity Provider metadata file downloaded in the previous step.

  1. Log in to Skills Base as an administrator
  2. Click the "Admin > Authentication" menu item
  3. For "Single Sign On", select "SAML 2" from the drop down list
  4. Next to "Metadata validator" click "IdP metadata validation tool »"
  5. Using a text editor such as Notepad, open the file that you downloaded from your IdP. It's important to use a plain text editor as opening the metadata file with a web browser is not reliable for copying the contents,
  6. Copy the contents of the metadata file and paste into the text box in Skills Base.
  7. Click "Validate" to ensure the metadata is valid. Check any certificates along with their expiry dates.
  8. If the metadata validates ok click "Back to settings"
  9. For "Single Sign On", select "SAML 2" from the drop down list
  10. Click the "Set up now" button
  11. Paste the metadata into the "IdP metadata" text box in Skills Base.
  12. Click "Save"


Step 6 - Test

The integration is set up. Now it's time to test it.

  1. Log into Skills Base using your shortcut link. You should be redirected to your AD FS server and presented with an authentication prompt.
  2. Log in using your organizational Active Directory credentials


Troubleshooting

If an AD FS page displays an error

If you are receiving an error message from your AD FS server, you can check the AD FS error log by:

  1. Opening the Windows Event Viewer on the AD FS machine
  2. Expand "Applications and Services logs"
  3. Expand "AD FS"
  4. View the "Admin" log.


If a Skills Base page displays an error

Please read the notes about your server's clock on the Single Sign On page if you receive one of the following errors from Skills Base:

  • "Received an assertion that is valid in the future. Check clock synchronization on IdP and SP."
  • "Received an assertion that has expired. Check clock synchronization on IdP and SP."
  • "Received an assertion with a session that has expired. Check clock synchronization on IdP and SP."


Updating the configuration

Occasionally it will be necessary to update the configuration either on the AD FS side, or the Skills Base side. Either way, if one needs to be updated, both do as they are completely dependent. The most common need to update configuration is when certificates are renewed.

For step-by-step instructions on updating the configuration, see: Updating AD FS configuration