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

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

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

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

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

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

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 fingerprint of the certificate (if null, the user will be authenticated using ANY certificate with the given Common Name)
      "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.
    }
  ],
}

Please note that the Username and RoleName MUST be uniquely defined. A badly defined json may fail silently.

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"
      ]
    }
  ],
}