Versions Compared


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


  • An LDAP server that can be queried from outside of your network.
    • If this is not possible, an ADFS connection might be what you need 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 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

Add the connection

In the administration interface as the domain administrator go to Management > Connections

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

  2. Have your colleague from the IT team complete the form and click add at the bottom.

  3. OpenAthens only permits secure LDAP connections so will require a the root certificate of your server. The status panel will show errors until it is added:

    You can hover over the panel for more details about an error

  4. Switch to the certificate tab and paste in the contents of the certificate file which should look similar to this:

    Code Block
    -----END CERTIFICATE-----
  5. . This will be converted to a summary panel:

    Make sure the Usually these certificates are self-signed, so the one you want has matching issuer and subject lines match and are the root for your server or you will have problems later (e.g. CN=AD, DC=organisation, DC=com). If using third-party certificates, also add the root certificate that the third-party certificate chains to.

  6. Save changes

  7. The status panel will update and should now show success if it did not before

  8. You should be able to use the test authentication button now with your own username and password.


  • 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 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, check both the live and visible boxes and then save. Your new connection should be available on the authentication point in a few seconds.


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

Should you need to show more than one LDAP option, the user will see a drop down list above the credentials boxes. This will contain all LDAP connections set as live and visible.




The name of the connection as it will appear at 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 where OpenAthens can connect to your server. This address will need to be accessible by our services from outside of 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:


Bind password

The password for the user specified in the admin bind

Base DN

The distinguished name of your directory, e.g:



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 attributeThis defaults in AD to be 'sAMAccountName' and in LDAP to 'cn'. It is the value displayed in account lists and in audit. You can choose any attribute.
Unique user attribute

This should be an attribute that will always be unique to that user and 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.

Pseudonymous identifiers are recommended where they are available.

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.


Not live = Can only be used in debug mode.

Live and not visible = Can only be used in debug mode.

Live & visible = production ready. Users will be able to access this login at the authentication point. If you have only one connection it will become the default login whenever 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

Include Page

Example filters

Instead of specifying only a username field, the use of a filter allows compatibility with a greater variety of LDAP structures - e.g. 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.


Connections from us will come from the following IP addresses (535.198189.13671.85 and 8617 and and changes to these would be communicated in advance.


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 identifiers such as objectGUID 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.