Authentication

The KumoScale CLI and REST APIs are accessed using tokens for both Appliance and Managed modes. The token will function until its expiration as long as the session has not terminated. Any user may generate a token for self-use, which can be entered in each REST command or once per CLI session. There are two ways to manage tokens for storage access:

  • Self-generated tokens, applies to both Appliance and Managed mode,
  • OpenID Connect (OIDC) for both Appliance mode and Managed mode.

Self-Generated Tokens

Any user may generate a token for self-use, which can be entered in each REST command (or once per CLI session). The generate-token command has an expiration parameter (in seconds – for REST API, or hours – for CLI):

  • Default (and minimum) value – one hour.
  • Maximum – 30 days.

The token is a JWT and must be properly validated before it can be used thereafter as an access token in KumoScale Provisioner REST API calls.

Open ID Connect Authentication

OpenID Connect (OIDC) authentication is supported under both Appliance and Managed modes. To configure KumoScale to support OIDC authentication, you can use the Provisioner REST API, Provisioner CLI, or custom resource files to complete the following steps:

  • Define the authentication server.
  • Update the provisioner secret with details on the authentication server.
  • Create the secret.

Note: When you configure OIDC, you must confirm that the clock is synched across all servers involved in provisioning and storage. For example, servers supporting the KumoScale Provisioner, storage nodes, and keycloak. Tokens have an expiration time and if there is a time difference between initiators, OIDC authentication may fail with a cannot decrypt token error.

OIDC Authentication using Custom Resource Files

In this section we will show you how to set up the authorization server using custom resource files. You will need to configure two files. An example of each is provided with KumoScale software

  • Authorization Secret CR, example file authorization-secret.yaml.
  • Authorization Server CR, example file yaml.

Complete the steps below:

  1. Gather details on the authentication server. Details on the authorization server needed for defining the CRs may be gathered by using a keycloak Complete information on how to use keycloak is available at https://www.keycloak.org.

Log into keycloak, to find the values of the:

  • Authorization server public key, under RealmSettings > keys
  • Provisioner Resource ID name, Provisioner Client ID, Storage node Resource ID and Storage node Client ID, under the client tab


2.   Set up the authorization secret file. The authorization secret file must contain values for each of the following fields:


Authorization Secret
Parameter Name

Description

Optional/Required

authenticationServerPublicKey

The public key used to decrypt tokens.

Required

authenticationServerTokenURL

Authorization server URL for generating tokens.

Required

provisionerClientID

The client ID of a client which has a service account with KumoScale level role ADMIN.

Required

provisionerClientSecret

The client secret

Required

provisionerResourceID

The ID of the provisioner resource; the client name as defined in the authorization server of the provisioner.

Required

storagenodeClientID

The client ID of a client which has a service account with Provisioner level role ADMIN.

Required

storageClientSecret

The KumoScale client secret

Required

storagenodeResourceID

The ID of the KumoScale resource.

Required

For example, the file authorization-secret.yaml contains

apiVersion: v1

kind: Secret

metadata:

name: auth-secret

namespace: default

type: Opaque

stringData:

config.yaml: |-

   authorizationServerPublicKey: ###############################################

   authServerTokenUrl: http://###.#.##.1:8080/auth/realms/Dev/protocol/openid-connect/token

   provisionerClientID: provisioner-adi

   provisionerClientSecret: ################-###-#######################

   provisionerResourceID: provisioner-adi

   storagenodeClientID: kumoscale-adi

   storagenodeClientSecret: ################-###-#######################

   storagenodeResourceID: kumoscale-adi

3.  Specify the values of the authorization CR. Only one authorization server CR is allowed. The table below summarizes the parameters to specify.


Authorization server Parameter Name

Description

Optional/Required

secretName

The secret which provides details for configuring the authentication server. This has a string value.

Required

revision

Used to track the updates of the CR secret. It should be increased by 1 for each update to the secret. This has an integer value.

Required

status

Generated automatically after you create the CR.
To verify the status, enter

kubectl describe authorizationServer –A

The value will be

  • Pending if validation failed. The server is not active.
  • Active , if validation was successful. The server is now active

N/A

 

For example, using the secret file above, the file authorization-server.yaml contains

apiVersion: kumoscale.kioxia.com/v1

kind: AuthorizationServer

metadata:

name: authorizationserver-sample

spec:

secretName: auth-secret

revision: 1
4.  Create the secret with:
kubectl create -f provisioner-secret.yaml

OIDC Authentication using the REST API

If you are using Managed mode on bare-metal servers, you will need to use the REST API commands below. See the REST API documentation for complete details on how to set up OIDC authentication. Below is an example.

  • Define the Authorization server using the Set Authorization Server Provisioner REST API command to set the parameters specified in the Provisioner REST API documentation.
  • Set the server. For example:
curl -k --cert ./ssdtoolbox.pem -X POST -H 'Content-Type: application/json' -d '{"authorizationServerPublicKey":“<key>", "authorizationServerTokenURL":"http://X.X.X.X:8080/auth/realms/Dev/protocol/openid-connect/token", "backendsClientID":“<ID>", "backendsResourceID":"<ID>", "backendsClientSecret":“<X>", "provisionerClientID":"<ID>", "provisionerResourceID":“<ID>", "provisionerClientSecret":“X"}' https://X.X.X.X:8090/auth_server
  • Get a token from the authorization server. For example:
curl http://<your URL>/auth/realms/Dev/protocol/openid-connect/token -H 'Content-Type: application/x-www-form-urlencoded' --data 'grant_type=client_credentials&client_id=****&client_secret=****'

 

 

Next: Tenant Management