User management

The Snow Owl Authoring Platform has two different ways to manage users. The primary authentication and authorization service is the LDAP Directory Server. The secondary option is a file-based database, used only for administrative purposes. Whenever user access has to be granted or revoked the following methods could be applied.

LDAP based identity provider

This is only applicable to the default deployment setup where a co-located OpenLDAP server is used alongside the Terminology Server.

While Bugzilla is configured to use the same OpenLDAP server for authentication, it also maintains its own user database in SQL. This user database is indirectly used by the Snow Owl thick client, so it is important to keep LDAP and Bugzilla in sync.

This means that whenever a change was made to the LDAP user database an explicit Bugzilla container restart is required withdocker-compose restart bugzilla

The container restart will take care of bringing over any changes made to the LDAP users.

There are several ways to access and manage an OpenLDAP server, hereby we will only describe one of them, through the Apache Directory Studio.

Welcome to Apache Directory Studio — Apache Directory

Apache Directory Studio is an open-source, free application. It is available to download for different platforms (Windows, macOS, and Linux).

Before accessing the LDAP database there is one technical prerequisite to satisfy. The OpenLDAP server has to be accessible from the machine Apache Directory Studio is installed. The best and most secure way to achieve that is to set up an SSH tunnel. Follow this link to an article that describes how to configure an SSH tunnel using PuTTY and Windows.

The OpenLDAP server uses port 389 for communication. This is the port that needs to be tunneled through the SSH connection. Here is what the final configuration looks like in PuTTY:

Configure SSH tunnel

Once the SSH tunnel works, it's time to set up our connection in Apache DS. Go to File -> New -> LDAP Connection and set the following:

Set up LDAP connection

Hit the "Check Network Parameter" button to verify the network connection.

Go to the next page of the wizard and provide your credentials. The default Bind DN and Bind password can be found in the Authoring Platform release package under ./snow-owl/docker/.env.

Provide credentials for the LDAP connection

Hit the "Check Authentication" button to verify your credentials. Hit Finish to complete the setup procedure.

All users and groups should be browseable now through the LDAP Browser view:

Browser LDAP users / groups

Grant user access

To grant access to a new user an LDAP entry has to be created. Go to the LDAP Browse view and right-click on the organization node, then New -> New Entry:

Create new LDAP entry

It is the easiest to use an existing entry as a template:

Select existing user entry as template

Leave everything as is on the Object Classes page, then hit Next. Fill in the new user's credentials:

Configure user details

On the final page, double click on the userPassword row and provide the user's password:

Set user credentials

Hit Finish to add the user to the database.

Now we need to assign a role for the user. Before going forward, get ahold of the user's DN using the LDAP Browser view:

Copy the user's DN

Select the desired role group in the Browser view and add a new attribute:

Add new attribute

Select the attribute type uniqueMember and hit Finish:

Select attribute type uniqueMember

Paste the user's DN as the value of the attribute and hit Enter to make your changes permanent:

Add new member to role group

Revoke user access

To revoke access the user has to be deleted from the list of users:

Delete user entry

And also has to be removed from the role group:

Delete role group attribute

Change credentials

To change either the first or last name, or the password of a user, just edit any of the attributes in the user editor:

Change user credentials

File-based identity provider

There is a configuration file ./snow-owl/docker/configs/snowowl/users that contains the list of users with their credentials encrypted. The passwords are encrypted using the bcrypt hash algorithm (variant $2a$). This method of authentication though should be used only for administration purposes (e.g. bot users) because any of the users added here will have admin privileges.

To apply any changes made to the users file the Terminology Server has to be restarted afterward.

Grant user access

To grant access the users file has to be amended with the new user and its credentials. There are several ways to encrypt a password using the bcrypt algorithm but here is one that is easy and available on most of the Linux variants. The package called htpasswd has to be installed:

htpasswd -nBC 10 my-new-username | head -n1 | sed 's/$2y/$2a/g' >> ./snow-owl/docker/configs/snowowl/users

It will prompt for the password and will amend the file with the new user at the end.

Revoke user access

Simply remove the user's line from the file and restart the service.

Change credentials

Remove the user's line from the file and regenerate the credentials according to the Grant user access section.