How to configure authentication?

This guide aims to present the setup of the authentication framework within ArmoniK.

What authentication means in ArmoniK

Authentication in ArmoniK is about security. Without authentication, anyone with access to the gRPC endpoints can send requests to it, potentially running undesirable workloads.

ArmoniK uses client certificates to authenticate users. Authentication allows users who have the right certificates to send requests to the different endpoints. Different certificates can grant different permissions, based on a User-Role-Permission system.

Authentication options in ArmoniK

It is possible to setup the authentication in different ways when deploying ArmoniK:

No authentication: Any user with access to the endpoints can send any request.
Ingress authentication: Only users with valid client certificates can send any request to the endpoints. Client certificate authority and custom unique client certificate are generated.
Ingress authentication, custom CA: Only users with valid client certificates can send any request to the endpoints. Client certificate authority must be provided at deployment.
Ingress + Control plane authentication: Only users with valid client certificates can send requests to the endpoints. Two users are created by default, one with access to all endpoints and requests and one with access only to the monitoring endpoints and requests. These certificates are generated by the ArmoniK deployment (See How to setup authentication using default certificates).
Ingress + Control plane authentication, custom CA: Only the users with valid client certificates can send requests to the endpoints. Users, roles and permissions are setup manually. Certificates are not generated by the deployment scripts, meaning the client certificate authority must be provided during deployment and user certificates are not automatically generated (See How to setup your own certificates for authentication for details).

Authentication options features table

Authentication Option	No client certificate	Method access restriction	Autogenerated Certificates	Custom roles	Custom certificates
No authentication	✔️	❌	❌	❌	❌
Ingress authentication	❌	❌	✔️	❌	❌
Ingress authentication, custom CA	❌	❌	❌	❌	✔️
Ingress + Control plane authentication	❌	✔️	✔️	❌	❌
Ingress + Control plane authentication, custom CA	❌	✔️	❌	✔️	✔️

Deployment configuration

For each of the following configuration, the required parameters in your parameters.tfvars to specify are:

ingress.mTLS: Controls whether the ingress requires user certificates
ingress.generate_client_cert: Controls whether the deployment generates the default certificates with different roles
ingress.custom_client_ca_file: Empty if the ingress should use a generated self signed certificate authority, otherwise uses the certificate specified at the given path
authentication.require_authentication: Controls whether the control plane requires user certificates in database
authentication.require_authorization: Controls whether the control plane checks for user permissions. If used it needs the authentication.require_authentication to be true.
authentication.authentication_datafile: Empty if the default generated certificates will be used, otherwise is a path to a json configuration file (See How to create a JSON authentication configuration file)

How to setup a deployment without authentication

Configuration parameter	Value
`ingress.mTLS`	`false`
`ingress.generate_client_cert`	`false`
`ingress.custom_client_ca_file`	`""`
`authentication.require_authentication`	`false`
`authentication.require_authorization`	`false`
`authentication.authentication_datafile`	`""`

Using this configuration, anyone with access to the endpoints can send any request.

How to setup mTLS authentication using a default certificate authority and a single user certificate

Configuration parameter	Value
`ingress.mTLS`	`true`
`ingress.generate_client_cert`	`false`
`ingress.custom_client_ca_file`	`""`
`authentication.require_authentication`	`true` or `false`
`authentication.require_authorization`	`false`
`authentication.authentication_datafile`	`""`

Using this configuration, a default client certificate will be generated. Anyone can access the endpoints using this certificate. Since this certificate will be put in the database by default, the parameter authentication.require_authentication can be set to true or false. The default client certificate created is infrastructure/quick-deploy/localhost/generated/certificates/ingress/client.submitter.crt

How to setup mTLS authentication using a custom certificate authority

Configuration parameter	Value
`ingress.mTLS`	`true`
`ingress.generate_client_cert`	`false`
`ingress.custom_client_ca_file`	`Path to client ca.pem`
`authentication.require_authentication`	`false`
`authentication.require_authorization`	`false`
`authentication.authentication_datafile`	`""`

Using this configuration, the specified ca.pem will be used to authenticate user certificates. The client certificates are not generated by the deployment.

How to setup authentication using default certificates

Configuration parameter	Value
`ingress.mTLS`	`true`
`ingress.generate_client_cert`	`true`
`ingress.custom_client_ca_file`	`""`
`authentication.require_authentication`	`true`
`authentication.require_authorization`	`true`
`authentication.authentication_datafile`	`""`

Default certificates are generated alongside the automatically generated client certificate authority. In this case, two certificates are generated in the infrastructure/quick-deploy/localhost/generated/certificates/ingress folder : client.submitter.crt which corresponds to a user with all permissions, and client.monitoring.crt which corresponds to a user with only monitoring permissions.

