> For the complete documentation index, see [llms.txt](https://docs.b2ihealthcare.com/authoring-platform-admin-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.b2ihealthcare.com/authoring-platform-admin-guide/miscellaneous/user-management.md).

# 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

{% hint style="info" %}
This is only applicable to the default deployment setup where a co-located OpenLDAP server is used alongside the Terminology Server.
{% endhint %}

{% hint style="danger" %}
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 with`docker-compose restart bugzilla`

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

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

{% embed url="<https://directory.apache.org/studio>" %}

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

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](https://linuxize.com/post/how-to-setup-ssh-tunneling/#set-up-ssh-tunneling-in-windows) 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](/files/WCpHvvZzGmkbp5dBdDJK)

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](/files/GJutnbWQbUPaVPs79wTP)

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](/files/JZQKiQpbQBA0CeXJxXYS)

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](/files/T9dS3xx5P1fg0WcYvty1)

### 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](/files/OrVUapIH2JnvRoNEMJ2B)

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

![Select existing user entry as template](/files/sffMV0V8TmbrHYXtJsIv)

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

![Configure user details](/files/4PtjC9hRcZhJzh24eJGJ)

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

![Set user credentials](/files/hkMTTZMoFWeVslo4K5Hk)

Hit *Finish* to add the user to the database.&#x20;

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](/files/W6sH12FapaWcQ1iDNyS3)

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

![Add new attribute](/files/Y9UBDry00fU2GRMDvN6C)

Select the attribute type `uniqueMember` and hit *Finish*:

![Select attribute type uniqueMember](/files/shOchkfUrYdOIj4InxVx)

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](/files/rNwtWD93ZPkO46xoYP0d)

### Revoke user access

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

![Delete user entry](/files/tIvHM9JBqCyTgMOn64Y6)

And also has to be removed from the role group:

![Delete role group attribute](/files/94TrIgqhbk1ICBaVvMIX)

### 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](/files/AUN5Z49qhOT5xdUh6Byb)

## 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 ](https://en.wikipedia.org/wiki/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.

{% hint style="warning" %}
To apply any changes made to the `users` file the Terminology Server has to be restarted afterward.
{% endhint %}

### 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:

```bash
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](#grant-user-access-1) section.&#x20;