Skip to main content
Skip table of contents

ADFS step by step

If you have never configured a relying party trust before in ADFS, the interface can seem a strange and mysterious place. Here is a step by step guide to help you if this is your first time. Screenshots are from a version without decoration, so don't worry if the dialog boxes on yours are a different colour.

  1. In current versions of Windows Server you can install ADFS from the services menu (2012 onwards). If you're still using Windows Server 2008 in any flavour, do not turn on the ADFS service via the server manager, Microsoft's own recommendation is to download and install version 2. 

  2. Log into your sever and launch the "AD FS Management" console

  3. In the tree on the left, expand Trust Relationships and click on Relying Party Trusts

  4. From the Actions menu or panel, select Add Relying Party Trust...

  5. If the wizard asks about 'claims aware', say yes otherwise just click the next button on the first page of the wizard. If you're asked about multi-factor authentication it's best to leave that off for now to limit the things that can get in the way during the initial set-up (you can go back and turn it on later if you wish).

  6. Import data using the metadata address of your OpenAthens connector (from the relying party tab) - e.g. 

    1. If your server cannot connect directly, download the metadata from a location that can, copy the file over and use the upload option instead. 

      Metadata download help

      In most browsers 'File > Save as' will download the metadata properly, but if that is problematic the fallback is to right-click on the page and select view source. Copy and paste what comes up into a text editor and save it with a .xml file extension.

      How you transfer that file to somewhere your ADFS server can read from is something you may have to take up with your IT team, but it's worth trying to copy and paste the file through a remote desktop session if that's what you're using.

  7. Click next through the rest of the wizard, giving it a name but otherwise accepting the defaults until you get to the last page. The defaults can be changed later if you do not want all users to be authorised to log into OpenAthens, or wish to use any additional features. 

  8. On the last page there is the option to go straight to editing claim rules. Leave that ticked and click finish.

  9. The Edit Claims Rules dialog box will open. Click Add Rule...

  10. In the wizard, select Send LDAP Attributes as Claims and click Next

  11. In the Edit rule box give it a name and select your attribute store, usually Active Directory

  12. In the Mapping box, use the drop down to select the source LDAP attribute and next to in under Outgoing Claim Type, give it a name without spaces that will be unique such as oa_unique.

    1. you will need at least one claim to be released to be used as the unique user identifier and one for the display name. 
      1. The claim for the user ID must be unique to the user for at least their time in your system and ideally will be unique to that user for all time. objectSid and objectGuid are good choices.
      2. The claim for the display name does not need to be different, but it would help if it were user readable. Display-Name is a popular choice.

    2. the 'oa_' bit avoids any possible clashes with names that ADFS thinks are special.

    3. you can use the default names if you like, but these can be long and confusing - e.g. UPN is released as by default. You can see these in the ADFS interface under Service > Claim Descriptions.

    Not every possible LDAP attribute is included in the drop down list. In such cases you would type in the source attribute name on the left instead of selecting it. If you're upgrading from Shibboleth you will often want to send objectSid as the unique identifier as that is what Shibboleth defaulted to using. See also: objectSid and ADFS

  13. Add any additional claims you will need for things like assigning permission sets, display names, user organisation, statistical groupings or passing attributes to service providers (the library will be able to tell you what these are).

  14. Click Apply or OK

  15. Return to the ADFS connector page to complete the set-up in OpenAthens.

Anything to watch out for?

On the older servers you may need to restart IIS if this is the first time ADFS set-up. ADFS 3 and above do not need IIS to be enabled

If you are planning to connect ADFS V2.0 to more than one OpenAthens domain you may need to apply Update Rollup 3:

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.