13. Authentication and Authorization

13.1. User authentication in ArmoniK

ArmoniK supports user authentication to increase the level of security, to allow different kinds of access to allowed users and to record the usage of the system. It uses mTLS to authentify a user with their user certificate. This authentication is done at 2 levels :

Certificate level authentication: the ingress in front of ArmoniK checks the validity of the user certificate. If validated, it sends the Common Name (CN) and Fingerprint of the certificate as headers to the underlying service
Header level authentication: the received headers are checked against a user database. If the user exists, it is authenticated with the corresponding internal user identity.

A user identity is the representation of a user and their permissions inside the system after the user has been authenticated. This authentication can be accomplished using either of the following schemes:

Certificate based scheme: the user identity corresponds to a specific certificate, which CN and Fingerprint are stored in the database.
CN based scheme: the user identity corresponds to the CN of a certificate. If the database contains an entry where only the CN is specified, it will match any valid certificate with this CN, unless it also matches an entry with both CN and Fingerprint in which case the Certificate Based Scheme has priority.
Impersonation scheme: the user identity corresponds to the user chosen via specific headers in the request. This is possible only if the certificate used matches a user, through a Certificate or CN scheme, who has the permissions required to impersonate the chosen user. See the Impersonation section for details.

13.2. Impersonation

ArmoniK allows users to impersonate other users by adding an impersonation header in their request. A user can use this feature if they already managed to pass a Certificate based scheme or a CN based scheme, then they must have impersonation permissions targetting all of the target’s roles. If at least one of the roles of the target user is not covered by the base user’s impersonate permissions, impersonation fails. If they can impersonate the target user, then the user identity used is the impersonated one. Permissions and roles of the original user are not inherited by the impersonated user. If a user attempts to impersonate a nonexistant user, or a user for which they don’t have have the proper rights, the authentication fails and does not fall back to the base user. Subsequent API calls done after this impersonation are seen by the rest of the system as if it was the impersonated user who made them. Impersonation is logged for auditing purposes.

13.3. User permissions

ArmoniK uses a User-Role-Permission based approach to handle authorization. Each user in the database can have a set of Roles. Each role contains a set of Permissions. A user cannot receive permissions directly, instead roles containing the permissions have to be created and given to the user. A permission is defined as a string in a specific format. The current version handles the following types of permissions :

Format	Example	Parameters	Description
`General:Impersonate:<Rolename>`	`General:Impersonate:Monitoring`	Rolename: Name of a role	Grants the right to impersonate a user with the role named <Rolename>. See Impersonation for details
`<Service>:<Name>`	`Submitter:CreateSession`	Service: Name of an ArmoniK web service Name: Name of the endpoint	Grants the right to use the endpoint named <Name> of the service named <Service>
`<Service>:<Name>:<Target>`	`Submitter:CancelSession:Self`	Service: Name of an ArmoniK web service Name: Name of the endpoint Target: Target or scope of the permission	Same as `<Service>:<Name>` as `<Target>` is currently unused

13.4. User authorization

When an user sends a request to an endpoint, they need to be authenticated, and they need the permission to use this endpoint. If they lack the permission, then they will be forbidden from using it.

13.5. Request authorization flowchart

        flowchart TB
    User([User Certificate])
    OK(OK)
    DENIED(PERMISSION DENIED)
    UNAUTHENTICATED(UNAUTHENTICATED)
    User --> Nginx{Nginx validates\nthe certificate}
    Nginx --> |Yes|Cache{User is already\nauthenticated}
    Nginx --> |No|UNAUTHENTICATED
    Cache --> |No|Exists{User is found\nin the database}
    Exists --> |No|UNAUTHENTICATED
    Exists --> |Yes|Identity(Identity =\n User Identity)
    Identity --> Impersonation{Impersonation\nheaders are set}
    Impersonation --> |Yes|CheckImp{Impersonated\nuser exists and base\n user can impersonate\n them}
    CheckImp --> |Yes|NewIdentity(Identity =\n Impersonated Identity)
    NewIdentity --> CheckPerm{User has enough\npermission to\ncall endpoint}
    Impersonation --> |No|CheckPerm
    CheckImp --> |No|UNAUTHENTICATED
    CheckPerm --> |No|DENIED
    CheckPerm --> |Yes|OK
    Cache --> |Yes|CheckPerm

