API Keys - Determinist API Keys + Security changes

[gmourier]

🤖 API Diff
📄 Rendered

---

Summary

This update to the Keys API makes several changes:

• It is possible to create a deterministic key value by specifying a uid field at creation.
• It is possible to get a key from the key field or the uid field.
• Specifying a key to update or delete is made with the uid field.
• Adds a name field to give a human-readable name to ease API key retrieval in a list at the convenience of the user.
• The master key is only dedicated to API keys management, it can't be used for other endpoints. Making Meilisearch more secure by design and thus preventing users from introducing a security vulnerability.
• Updating a key only allows the name and description fields.
• Introduce new actions to manage API Keys (keys.get, keys.create, keys.update, keys.delete). The Default Admin API Key is able to manage keys by default.
• apiKeyPrefix tenant token claim is renamed apiKeyUid.

---

Changes

uid Field Addition

The generation of a randomized prefix of 8 characters is removed by the existence of the uid field. This field accepts a string representing a UUID v4.

It is possible to specify this uid field when creating a key, if not specified it is generated by Meilisearch.

As the value of key is a hash of the uid and the master key, it is possible to have deterministic key values between instances sharing the same configuration thus keeping some interesting security features as:

• If the master key changes, all key values are automatically changed.
• The API key resources are propagated into the dumps and snapshot without displaying the key field in clear.

A key is retrieved from its uid rather than its key value. e.g. GET /keys/:uid_or_key instead of GET /keys/:key.

Specifying a uid that already exists returns a 409 Conflict.

name Field Addition

A name field is added to allow a human-readable name to better read the information within a list of keys. The description field is kept to add additional information if needed.

For example, the description field is useful to give important information about the keys generated by default that would not necessarily have its place in the name. This makes it easier to parse in a dashboard when building a UI or in the GET /keys response.

The default generated API keys are updated to reflect this change.

{
    ...,
    "name": "Default Admin API Key",
    "description": "Use it for all other than search operations. Caution! Do not expose it on a public frontend",
    ...
}

Note that the description is updated. ( / ) are removed.

Master key

The master key can only be used to manage API keys.

Several times, it has been found that users use the master key to make client-side requests, which is problematic for their security. In order to ensure that they do not inadvertently put themselves in danger, the master key can no longer access routes other than /keys.

keys.* actions

The specification adds new rights dedicated to the management of API keys.

These actions are keys.get, keys.create, keys.update, keys.delete.

The default Admin key also has these rights. actions is equal to * at its creation.

The goal is to give the possibility to users to create dedicated keys for that purpose and to reduce the use of the master key for this endpoint.

API Key Update

It is no longer possible to update the sensitive information of an API key which could introduce undesired permissions escalation as a side effect.

However, it is possible to update the name and description fields.

Out Of Scope

Adding a unique human-readable field as an alias to retrieve an API Key other than its uid is not considered in this iteration. It should be easy to add it later without breaking changes.

---

📡 Attention To Reviewers 📡

@meilisearch/cloud-team We basically need your attention on all these changes.

The big question mark could be the update of the permissions of an API key on your side, which users could request. This could be done within a transaction on your side to allow the update if it is a vital need.

The workaround would be to delete the key that needs to be updated and recreate one with the new permissions by giving it the uid of the previous one. This way, the key value used by clients to authorize requests is unchanged.

The regeneration of a key would be done in the same way by creating a key copying the permissions but giving it a new uid.

Also, do you have any particular constraints concerning the master key, which is now restricted to endpoint /keys access only?

@nicolasvienot The addition of the name field should allow you to have more fluidity in the construction of the UI and thus avoid having to parse the description field to display the default keys properly.

---

Misc

• Update OpenAPI specification file
• Reorganize the specification

[github-actions]

🚨 Breaking API change detected:

Modified (4)

• GET /keys
  • Response modified: 200
    • Body attribute modified: results
• GET /keys/{uid_or_key}
  • Path parameter added: uidOrKey
  • Response modified: 200
    • Body attributes added: uid, name
• PATCH /keys/{uid_or_key}
  • Body modified
    • Body attributes added: name, Additional properties are NOT allowed
    • [Breaking] Body attributes removed: key, actions, indexes, expiresAt, createdAt, updatedAt
  • Response modified: 200
    • Body attributes added: uid, name
• [Breaking] POST /keys
  • [Breaking] Body modified
    • Body attributes added: uid, name
  • [Breaking] Response modified: 200
    • Body attributes added: uid, name

View documentation diff

Powered by Bump

[brunoocasali]

Awesome work @gmourier 💪

[gmourier]

@meilisearch/integration-team @ManyTheFish There remains a design question regarding the JWT payload for tenant token.

Currently, the JWT requires an apiKeyPrefix. It should be renamed since the prefix won't exist anymore. Here is 2 possibilities I can think of:

• apiKey: Fill in the signing API key's full key field. (Not sure about this one!)
• apiKeyUid: Fill in the uid of the signing API key.

What will be the best choice according to you?

[gmourier]

@ManyTheFish will explore two additional things if the time permits it. Otherwise, it will be considered for future iterations.

GET /keys/:uid_or_key

See if it's possible to have GET /keys/:uid_or_key to transparently get the details of an API Key given uid or key.

Add specific rights to manage keys

Since the master key will only be used to manage /keys, we are exploring if we can easily add new actions to manage keys.

This way, the master key will be less shared and mostly used one time to fetch the defaults Search Key and Admin Key. The Admin Key will gain the rights to manage /keys by default.

---

Depending on the exploration results, the specification could be modified to add these points.

[ManyTheFish]

@gmourier, I suggested changes about key derivation.

[Kerollmops]

It would be much better if we could add a sentence about the secret for the HMACSHA256 hashing must be the original API Key value (not the UID and not base64 encoded). I can't add this sentence myself, the area where I put that is out of the diff.

[ManyTheFish]

Request changes related to meilisearch/meilisearch#2584