You can configure security to communicate with a Lightweight Directory Access Protocol (LDAP) server to authenticate and authorize users.
To integrate with LDAP, you configure an ldap realm in the snowowl.yml configuration file.
The following configuration settings are supported:
The default configuration values are selected to support both OpenLDAP and Active Directory without needing to customize the default schema that comes with their default installation.
When users send their username and password with their request in the Authorization header, the LDAP security realm performs the following steps to authenticate the user: 1. Searches for a user entry in the configured baseDn to get the DN 2. Authenticates with the LDAP instance using the received DN and the provided password
If any of the above-mentioned steps fails for any reason, the user is not allowed to access the terminology server's content and the server will respond with HTTP 401 Unauthorized.
To configure authentication, you need to configure the uri, baseDn, bindDn, bindDnPassword, userObjectClass and userIdProperty configuration settings.
To add a user in the LDAP realm, create an entry under the specified baseDn using the configured userObjectClass as class and the userIdProperty as the property where the user's username/e-mail address is configured.
Example user entry:
On top of the authentication part, the LDAP realm provides configuration values to support full role-based access control and authorization.
When a user's request is successfully authenticated with the LDAP realm, Snow Owl authorizes the request using the user's currently set roles and permissions in the configured LDAP instance.
To add a role in the LDAP realm, create an entry under the specified baseDn using the configured roleObjectClass as class and the configured permissionProperty and memberProperty properties for permission and user mappings, respectively.
Example read-only role:
Configuration
Description
uri
The LDAP URI that points to the LDAP/AD server to connect to.
bindDn
The user's DN who has access to the entire baseDn and roleBaseDn and can read content from it.
bindDnPassword
The password of the bindDn user.
baseDn
The base directory where all entries in the entire subtree will be considered as potential matches for all searches.
roleBaseDn
Alternative base directory where all role entries in the entire subtree will be considered. Defaults to the baseDn value.
userFilter
The search filter to search for user entries under the configured baseDn. Defaults to (objectClass={userObjectClass}).
roleFilter
The search filter to search for role entries under the configured roleBaseDn. Defaults to (objectClass={roleObjectClass}).
userObjectClass
The user object's class to look for when searching for user entries. Defaults to inetOrgPerson class.
roleObjectClass
The role object's class to look for when searching for role entries. Defaults to groupOfUniqueNames class.
userIdProperty
The userId property to access and read for the user's unique identifier. Usually their username or email address. Defaults to uid property.
permissionProperty
A multi-valued property that is used to store permission information on a role. Defaults to the description property.
memberProperty
A multi-valued property that is used to store and retrieve user dns that belong to a given role. Defaults to the uniqueMember property.
You can manage and authenticate users with the built-in file realm. All the data about the users for the file realm is stored in the users file. The file is located in SO_PATH_CONF and is read on startup.
You need to explicitly select the file realm in the snowowl.yml configuration file in order to use it for authentication.
In the above configuration the file realm is using the users file to read your users from. Each row in the file represents a username and password delimited by : character. The passwords are BCrypt encrypted hashes. The default users file comes with a default snowowl user with the default snowowl password.
To simplify file realm configuration, the Snow Owl CLI comes with a command to add a user to the file realm (snowowl users add). See the command help manual (-h option) for further details.
The file security realm does NOT support the Authorization formats at the moment. If you are interested in configuring role-based access control for your users, it is recommended to switch to the LDAP security realm.
Snow Owl security features enable you to easily secure your terminology server. You can password-protect your data as well as implement more advanced security measures such as role-based access control and auditing.
By default Snow Owl comes without any security features enabled and all read and write operations are unprotected. To configure a security realm, you can choose from the following built-in identity providers:
After configuring at least one security realm, Snow Owl will authenticate all incoming requests to ensure that the sender of the request is allowed to access the terminology server and its contents. To authenticate a request, the client must send an HTTP Basic or Bearer Authorization header with the request. The value should be a user/pass pair in case of using Basic authentication or a token generated by Snow Owl if using the Bearer method.
NOTE: It is recommended in production environments that all communication between a client and Snow Owl is performed through a secure connection.
Snow Owl sends an HTTP 401 Unauthorized response if a request needs to be authenticated.
If supported by the security realm, Snow Owl will also check whether an authenticated user is permitted to perform the requested action on a given resource.
Within an organization, roles are created for various job functions. The permissions to perform certain operations are assigned to specific roles. Members, staff or other system users are assigned particular roles, and through those role assignments acquire the permissions needed to perform particular system functions. Since users are not assigned permissions directly, but only acquire them through their role (or roles), management of individual user rights becomes a matter of simply assigning appropriate roles to the user's account; this simplifies common operations, such as adding a user, or changing a user's department.
Role assignment: A subject can exercise a permission only if the subject has selected or been assigned a role.
Permission authorization: A subject can exercise a permission only if the permission is authorized for the subject's active role.
With rules 1 and 2, it is ensured that users can exercise only permissions for which they are authorized.
S = Subject = A person or automated agent R = Role = Job function or title which defines an authority level P = Permissions = An approval of a mode of access to a resource
In Snow Owl a permission is a single value that represents both the operation the user would like to perform and the resource that is being accessed. The format is the following: <operation>:<resource>
Currently there are 7 operations supported by Snow Owl:
browse - read the contents of a resource
edit - write the contents of the resource, delete the resource
import - import from external content and formats
export - export to external content and formats
version - create a version in a Code System, create a release
promote - merge content from isolated branch environments to a Code System's development version
classify - run classifiers and save their results
Resources represent the content that is being accessed by a client. A resource can be anything that can be resolved to a database entry. Currently, the following resource formats are allowed to be used in a permission:
<repositoryId> - access the entire content available in a terminology repository
<repositoryId>/<branch> - access the content available on a branch in a terminology repository
<codeSystemId> - access all content of a Code System, including both the latest development and all previous releases
<codeSystemId>/<versionId> - access a specific release of a Code System
There is a special * wild card character that can be used for both the operation and resource parts in a permission value to allow any operation to be performed on any or selected resources, or to allow certain operations to be performed on any available resources.
Examples:
browse:snomedStore - browse all SNOMED CT Code Systems and their content
edit:SNOMEDCT-UK-CL - edit the SNOMEDCT-UK-CL Code System
export:SNOMEDCT-US/2019-03-01 - export the 2019-03-01 US Extension release
*:SNOMEDCT - allow any operations to be performed on the SNOMEDCT Code System
browse:* - allow read operations on all available resources
*:* - administrator permission, the user can do anything with any of the available resources
To configure authorization, please consult the security realm specific documentation: