Identity Management

MinIO Key Management Service (KMS) 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.

MinIO KMS 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 KMS 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.

Creating Admin Identities

Use the minkms identity and minkms add-identity commands to create a new admin identity for an existing enclave. The following example assumes an AIStor object store named ‘primary’ for determining the enclave name:

minkms identity # Prints a new API key and its identity

minkms add-identity --enclave aistor-object-store-primary --admin <IDENTITY>

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

Creating User Identities

Use the minkms identity and minkms add-identity commands to create a new user identity for an existing enclave. The following example assumes an AIStor object store named ‘primary’ for determining the enclave name:

minkms identity # Prints a new API key and its identity

minkms add-identity --enclave aistor-object-store-primary <IDENTITY>

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 MinIO KMS can then perform all allowed operations within the enclave.

Creating an explicit root or superadmin identity

The root or superadmin identity has full access to all operations within all enclaves, plus cluster management. MinIO KMS 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 KMS configuration file as the value of the admin.identity key:

admin:
  identity: h1:<VALUE>

Apply this change to all KMS 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 MinIO KMS can perform all operations, including cluster and enclave operations.

Default root or superadmin identity

If the configuration file does not include an explicit admin.identity key, MinIO KMS uses a configured HSM to generate an API key for the purpose of performing client operations against the cluster. The minkms process 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.

Rotating API keys

Rotate API keys on a regular schedule, when a team member who knows a key leaves, or when you suspect a key has been exposed.

MinIO KMS does not issue a new API key for an existing identity. Each API key belongs to exactly one identity, so rotating an API key means replacing the identity:

Create a new identity with the same privileges as the old identity, using minkms add-identity.
Update every client that uses the old API key to use the new API key.
Remove the old identity with minkms rm-identity.

Both API keys work during the transition, so clients keep their access to MinIO KMS while you update them.

Rotating an API key does not affect your encryption keys or your data. The enclave and its keys stay the same, and AIStor can still read all data encrypted before the rotation.

You can run the identity commands against any node in the cluster. MinIO KMS applies the change to all nodes automatically, and you do not need to restart MinIO KMS.

Creating the replacement identity

The new identity must have the same privileges as the identity it replaces.

Look up the privileges of the old identity.

Use minkms identity to get the h1:-prefixed identity of the old API key, and then display it with minkms get-identity:
```
minkms identity k1:OLD_API_KEY # Copy the `h1:`-prefixed value
minkms get-identity --enclave ENCLAVE_NAME h1:OLD_IDENTITY
```
The output shows the Privilege of the identity and, for a user identity, the name of its Policy.

Create the new identity.

Run minkms add-identity with an enclave admin API key or the root API key. If you do not specify --api-key, the command uses the value of MINIO_KMS_API_KEY.

To replace an enclave admin identity, include --admin:

minkms add-identity --enclave ENCLAVE_NAME --admin --api-key k1:CURRENT_API_KEY

To replace a user identity, omit --admin:

minkms add-identity --enclave ENCLAVE_NAME --api-key k1:CURRENT_API_KEY

The command generates a new API key, adds its identity to the enclave, and prints both values:

Your API key:

   k1:NEW_API_KEY

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

Your API key's identity:

   h1:NEW_IDENTITY

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

This identity can be re-computed again via:

  $ minkms identity k1:NEW_API_KEY

Added identity to server successfully.

MinIO KMS does not store the API key and cannot display it again. Store the API key in a secure location before you continue.

For a user identity, assign the policy of the old identity to the new identity.

A new user identity has no permissions until you assign a policy to it. Use minkms set-policy with the policy name from the first step:
```
minkms set-policy --enclave ENCLAVE_NAME POLICY_NAME h1:NEW_IDENTITY
```
Enclave admin identities do not use policies, so skip this step when you replace an enclave admin identity.

Rotating the API key that AIStor uses

AIStor uses the enclave admin API key in MINIO_KMS_API_KEY to connect to MinIO KMS. AIStor reads this value only when the process starts, so you must restart the AIStor service on every node to use a new API key.

Create a new enclave admin identity as described in Creating the replacement identity.
Confirm that the new API key works.
```
minkms ls-key --enclave ENCLAVE_NAME --api-key k1:NEW_API_KEY
minkms ls-identity --enclave ENCLAVE_NAME --api-key k1:NEW_API_KEY
```
The first command lists the keys in the enclave. The second command lists both the old and the new enclave admin identities.
Set MINIO_KMS_API_KEY to the new API key on every AIStor node, and then restart the AIStor service on every node.
```
sudo systemctl restart minio
```
Do not use mc admin service restart for this step. That command restarts AIStor with the environment it started with, so AIStor keeps using the old API key.

Check the AIStor logs on each node to confirm that AIStor starts and connects to MinIO KMS.
Remove the old identity.

Remove the old identity only after all AIStor nodes use the new API key. On AIStor nodes that still use the old API key, requests that require MinIO KMS fail. Removing the identity also removes its service accounts, so first check that no application uses them.

minkms rm-identity requires the h1:-prefixed identity, not the API key. Use minkms identity to get the identity of the old API key, and then remove it:
```
minkms identity k1:OLD_API_KEY # Copy the `h1:`-prefixed value
minkms rm-identity --enclave ENCLAVE_NAME h1:OLD_IDENTITY
```

Rotating the `root` API key

You cannot create a root or superadmin identity with minkms add-identity. To replace the root API key, follow the steps in Creating an explicit root or superadmin identity. This applies to both the default root API key that the HSM generates and a root API key that you configured earlier.

After you restart all nodes, the new identity is the only root identity. The previous root API key no longer has superadmin privileges.

Use the root API key only for cluster management, and give applications such as AIStor an enclave admin API key instead. Cluster management commands such as minkms stat require the root API key and do not work with an enclave admin API key.

Identity Management

On this page