How to setup your own certificates for authentication

Configuration parameter	Value
`ingress.mTLS`	`true`
`ingress.generate_client_cert`	`false`
`ingress.custom_client_ca_file`	`Path to client ca.pem`
`authentication.require_authentication`	`true`
`authentication.require_authorization`	`true`
`authentication.authentication_datafile`	`Path to json authentication configuration file`

Using this configuration, the specified ca.pem will be used to authenticate the user certificates. The client certificates are not generated by the deployment. Each certificate is attributed to a specific user with specific roles. Each role has specific permissions, allowing or denying the user access to specific endpoints. For each certificate, the user and role need to be described in the given json configuration file (See How to create a JSON authentication configuration file).

How to create a JSON authentication configuration file

The JSON authentication configuration file must have the following format (note that the format is case sensitive):

{
  "certificates_list":[
    {
      "Cn": "string", //Common name of the certificate
      "Fingerprint" : "string" or null, // Sha1 sum of the certificate's raw binary data
      "Username": "string" // Username
    }
  ],
  "users_list":[
    {
      "Username": "string", // Username
      "Roles": ["string"] // RoleName of the user's list of roles
    }
  ],
  "roles_list":[
    {
      "RoleName":"string", // Role name
      "Permissions": ["string"] // List of permissions linked to that role.
    }
  ],
}

Notes:

The Username and RoleName MUST be uniquely defined. A badly defined json may fail silently.
The Fingerprint field represents the SHA-1 hash of the certificate’s raw binary data, which can be extracted using the following command
```
  openssl x509 -in </path/to/certificate.crt> -noout -fingerprint | sed 's/.*=\|://g' | tr A-F a-f
```
If Fingerprint is null, the user will be authenticated using ANY certificate with the given Common Name.

The resulting configuration is stored in the MongoDB database. If the database is restarted when MongoDB isn’t setup with a persistent volume or if the database is emptied it needs to be repopulated by relaunching the authentication-in-database job. In a local deployment, this can be achieved using the following shell command:

kubectl -n armonik get job authentication-in-database -o json | jq "del(.spec.selector)" | jq "del(.spec.template.metadata.labels)" | kubectl -n armonik replace --force -f -

JSON authentication configuration example

The following json is an example defining two users, with their own different roles. The role Submitter does have all the permissions on every current endpoints. The role Monitoring does have all permissions related to monitoring duties, but cannot start or stop tasks or sessions. Each user has its own certificate.

{
  "certificates_list":[
    {
      "Cn": "CNOfUserSubmitter",
      "Fingerprint" : "752c14ea195c369bac3c3b7896975ee9fd15eeb7",
      "Username": "UserSubmitter"
    },
    {
      "Cn": "CNOfUserMonitoring",
      "Fingerprint" : "c26dc0bf68e25099bc4a85b631efdb93d0768a20",
      "Username": "UserMonitoring"
    }
  ],
  "users_list":[
    {
      "Username": "UserSubmitter",
      "Roles": [
        "Submitter",
        "Monitoring"
        ] // Note here that the permissions of Monitoring are included in Submitter, thus Monitoring could be omitted here
    },
    {
      "Username": "UserMonitoring",
      "Roles": ["Monitoring"]
    }
  ],
  "roles_list":[
    {
      "RoleName":"Submitter",
      "Permissions": [
        "Submitter:GetServiceConfiguration",
        "Submitter:CancelSession",
        "Submitter:CancelTasks",
        "Submitter:CreateSession",
        "Submitter:CreateSmallTasks",
        "Submitter:CreateLargeTasks",
        "Submitter:CountTasks",
        "Submitter:TryGetResultStream",
        "Submitter:WaitForCompletion",
        "Submitter:TryGetTaskOutput",
        "Submitter:WaitForAvailability",
        "Submitter:GetTaskStatus",
        "Submitter:GetResultStatus",
        "Submitter:ListTasks",
        "Submitter:ListSessions",
        "Sessions:CancelSession",
        "Sessions:GetSession",
        "Sessions:ListSessions",
        "Tasks:GetTask",
        "Tasks:ListTasks",
        "Tasks:GetResultIds",
        "Results:GetOwnerTaskId"
      ]
    },
    {
      "RoleName":"Monitoring",
      "Permissions": [
        "Submitter:GetServiceConfiguration",
        "Submitter:CountTasks",
        "Submitter:GetTaskStatus",
        "Submitter:GetResultStatus",
        "Submitter:ListTasks",
        "Submitter:ListSessions",
        "Sessions:GetSession",
        "Sessions:ListSessions",
        "Tasks:GetTask",
        "Tasks:ListTasks",
        "Tasks:GetResultIds",
        "Results:GetOwnerTaskId"
      ]
    }
  ],
}