diff --git a/doc/2/guides/advanced/api-keys/index.md b/doc/2/guides/advanced/api-keys/index.md index ce1df361e6..f5300a3cd5 100644 --- a/doc/2/guides/advanced/api-keys/index.md +++ b/doc/2/guides/advanced/api-keys/index.md @@ -5,10 +5,11 @@ order: 200 title: API Keys | Kuzzle Advanced | Guide | Core meta: - name: description - content: Manage kuzzle API keys + content: Manage Kuzzle API keys - name: keywords - content: Kuzzle, Documentation, kuzzle write pluggins, General purpose backend, opensource, API Keys + content: Kuzzle, Documentation, kuzzle write pluggins, General purpose backend, opensource, API Keys --- + # API Keys Kuzzle allows to create API keys to **authenticate users without using an authentication strategy** and the [auth:login](/core/2/api/controllers/auth/login) action. @@ -28,95 +29,51 @@ By default, **API keys do not expire**. But it is possible to specify the durati ::: info It is also possible to set a maximum validity period for an API key under the key `security.apiKey.maxTTL` in the Kuzzle configuration. This limit will only apply to API key created with the `auth` controller. -Possible values: - - `<= -1`: disable the use of maxTTL - - `>= 0`: enable maxTTL with setted value (`0` will invalid all your API keys at their creation) -::: +Possible values: + +- `<= -1`: disable the use of maxTTL +- `>= 0`: enable maxTTL with a set value (`0` will immediately invalidate an API key when created) + ::: It is also necessary to **provide a description** of the API key. -**Example: _Create an API key for the user "melis" and valid for 30 days_** -```bash -kourou security:createApiKey '{ description: "Cron API key" }' \ - -a expiresIn=30d \ - -a userId=melis -``` +**Example: _Create an API key for the user "ricky", valid for 30 days_** -
API response - -```js -{ - "description": "Cron API key", - "expiresAt": 1608466769443, - "fingerprint": "b9aeb4703bf1f4bf3bf05dd39d0546763a375f38d9220aa8b803251e58927b5a", - "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiItMSIsImlhdCI6MTYwNTg3NDc2OSwiZXhwIjoxNjA4NDY2NzY5fQ.8O6Nq6qTRcQCiU1YcOiXnGrsZj-kDIMi0awtX3kofio", - "ttl": 2592000000, - "userId": "melis", - "_kuzzle_info": { - "author": "melis", - "createdAt": 1605874769445, - "updatedAt": null, - "updater": null - } -} +```bash +kourou api-key:create ricky --description "Cron API key" --expire "30d" ``` -
- +![api-key](../../../screenshots/api-key-create.png) -Kuzzle returns a response containing the token authentication linked to the API key in the `token` property. +Kourou returns the authentication token linked to the API key. ### API Key properties ::: warning -The authentication token provided in the `token` property will never be returned by Kuzzle again. If you lose it, you'll have to delete the API key and recreate a new one. +The authentication token is only sent by Kuzzle **once**. If you lose it, you'll have to delete the API key and recreate a new one. ::: -| Property | Description | -|---------------|-----------------------------------------------------------------------------------| -| `description` | Description | -| `expiresAt` | expiration date in UNIX micro-timestamp format (`-1` if the token never expires) | -| `fingerprint` | SHA256 hash of the authentication token | -| `token` | Authentication token associated with this API key | -| `ttl` | Original TTL | -| `userId` | User [kuid](/core/2/guides/main-concepts/authentication#kuzzle-user-identifier) | +| Property | Description | +| ------------- | -------------------------------------------------------------------------------- | +| `description` | Description | +| `expiresAt` | Expiration date in UNIX micro-timestamp format (`-1` if the token never expires) | +| `fingerprint` | SHA256 hash of the authentication token | +| `token` | Authentication token associated with this API key | +| `ttl` | Original TTL | +| `userId` | User [kuid](/core/2/guides/main-concepts/authentication#kuzzle-user-identifier) | ## Search for API Keys It is possible to search in its own API keys ([auth:searchApiKeys](/core/2/api/controllers/auth/search-api-keys)) or in those of all users ([security:searchApiKeys](/core/2/api/controllers/security/search-api-keys)). +In order to search an API key of a user, you can use the Kourou `api-key:search` command. -In order to know to which API key an authentication token corresponds, it is possible to use the `fingerprint` property which is a SHA256 hash of the token. - +**Example: _Search every API keys of the user "ricky"_** ```bash -# use sha256sum to compute the fingerprint of the authentication token -echo -n "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiItMSIsImlhdCI6MTYwNTg3NDc2OSwiZXhwIjoxNjA4NDY2NzY5fQ.8O6Nq6qTRcQCiU1YcOiXnGrsZj-kDIMi0awtX3kofi -o" | sha256sum -# b9aeb4703bf1f4bf3bf05dd39d0546763a375f38d9220aa8b803251e58927b5a - -kourou security:searchApiKeys -a userId=melis '{ term: { fingerprint: "b9aeb4703bf1f4bf3bf05dd39d0546763a375f38d9220aa8b803251e58927b5a" } }' -``` -
API response - -```js -{ - "hits": [ - { - "_id": "PLuY5XUBTiOVkQBqXikm", - "_source": { - "description": "Cron API key", - "expiresAt": 1608466769443, - "fingerprint": "b9aeb4703bf1f4bf3bf05dd39d0546763a375f38d9220aa8b803251e58927b5a", - "ttl": 2592000000, - "userId": "melis" - } - } - ], - "total": 1 -} +kourou api-key:search ricky ``` -
+![api-key](../../../screenshots/api-key-search.png) ::: info The associated authentication token is not returned by Kuzzle. @@ -128,6 +85,21 @@ It is possible to use the [auth:deleteApiKey](/core/2/api/controllers/auth/delet Once an API key is deleted, the **associated authentication token will be revoked** and cannot be used anymore. +**Example: _Delete the API key with the ID `7ef0022d-a5e2-429b-ab8f-5b6065d345e7` of the user "ricky"_** ```bash -kourou security:deleteApiKey -userId=melis --id PLuY5XUBTiOVkQBqXikm +kourou api-key:delete ricky 7ef0022d-a5e2-429b-ab8f-5b6065d345e7 ``` + +![api-key](../../../screenshots/api-key-delete.png) + + +## Check API Key + +It is possible to check the validity of an API Key by running + +**Example: _Check the validity of the API key `kapikey-eyJ...2dos`_** +```bash +kourou api-key:check kapikey-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiJyaWNreSIsImlhdCI6MTY5NzQ2OTU5NCwiZXhwIjoxNzAwMDYxNTk0fQ.pTuBOPaRoV9VpxuWI6HufxdbSDAbcPK5PNTmHHS2dos +``` + +![api-key](../../../screenshots/api-key-check.png) \ No newline at end of file diff --git a/doc/2/screenshots/api-key-check.png b/doc/2/screenshots/api-key-check.png new file mode 100644 index 0000000000..350b38bcde Binary files /dev/null and b/doc/2/screenshots/api-key-check.png differ diff --git a/doc/2/screenshots/api-key-create.png b/doc/2/screenshots/api-key-create.png new file mode 100644 index 0000000000..e215c3a3bb Binary files /dev/null and b/doc/2/screenshots/api-key-create.png differ diff --git a/doc/2/screenshots/api-key-delete.png b/doc/2/screenshots/api-key-delete.png new file mode 100644 index 0000000000..777ea8f794 Binary files /dev/null and b/doc/2/screenshots/api-key-delete.png differ diff --git a/doc/2/screenshots/api-key-search.png b/doc/2/screenshots/api-key-search.png new file mode 100644 index 0000000000..fd00f79209 Binary files /dev/null and b/doc/2/screenshots/api-key-search.png differ