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.
Keycloak: This is the default setup and has to be used by any production system.
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
Obtains the OpenID configuration and performs the OAuth flow by using the OpenIdAuthenticationMechanism provided by Payara https://docs.payara.fish/community/docs/5.201/documentation/payara-server/public-api/openid-connect-support.html , https://blog.payara.fish/openid-connect-in-the-payara-platform-5.183
Configuration of the OpenIdAuthenticationMechanism is done trough Payara MicroProfile properties
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:
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
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.