Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Before you start you will need:

  • An Active Directory server with Windows Server 2008R2 or better running ADFS v2.0 or above installed and configured.
  • A member of your IT team to configure ADFS and supply the ADFS metadata.
    • Ideally an externally accessible URL for your ADFS metadata, but failing that copy of the metadata as an XML file
  • All users to be in your directory
  • Access to the OpenAthens administration area at the domain level

If you are migrating from an alternative IdP such as Shibboleth, also see: Migrating from your own IdP

If you're unsure about anything or get stuck, we're happy to help. Hit the support link in the top right of the admin area to get through to your local support guys.

Add the connection in OpenAthens
Anchor
OpenAthens
OpenAthens

...

  1. Click the add button on the left and select ADFS



  2. Enter the ADFS metadata URL or upload the xml file as supplied by your IT team.

    1. The metadata URL is typically something like https://YOURDOMAIN/FederationMetadata/2007-06/FederationMetadata.xml and would need to be accessible outside of your network.

  3. Set the user identifier field to match the claim you will be sending as the user identifier. This can be changed later, but needs to have a value to save the page.

  4. Set the display name to match the claim you want to use - if you are only sending one claim, you can set this the same as the user identifier. Again this can be changed later, but needs to have a value to save the page.

  5. Do not set it as default at this time.

  6. Save changes

  7. Go to the relying party tab and make a note of the metadata address displayed there. You will need this when you add OpenAthens to ADFS.
The detail fields displayed are
FieldExplanation

Display name

The name of the connection as it will appear at our authentication point when there is a choice of connector. Defaults to the name specified in the ADFS metadata

Metadata URL

Where the ADFS metadata is published. Populated only when metadata is loaded from a URL, it allows easy updates to the connection if your ADFS system changes.

EntityID

The entity identifier of your ADFS instance, typically http://YOURDOMAIN/adfs/services/trust. Drawn from the ADFS metadata.

SSO endpoint

The login address, typically https://YOURDOMAIN/adfs/ls/. Drawn from the ADFS metadata.
Display name attributeThe claim you specify here supplies the value displayed in account lists and audit where you would normally see the OpenAthens username. DisplayName is a common source but it does not have to be different from the Unique user attribute claim.
Unique user attribute

The claim you specify here must supply a value unique to the user within the current user set and should supply a pseudonymous value unique to that user for all time. This is used by the system to tell users apart and also used in the generation of targetedIDs and statistics. It does not have to be the username entered at your login point. ObjectGUID is a popular choice.

Status

Not live = connection can only be used in debug mode. The visibility and default flags are ignored.

Live and visible (if this is the only local connection) = connection can only be used in debug mode.

Live and visible (if there are multiple live and visible connections) = users are offered a choice of connections, including this one. There is a domain preference to include OpenAthens accounts or not.

Live & visible & default = This is your only login option and users will be sent directly to your login whenever the organisation is known. A successful authentication will tell the authentication point to remember that location. A failed authentication will clear that setting. Debug mode will not show other login options.

Changes to the status usually take effect within moments.

Create local accounts

Automatically - any user authenticated by your system and passed back to us is deemed ok and will be accepted by the system

Manually - only user IDs you have previously uploaded via the list page will be accepted by our systems

Remove local accounts

Include Page
_autoclearcachedaccounts
_autoclearcachedaccounts

Salt value

The salt used to generate a targetedID for users authenticated by this connection.

You might edit it if you were migrating from something like OpenAthens LA to MD so that your users can have the same targetedID value when they change systems. If you set it to blank the connection will use the same salt as your MD accounts.

Modifying this after you go live will change the identifiers seen by service providers for your users... which is rarely desirable.

...

  • Permission set rules so that your users as assigned an appropriate set of resources
  • Attribute mappings so that OpenAthens can make use of data available from your LDAPdirectory
    • OpenAthens will cache these attributes when the user signs in, so changes in ActiveDirectory won't be picked up until the next time the user starts an OpenAthens session.

When you're ready to go live, check both the live and visible boxes and then save. Your new connection should be testable a few seconds later.

...

Certificates - allows you to add a second certificate. Used when you need to change a server certificate on AD and want to minimise downtime for your users.

Advanced - Allows you to make several changes that are rarely necessary:

  • switch between SAML versions should you

...

  • have a source that can only handle the older SAML 1 profile
  • switch the profile from Redirect to Post if your source insists on it
  • enable signing of authentication requests (SHA-1 or SHA-256)

...

  • if your source requires it 
  • enable the SAML forceAuthn option (forces your local source to re-authenticate any time the user is sent there - e.g. where users can have multiple affiliations within a consortium and your SAML source's session management makes it difficult for them to change).

Anything to watch out for?

When you use the refresh metadata button it will update everything in the connection with values from the metadata including endpoints , names and certificates. This will also undo any manual changes you have made on the advanced tab. The metadata URL can be removed to guard against this if you chooseIt won't change the name or any options on the other tabs.

If for any reason you have locked your ADFS system down to use TLS versions earlier than 1.2, we're going to reject the connections and it won't work.

Pseudonymous?

Pseudonymous identifiers are recommended for the unique user attribute to avoid potential problems with data protection legislation as that identifier will live on for a time in the audit trail after other mapped attributes are cleared.