Local directory integration for the IT team

Most of the documentation for OpenAthens is aimed at the library user, and from the perspective that they will be creating and managing accounts within OpenAthens. If you are from IT setting up local directory integration, that might not be as useful to you so here is what you need to know from your perspective over and above what is in the set-up instructions.

Why does the library want me to do this?

The short answer is so that they do not need to create and manage a parallel set of user accounts for access to the online subscription content they purchase for your users. Once connected this way, their workload drops considerably as they do not need to create user accounts, reset passwords or delete accounts when a user leaves - all these things are happening anyway with the accounts you are already maintaining and since users are going to forget their passwords less often the more they use them, your workload may even go down a little too.

If you have previously been using something like Shibboleth, your workload will go down considerably.

Basically, the authentication of your users is being done by you but we will handle the job of interacting with service providers.

I have questions about the connector...

The connectors currently available are: ADFS, API, LDAP, SAML and SirsiDynix. As well as the installation docs, for each we have included here some notes which should address most of the technical questions you have:

LDAP

LDAP is a brokered connection and features a login box on our authentication point that accepts your credentials.

• Setup instructions for LDAP
• The admin bind
  
  • Can be limited
  • Must have sufficient privileges to discover the FQDN of any user that should be allowed to access the system.
  • Would benefit from sufficient privileges to view the attributes you want to map to OpenAthens attributes or use for permission set / organisation assignment to make set up easier.
• When users log in:
  • An admin bind is used to discover the FQDN of the user based on your specified username parameter(s).
    
    • You can use the filter to define which field or fields are used for username - e.g. sAMAccountName, mail, either.
  • The user's FQDN and password are used to authenticate the user and to request any mapped attributes from your directory.
• The interaction between us and your directory uses your choice of LDAPS or STARTTLS.
• Connections from us will come from a defined set of addresses (quoted in setup instructions). If these ever need to change we will tell you in advance.

SAML (including ADFS, Azure, Google Workspace and Aperio CAS)

These are all delegated connections and will forward the user to your own login page for authentication. The only difference between them is that SAML has an option to use the NameID as the unique user attribute.

• Setup instructions for SAML (for others, see: Sign into OpenAthens with local authentication systems)
• Only the claims / assertions you choose to send are visible to OpenAthens
• Information is transferred between you and us via the users' browser and SAML. If your source is flagged in your metadata as supporting encryption the information will be encrypted over and above https.
• The unique user identifier...
  • must be persistent and unique amongst current users. If possible it should be unique for all time.
  • is the minimum amount you need to send, but you will need to send more if you want to map attributes or assign permissions based on your own user categorisation.

SirsiDynix

Like LDAP this is a brokered connection so credentials are entered at our authentication point.

• Setup instructions for SirsiDynix
• SirsiDynix's Symphony API is required
• Connections from us will come from a defined set of addresses (quoted in setup instructions). If these ever need to change we will tell you in advance.

API

• Setup instructions for the API and setup instructions for your code.
• The return URL must be a location in your application that can handle the status parameter

Now it is connected, how do I pass attributes to service providers?

Your local connection is used to sign a user into OpenAthens. OpenAthens is used to sign a user into a service provider such as Ebsco or ScienceDirect, so it is OpenAthens attributes that are passed to service providers.

OpenAthens only passes on attributes from our system that are both marked as releasable in the schema editor, and that have also been explicitly released by policy - e.g. your settings might have us telling any service provider if a user were staff or student, but only telling a specified service provider if the user were a Physicist, Doctor or Geologist.

There are two classes of attributes. Some will apply to groups of users whilst others are user-specific - e.g. role and email address.

When you are using a local connector, generic attributes such as roles can be inferred from an attribute you pass without having to map it to an OpenAthens attribute - e.g. ActiveDirectory's memberOf field would usually have some indication if a user were staff or student. User-specific attributes such as names or emails would need to be mapped to an OpenAthens attribute to be usable within the system. There's also a simple setting that can stop OpenAthens saying anything at all to a service provider that isn't assigned to the user (those of you who have used Shibboleth in the past may appreciate that).