Central Authentication

Introduction

For large, distributed GNU Health installations, such a network of public hospitals, you might want to consider a central user authentication model.

Under this method, the users and their login credentials are managed centrally, so it’s easy to create, modify, and/or revoke them when necessary.

The central authentication model in GNU Health is quite flexible, allowing different roles per health facility. For example, a health professional can work in two different health centers. Dr. Cameron Cordara works in the morning as a family medicine physician at GNU SOLIDARIO Hospital, and in the afternoon, she cooperates with the social workers, meeting with the community at the local primary care facility. Two different roles in two different centers, yet one single person and one single login.

Note: This documentation is based on a installation under FreeBSD and OpenLDAP, but it should work fine on other Free/Libre Operating Systems, such as GNU/Linux . There are also many configuration and deployment options, such as Public Key Infrastructure (PKI), LDAP replication, etc… that are not covered in this introductory, conceptual document.

Components

  • OpenLDAP server (slapd)

  • Tryton server modules : trytond_ldap_authentication

Central Authentication Workflow

  1. The health professional enters the username / password at the login prompt.

  2. The credentials are checked against the OpenLDAP server.

    • Scenario 1: The user exists in the OpenLDAP database. If the password provides is correct, then she logins with her local authorization profiles. If she enters an incorrect password, she will be get the login prompt again.

    • Scenario 2: The user does not exist in the OpenLDAP database. The credentials are checked against the local GNU Health database at the health facility.

    • Scenatio 3: The OpenLDAP server is unreachable (network outage, server down, … ). Same rule as in Scenario 2 applies.

Installation

Creating the Organization and Users on the LDAP Server

After you installed OpenLDAP, you need to create the organization, the roles and the users, so the LDAP client and GNU Health can interact with the server.

The following LDIF file to the basic organization and users, just for demonstration purposes.

Sample LDIF file

# The GNU Health Organization
dn: dc=gnuhealth,dc=org
objectclass: dcObject
objectclass: organization
o: GNU Health Nation
dc: gnuhealth

dn: cn=Manager,dc=gnuhealth,dc=org
objectclass: organizationalRole
cn: Manager

# PEOPLE Organizational UNIT (first level hierchy)
dn: ou=people, dc=gnuhealth,dc=org
ou: people
description: All people in organisation
objectclass: organizationalunit

# Actual users
dn: cn=Cameron Cordara,ou=People,dc=gnuhealth,dc=org
objectClass: inetorgperson
cn: Cameron Cordara
sn: Cordara
uid: cameroncordara
userPassword: SecretPass

You can now populate the initial OpenLDAP database uploading your newly created LDIF, for instance

$ slapadd -l <your_ldif_file>

Configuring LDAP in GNU Health

After you have configured the OpenLDAP server and created your users, you need to configure your GNU Health Tryton instance to communicate with it.

  • Install the following Tryton module

    • trytond_ldap-authentication

  • Create a new LDAP connection (Administration → LDAP → Connections)

    • Fill in the information to meet your LDAP server specification.

    • Save the connection

  • Create a user in GNU Health (Administration → Users → Users)

You can now create a user matching the uid on the LDIF file, and assign local roles to her. In this case, we would match the “login” name on he screen, with the uid of the user on your Organization. In the case of our Doctor Cameron Cordara, the login name would be cameroncordara. Again, this is just for demo purposes. In real-life scenarios you would use unique identifiers for login names.

Note: You will notice that the password field is already “filled in”. This is because the actual user password resides now in the LDAP server, and not in your local instance database.

If everything went right, you now have GNU Health enable for central authentication. Try to login as “cameroncordara”. Her credentials will be checked on the LDAP server.