Authentication & Authorization

Owned by Candice Louw (Unlicensed)
Last updated: Jul 22, 2024
4 min read

  • Authentication relies on users managed in SORMAS and synchronized to keycloak.

  • Authorization relies on user rights managed in SORMAS

Authentication Mechanisms

SORMAS comes with two authentication mechanisms, configures via the authentication.provider property in the sormas.properties file.

  1. Keycloak: This is the default setup and has to be used by any production system.

  2. SORMAS JEE authentication realm: This is a legacy authentication mechanism that should only be used by development systems.

KEYCLOAK

Obtains and validates the sessions/requests trough a Keycloak instance. Keycloak doesn't handle any roles, those are still managed by the Sormas system.

See Keycloak and [Keycloak Setup].(https://github.com/hzi-braunschweig/SORMAS-Project/blob/development/docs/SERVER_SETUP.md#keycloak-server )

The authentication mechanism is implemented in the following modules:

sormas-rest

  • Validates all the requests trough the Keycloak OIDC Filter https://www.keycloak.org/docs/latest/securing_apps/#_servlet_filter_adapter

  • Configuration of Keycloak is provided trough Payara MicroProfile properties

  • Depending on how the sormas-rest Keycloak client is configured, it can accept Bearer and Basic or only Bearer authorization

    • If Basic authorization is enabled, the mobile app doesn't need to implement any Oauth2 flows for obtaining the access token of the user and can use the same approach as it uses with the SORMAS realm

sormas-ui

sormas-backend

  • Synchronization of users and management of credentials from SORMAS to keycloak

  • To do so performs a server-side authentication with Keycloak and obtains a service account token

  • Configuration of Keycloak is provided trough Payara MicroProfile properties

SORMAS realm

Provides a basic auth authorization using a JEE auth realm.

User Management

A user account can be used by an end user to access SORMAS. Additionally, there are technical user accounts that allow external systems to access data. **Users **have one or more user roles, which in turn define a set of user rights and a jurisdiction that defines the area of responsibility. For example, the jurisdiction of a surveillance officer is the district, which is defined on the user. User roles that have different areas of responsibility are therefore not combinable. SORMAS has a standard set of user roles with predefined user rights and also allows to create custom user roles.

User Creation

User creation is done solely by the SORMAS Admin (see Sormas User Rights for more details) trough the SORMAS UI.

  • User creation is currently not exposed trough the REST API

  • When Keycloak is used a counterpart of the user is created in Keycloak as well. Matching is done based on the username.

There are a few restrictions when creating the user:

  • username must be unique

  • with the basic authentication provider, the uniqueness is case sensitive (Abc =/= abc)

  • with Keycloak authentication provider, the uniqueness is no longer case sensitive (Abc == abc)

  • there are roles which are mutually exclusive (cannot be assigned at the same time) → the system will inform the user of this when a conflict appears

  • email is not unique, multiple users can share the same email

  • email is optional for any authentication provider starting with SORMAS 1.54.0

An end user can get access into the system in 2 possible ways:

  1. The SORMAS Admin creates the user without an email address a password will be generated by the SORMAS password helper and displayed in plain text for the admin to copy and share. Once the Password window is closed, there is not way of viewing the password again without generating a new one

  2. If Keycloak is active as an authentication provider, the users have the possibility to setup a password for themselves once they login into the web application. If the SORMAS Admin creates the user with an email address, no password will be displayed to the Admin, but an email will be sent to the user's email address with account activation instructions

User Deletion

SORMAS doesn't have a concept for complete user deletion, however an inactivate functionality is present which allows the Admin to revoke login access for any user.

When Keycloak is the active authentication provider the deactivation is synced from SORMAS to Keycloak A deactivated user can no longer login or request a new password until an Admin activates the account back

Credentials Management

Credentials management are highly dependent on the active Authentication Provider

SORMAS Authentication Provider

  • Credentials only refer to username and password

  • The password is generated based on a SHA-256 algorithm (salted)

  • There are no features for end users to manage their own password (they can only be generated by an Admin user)

  • Since the passwords are generated by the system when triggered by the admin, no password policy is in place

Keycloak Authentication Provider

  • Credentials can refer to username, password and OTP (later one being optional for each installation) → see the Configuration Summary for Keycloak

  • The default Keycloak algorithm used for encrypting passwords is a combination of pbkdf2 and SHA-256 with salt

  • If a user has a valid email address associated to their account, they can use features like: setting up an initial password when activating their account and forgot password

  • Since the user has the possibility to set up a password manually a default Password Policy is also in place (can be easily adjusted by any Keycloak Admin → see the Keycloak documentation for this) Length of minimum 12 characters

    • At least 1 upper case letter

    • At least 1 lower case letter

    • At least 1 digit

    • At least 1 special character

Authorization

Roles and Rights

All the SORMAS supported roles and rights are defined in the Sormas User Roles excel.

In all situations the SORMAS System is the central point for configuring and managing roles and rights for the users.