Configuring LDAP authentication

Jan 23, 2018

Sobs includes an LDAP option that will authenticate the login details against an LDAP server.

LDAP Servers

Our LDAP option has been tested with OpenLdap, Microsoft’s Active Directory and Novell’s e-Directory.

What happens with LDAP?

With a binding username and password:

  1. You enter in the login screen your regular network login name and password
  2. We establish a connection to the LDAP server
  3. We then attempt to login to the LDAP server using the binding user and password previously supplied
  4. Now we search for the username currently attempting to login
  5. This search is performed by substituting the username into the context
  6. Assuming we locate a particular user in the LDAP server we then authenticate the password entered against this user
  7. Once the password is authenticated we then pull specific values that are mapped from the LDAP data into the Sobs staff record, such as name and email address
  8. If the Sobs staff record did not exist it will be automatically created for an authenticated user with a security of ‘Regular staff member’

Without a binding username and password:

  1. You enter in the login screen your regular network login name and password
  2. We establish a connection to the LDAP server
  3. We then attempt to login to the LDAP server using the username and password supplied
  4. If are able to bind to the LDAP server with this username and password we then assume the user is authenticated
  5. We then retrieve specific values that are mapped from the LDAP data into the Sobs staff record, such as name and email address
  6. If the Sobs staff record did not exist it will be automatically created for an authenticated user with a security of ‘Regular staff member’

Configuring LDAP

If you are operating from the Sobs hosted solution then you will need to allow Sobs to access your LDAP server through your firewall.

  • To establish the Sobs IP address (where the LDAP request will come from) start a DOS or Unix command prompt and type “ping sobs.com.au” this will lookup the IP address of the Sobs server and attempt to ping the server.  You are simply after the IP address of the Sobs server in order to create the rule in your firewall.
  • Identify the LDAP port you will be using, non-SSL is by default 389 and the default that Sobs will use.  If you are using SSL the default will be 636.  Check this with your LDAP server.
  • Normally with LDAP authentication the school will want to use SSL communications between the computers and the web server (and similarly with the LDAP server).  Therefore you should be using the https://sobs.com.au web address on all your links, shortcuts and bookmarks to access Sobs.  Once you start a session with the SSL option the following links will also use this security.
  • Add the rule to your firewall allowing the Sobs server to access your LDAP server on the desired port.
Now you can sign into Sobs (sign in without LDAP authentication this time)
  • Click on the ‘School settings’ link in the Configuration menu.
  • Click on the ‘Authentication’ tab.
  • By default LDAP is disabled, so start by clicking the ‘Edit’ button, top right, and then scroll towards the bottom of the form and you will find a number of LDAP fields.
  • The first field simply labeled LDAP is the main switch for enabling LDAP.  Check this box to enable LDAP
  • If you want to use a ‘Binding user’ to connect to your LDAP server (see notes at the start of this article) then enter the fully qualified name for the binding user.
  • If you are using the ‘Binding user’ then enter the password for this binding user.
  • The LDAP server and LDAP port are how we connect to your LDAP server, you can specify an IP address or a server name for the LDAP server.   The default LDAP port is 389.  If you are using SSL then you will want to specify the LDAP server using the “ldaps://” protocol, for example “ldaps://192.168.1.1” and specify your SSL port for your firewall in the LDAP port number, by default this would be 636.
  • Lastly you will find a number of ‘LDAP map…’ fields.  Specify in these fields the fieldname used in your local LDAP system for each item.  Typically email is ’email’, however surname is commonly ‘sn’.  Check with your LDAP server for the fieldnames of these values

Now click the ‘Save’ button to save your changes.

With LDAP enabled, scroll down the page to view the LDAP settings, you should also find a link to add an LDAP context.

  • Click the ‘Add’ link to add a new LDAP context
  • When adding a context your entry should include the token “{username}” as this will be replaced with the login name of the staff member logging in when searching the LDAP user database.  See the details below for configuring your context.
