Identity Management

AIStor Key Manager uses an authentication system where clients must present an API key to perform operations against the cluster. Each API key corresponds to a user identity that has a specific set of permissions defined by an attached policy.

Key Manager provides three types of identity by default:

• root or superadmin with full access to all operations (read, write, delete) within all enclaves, plus cluster management
• admin has full access to all operations (read, write, delete) within an enclave
• user has limited policy-controlled access to operations (read) within an enclave.

Each identity consists of a private and public key-string pair. The API key is a secret value that clients use to authenticate to the Key Manager cluster, while the public value lets peers verify the authenticity of the API key. Use the minkms identity command to create a new identity:

Your API key:

   k1:APIKEY

This is the only time it is shown. Keep it secret and secure!

Your API key's identity:

   h1:IDENTITY

The identity key is not a secret and can be shared securely.
Peers need this key to verify your API key.

This identity can be re-computed again using the following:

  $ minkms identity k1:APIKEY

The k1: prefixed value represents the API key to use when performing client operations. Treat this value as a secret and store it appropriately.

Use the minkms identity and minkms add-identity commands to create a new admin identity for an existing enclave:

minkms identity # Copy the `k1:`-prefixed API key

minkms add-identity aistor-object-store-primary --name enclave-admin --admin --id k1:<VALUE>

The --admin option specifies that the new identity has admin privileges within the specified enclave. Client applications specifying the API key when connecting to Key Manager can perform all key operations within the enclave.

Use the minkms identity and minkms add-identity commands to create a new user identity for an existing enclave:

minkms identity # Copy the `k1:`-prefixed API key

minkms add-identity aistor-object-store-primary --name enclave-user --id k1:<VALUE>

The user by default has no permissions to perform any operations within the enclave. You must attach a policy to the identity to allow it to perform any operations. Client applications specifying the API key when connecting to Key Manager can then perform all allowed operations within the enclave.

The root or superadmin identity has full access to all operations within all enclaves, plus cluster management. Key Manager first checks the configuration file for the admin.identity key to determine the root or superadmin identity.

Use the minkms identity and minkms add-identity commands to create a new root or superadmin identity:

minkms identity # Copy the `h1:`-prefixed value

Add the identity value to the Key Manager configuration file as the value of the admin.identity key:

admin:
  identity: h1:<VALUE>

Apply this change to all Key Manager nodes in the cluster, then restart all nodes to activate the new root or superadmin identity. Client applications specifying the API key when connecting to Key Manager can perform all operations, including cluster and enclave operations.

If the configuration file does not include an explicit admin.identity key, the Key Manager uses a configured HSM to generate an API key for the purpose of performing client operations against the cluster. Key Manager prints the root API key to the system log at startup. You can retrieve the key by reviewing the system logs with the journalctl utility:

journalctl -u minkms -g "API Key" -o cat --output-fields "MESSAGE"

The k1:-prefixed value represents the API key to use when performing client operations.