LDAP connector

Path to function: Management > Connections > Add > LDAP

OpenAthens can connect directly to an LDAP server so that you do not have to issue personal accounts for your users (you will still need your OpenAthens administrator account). Anything that uses standard LDAP protocols is acceptable, so this method also works well with ActiveDirectory.

As well as the ability to use local accounts instead of maintaining a separate set of credentials, accesses to federated resources that already involve discovery (identifying the user’s home organisation) will take the user directly to your LDAP login at our authentication point. No further discovery is required.

Preparation

Before you start, you need:

An LDAP server that can be queried from outside your network. (If this is not possible, try an ADFS connection instead)
A member of your IT team to supply or enter the connection details (jump to details)
A copy of your LDAP server's certificate (base 64 encoded X.509, often called PEM format). This must be the root certificate, i.e. the subject and issuer are the same. If you are unsure how to get this from ActiveDirectory, see ActiveDirectory certificates
Access to OpenAthens as a domain administrator

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

If you need technical help, consult the relevant software documentation or your IT team. Our support team are also happy to help, but can fully support only the OpenAthens end of the connection.

Add the connection

Log in to the OpenAthens admin area as the domain administrator.
Go to Management > Connections.
Under Local authentication in the left sidebar, press Create. A pop-up opens, showing available types of connector.

Select LDAP and press Configure.

Pop-up window titled 'Add LDAP authentication system'. It contains the editable fields 'Name', 'Description', 'Directory type', 'Server host', 'Server port', 'Connection type', 'Admin bind DN', 'Bind password', 'Base DN', 'Filter' and 'Unique user attribute'. At the bottom of the window are buttons marked 'Add' and 'Cancel'.

With guidance from your IT team, fill in the technical details of the connection.
Press Add to create the connection.

Provide your certificate

Next, upload the root certificate of your server. OpenAthens needs this certificate to secure the connection. Until you upload it, the status panel for the connection will show errors. (Hover over the panel for more details about an error.)

'Directory Status' panel, showing the date last checked and two warnings of potential issues - 'Connection to server' and 'Bind'. There are also buttons marked 'Test authentication' and 'Refresh'.

Go to the Certificates tab.

Certificates tab. It shows some default technical details, including 'Usage', Serial number', 'Issuer', 'Subject', 'Not before', 'Not after' and 'SHA1 fingerprint'. There is also a large text field, currently blank except for the text 'No certificate. Paste certificate into editor and click save changes.' A button marked 'Save changes' is at the top right of the page.

In the large text field, paste the contents of your LDAP server’s certificate file. Usually these certificates are self-signed, so the one you want will have matching issuer and subject lines. The file should look similar to this:

CODE

This information is then converted into the summary shown at the top of the tab, replacing the default values there.

Certificates tab, showing non-default values for the details of the certificate.

If using third-party certificates, also add the root certificate to which the third-party certificate chains.
Press Save changes. The error warnings should now clear from the status panel.

You can now test the connection.

Other configuration options

In the Login Page tab, customise the end-user login page to suit your organisation
Configure permission set rules so that your users are assigned an appropriate set of resources
Configure attribute mappings so that OpenAthens can make use of data available from your LDAP
- OpenAthens will cache these attributes when the user signs in, so changes in LDAP won't be picked up until the next time the user starts an OpenAthens session.

When you're ready to go live, go to the Details tab of the connection and set the Status to Live and Visible. Save your changes. Your new connection should be available on the authentication point in a few seconds.

Testing

Since OpenAthens accounts will still work if entered (see below), some sites are happy to test by setting the connector to Live and Visible for periods of time. You can also use debug mode to make all connections available to you without being visible to your end users.

How to use LDAP alongside OpenAthens accounts or other connections

If this is your only local connection, once you set it as both Live and Visible it becomes the expected way for users to sign into OpenAthens where the system knows that the user belongs to your institution. That means that the user has selected your organisation from a WAYF on a federated resource, or that the system remembers the user having done so previously.

Where the system does not know the user is yours, only the OpenAthens account login will appear automatically, but the user can find your organisation through search. Once the user selects your organisation, they are taken to your connection.

Users from your organisation who have OpenAthens accounts can still sign in by entering their username and password in the same login box as the LDAP account. This may affect your choice of label text.

Should you have more than one LDAP option, the user will see a drop-down list above the fields for entering their credentials. This will contain all LDAP connections set as Live and Visible.

OpenAthens login screen. The heading 'Sign in with your Example Organization account' is followed by three fields - 'Sign in using' (a drop-down list, set to 'Staff'), 'Username' and 'Password'. There is a button marked 'Sign in', and a link that reads 'Problems signing in'.