Lastly we want to configure a Sobs administrator account so that we don’t lock ourselves out of the Sobs configuration.
  • Click on the ‘Staff’ link in the Configuration menu
  • Click ‘Add user’ from the top right of the page
  • Add the details for an administrator account (choose a username that is not associated with any account in your LDAP server).
  • Ensure you select the ‘Sobs administrator’ security, so that this account will have access to modify these settings when necessary.
  • When adding the details check the box for ‘non-LDAP account’ (when logging in with this account the system will not authenticate the user with the LDAP server)

 

Now you can logoff and attempt to login using an LDAP account.  If your login fails you can log back in using the ‘non-LDAP’ account you configured above, make changes as required and then try the login process again.

Configuring your Context (for Microsoft AD)

Microsoft make this a little complicated, and if you have a basic defaults setup for your AD then this is sure to help.  Firstly, you will need a binding user.  With the binding user you should be able to copy and paste their context into the binding user field – this will very likely be using the “CN” naming context .  Here’s an example:

Binding user: CN=LDAP Staff User,OU=Staff Accounts,OU=All Staff,OU=All Users,DC=acme,DC=edu,DC=au

Of course you need to specify the password for this user in the Binding user password field.

Secondly we come to the context.  In this case we must use the”sAMAccountName” naming context.  The sAMAccountName in this case is the one the staff login with, and when we replace that in the context string and perform a search we will locate the staff member.  An example of the context to use:

Context: sAMAccountName={username},OU=Staff Accounts,OU=All Staff,OU=All Users,DC=acme,DC=edu,DC=au

 

Configuring your Context (for all other LDAP servers)

This is often the most difficult part of configuring your connection and often requires a process of trial and error until the correct context is identified.

Firstly, ensure you have your context strings set correctly.  They should contain one instance of the text “{username}”, for example:

cn={username},ou=Staff,o=Acme
cn={username},dc=acme,dc=edu,dc=au
sAMAccountName={username},ou=Teachers,dc=acme,dc=edu,dc=au

Remember, the “{username}” is a text token that must exist in the above strings.  When we are processing a user logging in we will replace this token with the username of the person logging in, so the resulting cn=john.smith,ou=Staff,o=Acme should identify a unique user within your LDAP server.

Firstly you need to identify which field the login name is stored in.  Sometimes, this is “cn” however depending on the LDAP configuration it can also be “uid” or some other value.  Checking your LDAP server should show a distinguishing name value, check for the login name in this string and the field label it is identified by.

Secondly you need to determine which context path to take.  Sometimes you will achieve the context via the ‘organisational unit’ and ‘organisation’, eg ou=Staff,o=Acme.  In other cases you will define the context with the ‘domain context’, eg dc=acme,dc=edu,dc=au   It is generally best not to mix these two types, if you are able to get a context working using the organisational parameter then don’t mix this with domain context parameters, as in my experience I have not found that the two work together well.

Start with generic entries (ie less parameters) and work your way through to more specific entries once you have some broad access options working.  For example, trying “cn={username},dc=acme” maybe a generic option, or “cn={username},o=Acme” as another example.  If you manage to get one of these to work then you can add other parameters to narrow the collection of staff who will be able to login through this point.  For example, if you just left “cn={username},o=Acme” as the context this potentially would allow students with network logins to access your Sobs system.  Adding the “ou=Staff” limits the context to staff at Acme.

Also, remember you can add multiple context at one time, so configure a number of combinations at once and the system will try one context after the other until it achieves a result.

 

Changes to the Sobs IP address

Every 2-3 years we will replace the Sobs server with a new machine.  Each time we do this the IP address of the Sobs server will change.  As part of the process of changing the server we will contact each school using LDAP or SAML configurations and ensure that they are aware of the impending IP change.  In that case the school can add the rule to their firewall for the new IP address.  When the service switches over from the old IP to the new IP there will be no interruption to the staff.  Similarly after the changeover we will again contact each school and notify them the change has been made and the firewall rule for old IP address can now be removed.

 

Help error messages

There are lots of “helpful” messages from LDAP.  For in-house systems you should enable your PHP logging for Sobs – the messages will appear in the error log and will show success or failure at each step of the authentication process.  If you are using the hosted system then use the ‘Contact us’ page on the website to ask for copies of the error messages being generated (you may like to ring us prior to starting your LDAP configuration to ensure we will be available to respond with these messages in a timely fashion).