13.6. User administration

Users, roles, permissions and certificates are stored and managed by ArmoniK via environment variables provided to the control plane and compute plane by the administrator during deployment. Administrators in charge of handling user permissions can refer to this section to manage user permissions.

13.6.1. Populating the internal MongoDB when deploying ArmoniK

NOTE : This is the current recommended method

You can define the users’ roles and certificates using a json configuration during deployment. Check the ArmoniK Authentication Configuration Guide for more details.

13.6.2. Using ArmoniK environment variables

In order to function properly, the authentication needs to have the following collections:

List of Certificate
- Handles the association between certificates and users
- Requires the following fields:
  - User : Name field of the User object associated with this certificate
  - CN : Certificate’s Common name
  - Fingerprint : null if this entry should match all certificates with the given CN, otherwise, the certificate’s fingerprint
- The CN and Fingerprint fields form a unique compound index.
List of User
- Handles the association between a user and its roles
- Requires the following fields
  - Name : Unique user name
  - Roles : list of role names, each matching the Name field of the roles given to the user
List of Role
- Handles the association between a role and its permissions
- Requires the following fields
  - Name : Unique role name
  - Permissions : list of strings corresponding to the permissions of the role

These collections of object need to be provided as JSON objects as detailled in the following sections.

13.6.2.1. Environment variables base

An InitServices options class was introduced to initialize services. It contains two classes : Authentication and Partitionning to configure authentication and partitions respectively. Authentication has several list of strings as fields: UserCertificates, Roles and Users. Those fields are JSON strings that are deserialized into corresponding objects that will be inserted into the database.

These options can be configured as environment variables. Lists should be converted into an environment variable per element with its index as shown below.

For example, the environment variables for the first and second roles are:

InitServices__Authentication__Roles__0=<json string containing a [Role]>
InitServices__Authentication__Roles__1=<json string containing a [Role]>

13.6.2.2. Specify roles

To specify a role with the name “Role1” granting the permissions “Submitter:ListTasks” and “General:Impersonate:Role2”, use the following environment variable:

InitServices__Authentication__Roles__0='{"Name": "Role1", "Permissions": ["Submitter:ListTasks", "General:Impersonate:Role2"]}'

If you need a second role, you can add the following environment variable too:

InitServices__Authentication__Roles__1='{"Name": "Role2", "Permissions": ["Submitter:ListTasks", "General:Impersonate:Role3"]}'

13.6.2.3. Specify users

To specify a user with the name “User1” with the role “Role1”, use the following environment variable:

InitServices__Authentication__Users__0='{"Name": "User1", "Roles": ["Role1"]})'

13.6.2.4. Specify certificates

To insert a certificate with Common Name “CN1” and Fingerprint “FP1” associated with the User called “User1”, use the following environment variable:

InitServices__Authentication__UserCertificates__0='{"User": "User1", "Cn": "CN1", "Fingerprint": "FP1"}'

To insert an entry matching all certificates with Common Name “CN1” associated with the User called “User1”, use the following environment variable:

InitServices__Authentication__UserCertificates__0='{"User": "User1", "Cn": "CN1"}'

13.6.2.5. Edit a user/role/certificate

Refer to this link for the procedure to update MongoDB entries. When updating a Role’s name, please make sure to also update the associated impersonation permission’s value.

13.6.2.6. Deleting a user/role/certificate

Refer to this link for the procedure to delete MongoDB entries.

13.6.3. Using the User Administration gRPC service

Currently not implemented