If you have a mix of LDAP and SAML connections, e.g. LDAP for students and ADFS for staff, the different login methods are presented in an overlay for users to select. If the user chooses a local connection and successfully signs in, their choice will be remembered next time. If the user fails to sign in for any reason, the authentication point will forget their preference and offer a choice of connections again next time. (This prevents users who select the wrong option from getting stuck at a login they cannot use.)

Screenshot. Under the heading 'Choose how to sign in' is a list of options - 'Staff', ADFS connection name', 'OpenAthens LA' and 'OpenAthens'.

In these cases, selecting the OpenAthens option will show the first LDAP connection and the OpenAthens credentials will be accepted there.

Depending on your subscription, multiple connections may incur additional charges.

Fields in the Details tab

Field	Explanation
Name	The name of the connection, as it will appear in our authentication point when there is a choice of connector.
Description	The description of the connection, as it will appear in our authentication point when there is a choice of connector
Directory type	Used to set default values in other places on the form.
Server host	The address at which OpenAthens connects to your server. This address must be accessible outside your network.
Server port	The port that your server uses for LDAP traffic. Standard ports are selected when you change protocol. You can specify a non-standard port if necessary, but this can affect security.
Connection type	The form of security used. StartTLS is the standard but ldaps:// can be chosen if you prefer. The minimum supported version of TLS is 1.2.
Admin bind DN	The full distinguished name of a user that can connect and view all the users you need to authenticate, e.g: `cn=openathens,cn=users,dn=ad,dn=yourdomain,dn=net`
Bind password	The password for the user specified in the admin bind.
Base DN	The distinguished name of your directory, e.g: `dn=ad,dn=yourdomain,dn=net`
Filter	Allows you to specify the username field, plus limitations where necessary. The field you identify as =${uid} will be used as the username in login dialogs.
Display name attribute	This defaults in AD to be 'sAMAccountName' and in LDAP to 'cn'. It is the value displayed in account lists and the audit trail. You can choose any attribute.
Unique user attribute	This should be an attribute that will always be unique to an individual user. It is used in the generation of targetedIDs and statistics. It defaults in AD to 'objectGUID' and in LDAP to 'cn'. If you are migrating from another local authentication system, you may want this to match your old setting. We recommend pseudonymous identifiers if available.
Salt value	The salt used to generate a targetedID for users authenticated by this connection. You might edit this if you are upgrading from Shibboleth so that your users can have the same targetedID value when they change systems. If you set this field to blank, the connection will use the same salt as your OpenAthens accounts. Avoid modifying the salt after you go live, which will change the user identifiers seen by service providers.
Status	Not Live = can be used only in debug mode. Live but not Visible = can be used only in debug mode. Live and Visible = production ready. Users will be able to access this login from the authentication point. If you have only one connection, it will become the default login where your organisation is known (e.g. for any resources where access involves your entityID). Changes to the status usually take effect within moments.
Create local accounts	Automatically: any user authenticated by your system is deemed OK and will be accepted by the system. Manually: only user IDs you have previously uploaded will be accepted by our systems. See how to limit which local accounts can sign in.
Remove local accounts	This setting controls when local account data will be automatically cleared from the system and is the number of days from the last time the account last signed in. Pre-mapped accounts that have not been seen are also cleared. The setting can be from 1 to 365 days and represents the number of complete days that have passed since the date the account last signed in, i.e. does not include the day of the last sign-in in the count. See also: How to modify a local account.

Example filters

Instead of specifying only a username field, the use of a filter allows compatibility with a greater variety of LDAP structures. For example, where including all valid users requires binding to a node that will also include invalid users, the filter can be set to exclude the invalid users.

cn=${uid} - The default LDAP filter using common name as the username.

(&(objectCategory=Person)(sAMAccountName=${uid})) - The Default ActiveDirectory filter uses the Windows login as the username and requires the user to have an object category of person.

See more example filters.

Technical information for your IT team

During set-up and configuration (including testing of mappings):

There is a read-only admin bind to your directory to check status and read the available attributes for mapping

During user authentications:

There is a read-only admin bind to your directory to discover the FQDN of the user based on whichever attribute you have defined as the userID
Once the user's FQDN is known, it is used with the user's password to bind for authentication and request of any mapped attributes

Connections from us will come from the IP addresses 35.189.71.17 and 35.224.184.162. Any changes to these addresses will be communicated in advance.

The admin bind used MUST have sufficient access to search for accounts and read the FQDN of any user account (that should have access).

The admin bind used SHOULD have sufficient access to read all mappable attributes for user accounts so that typeaheads work when setting up mappings and permission set rules.

The only significant difference between StartTLS and ldaps:// in operation is that with StartTLS you only need to listen on one port instead of two.

Anything to watch out for?

AD will truncate sAMAccountName before release if it is over 20 characters. This may affect your choice of unique user attribute.

TLS versions before 1.2 are not supported.

Pseudonymous?

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