mirror of
https://github.com/qdrant/landing_page.git
synced 2026-09-29 16:08:32 +02:00
Add JWT RBAC documentation (#808)
* add basic description * add table and proof-read * review fixes * add leeway detail * review * nits --------- Co-authored-by: generall <andrey@vasnetsov.com>
This commit is contained in:
Luis Cossío
@@ -7,8 +7,6 @@ aliases:
|
||||
|
||||
# Security
|
||||
|
||||
|
||||
|
||||
Please read this page carefully. Although there are various ways to secure your Qdrant instances, **they are unsecured by default**.
|
||||
You need to enable security measures before production use. Otherwise, they are completely open to anyone
|
||||
|
||||
@@ -42,7 +40,7 @@ export QDRANT__SERVICE__API_KEY=your_secret_api_key_here
|
||||
|
||||
<aside role="alert"><a href="#tls">TLS</a> must be used to prevent leaking the API key over an unencrypted connection.</aside>
|
||||
|
||||
For using API key based authentication in Qdrant cloud see the cloud
|
||||
For using API key based authentication in Qdrant Cloud see the cloud
|
||||
[Authentication](/documentation/cloud/authentication/)
|
||||
section.
|
||||
|
||||
@@ -110,7 +108,7 @@ var client = new QdrantClient(
|
||||
);
|
||||
```
|
||||
|
||||
<aside role="alert">Internal communication channels are <strong>never</strong> protected by an API key. Internal gRPC uses port 6335 by default if running in distributed mode. You must ensure that this port is not publicly reachable and can only be used for node communication. By default, this setting is disabled for Qdrant Cloud and the Qdrant Helm chart.</aside>
|
||||
<aside role="alert">Internal communication channels are <strong>never</strong> protected by an API key nor bearer tokens. Internal gRPC uses port 6335 by default if running in distributed mode. You must ensure that this port is not publicly reachable and can only be used for node communication. By default, this setting is disabled for Qdrant Cloud and the Qdrant Helm chart.</aside>
|
||||
|
||||
### Read-only API key
|
||||
|
||||
@@ -132,6 +130,286 @@ export QDRANT__SERVICE__READ_ONLY_API_KEY=your_secret_read_only_api_key_here
|
||||
|
||||
Both API keys can be used simultaneously.
|
||||
|
||||
### Granular access control with JWT
|
||||
|
||||
*Available as of v1.9.0*
|
||||
|
||||
For more complex cases, Qdrant supports granular access control with [JSON Web Tokens (JWT)](https://jwt.io/).
|
||||
This allows you to have tokens, which allow restricited access to a specific parts of the stored data and build [Role-based access control (RBAC)](https://en.wikipedia.org/wiki/Role-based_access_control) on top of that.
|
||||
In this way, you can define permissions for users and restrict access to sensitive endpoints.
|
||||
|
||||
To enable JWT-based authentication in your own Qdrant instance you need to specify the `api-key` and enable the `jwt_rbac` feature in the configuration:
|
||||
|
||||
```yaml
|
||||
service:
|
||||
api_key: you_secret_api_key_here
|
||||
jwt_rbac: true
|
||||
```
|
||||
|
||||
Or with the environment variables:
|
||||
|
||||
```bash
|
||||
export QDRANT__SERVICE__API_KEY=your_secret_api_key_here
|
||||
export QDRANT__SERVICE__JWT_RBAC=true
|
||||
```
|
||||
|
||||
The `api_key` you set in the configuration will be used to encode and decode the JWTs, so –needless to say– keep it secure. If your `api_key` changes, all existing tokens will be invalid.
|
||||
|
||||
To use JWT-based authentication, you need to provide it as a bearer token in the `Authorization` header, or as an key in the `Api-Key` header of your requests.
|
||||
|
||||
```http
|
||||
Authorization: Bearer <JWT>
|
||||
|
||||
// or
|
||||
|
||||
Api-Key: <JWT>
|
||||
```
|
||||
|
||||
```python
|
||||
from qdrant_client import QdrantClient
|
||||
|
||||
qdrant_client = QdrantClient(
|
||||
"xyz-example.eu-central.aws.cloud.qdrant.io",
|
||||
api_key="<JWT>",
|
||||
)
|
||||
```
|
||||
|
||||
```typescript
|
||||
import { QdrantClient } from "@qdrant/js-client-rest";
|
||||
|
||||
const client = new QdrantClient({
|
||||
host: "xyz-example.eu-central.aws.cloud.qdrant.io",
|
||||
apiKey: "<JWT>",
|
||||
});
|
||||
```
|
||||
|
||||
```rust
|
||||
use qdrant_client::client::QdrantClient;
|
||||
|
||||
let client = QdrantClient::from_url("xyz-example.eu-central.aws.cloud.qdrant.io:6334")
|
||||
.with_api_key("<JWT>")
|
||||
.build()
|
||||
.unwrap();
|
||||
```
|
||||
|
||||
```java
|
||||
import io.qdrant.client.QdrantClient;
|
||||
import io.qdrant.client.QdrantGrpcClient;
|
||||
|
||||
QdrantClient client =
|
||||
new QdrantClient(
|
||||
QdrantGrpcClient.newBuilder(
|
||||
"xyz-example.eu-central.aws.cloud.qdrant.io",
|
||||
6334,
|
||||
true)
|
||||
.withApiKey("<JWT>")
|
||||
.build());
|
||||
```
|
||||
|
||||
```csharp
|
||||
using Qdrant.Client;
|
||||
|
||||
var client = new QdrantClient(
|
||||
host: "xyz-example.eu-central.aws.cloud.qdrant.io",
|
||||
https: true,
|
||||
apiKey: "<JWT>"
|
||||
);
|
||||
```
|
||||
|
||||
#### Generating JSON Web Tokens
|
||||
|
||||
Due to the nature of JWT, anyone who knows the `api_key` can generate tokens by using any of the existing libraries and tools, it is not necessary for them to have access to the Qdrant instance to generate them.
|
||||
|
||||
For convenience, we have added a JWT generation tool the Qdrant Web UI under the 🔑 tab, if you're using the default url, it will be at `http://localhost:6333/dashboard#/jwt`.
|
||||
|
||||
- **JWT Header** - Qdrant uses the `HS256` algorithm to decode the tokens.
|
||||
|
||||
```json
|
||||
{
|
||||
"alg": "HS256",
|
||||
"typ": "JWT"
|
||||
}
|
||||
```
|
||||
|
||||
- **JWT Payload** - You can include any combination of the [parameters available](#jwt-configuration) in the payload. Keep reading for more info on each one.
|
||||
|
||||
```json
|
||||
{
|
||||
"exp": 1640995200, // Expiration time
|
||||
"value_exists": ..., // Validate this token by looking for a point with a payload value
|
||||
"access": "r", // Define the access level.
|
||||
}
|
||||
```
|
||||
|
||||
**Signing the token** - To confirm that the generated token is valid, it needs to be signed with the `api_key` you have set in the configuration.
|
||||
That would mean, that someone who knows the `api_key` gives the authorization for the new token to be used in the Qdrant instance.
|
||||
Qdrant can validate the signature, because it knows the `api_key` and can decode the token.
|
||||
|
||||
The process of token generation can be done on the client side offline, and doesn't require any communication with the Qdrant instance.
|
||||
|
||||
Here is an example of libraries that can be used to generate JWT tokens:
|
||||
|
||||
- Python: [PyJWT](https://pyjwt.readthedocs.io/en/stable/)
|
||||
- JavaScript: [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken)
|
||||
- Rust: [jsonwebtoken](https://crates.io/crates/jsonwebtoken)
|
||||
|
||||
#### JWT Configuration
|
||||
|
||||
These are the available options, or **claims** in the JWT lingo. You can use them in the JWT payload to define its functionality.
|
||||
|
||||
- **`exp`** - The expiration time of the token. This is a Unix timestamp in seconds. The token will be invalid after this time. The check for this claim includes a 30-second leeway to account for clock skew.
|
||||
|
||||
```json
|
||||
{
|
||||
"exp": 1640995200, // Expiration time
|
||||
}
|
||||
```
|
||||
|
||||
- **`value_exists`** - This is a claim that can be used to validate the token against the data stored in a collection. Structure of this claim is as follows:
|
||||
|
||||
```json
|
||||
{
|
||||
"value_exists": {
|
||||
"collection": "my_validation_collection",
|
||||
"matches": [
|
||||
{ "key": "my_key", "value": "value_that_must_exist" }
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
If this claim is present, Qdrant will check if there is a point in the collection with the specified key-values. If it does, the token is valid.
|
||||
|
||||
This claim is especially useful if you want to have an ability to revoke tokens without changing the `api_key`.
|
||||
Consider a case where you have a collection of users, and you want to revoke access to a specific user.
|
||||
|
||||
```json
|
||||
{
|
||||
"value_exists": {
|
||||
"collection": "users",
|
||||
"matches": [
|
||||
{ "key": "user_id", "value": "andrey" },
|
||||
{ "key": "role", "value": "manager" }
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
You can create a token with this claim, and when you want to revoke access, you can change the `role` of the user to something else, and the token will be invalid.
|
||||
|
||||
- **`access`** - This claim defines the [access level](#table-of-access) of the token. If this claim is present, Qdrant will check if the token has the required access level to perform the operation. If this claim is **not** present, **manage** access is assumed.
|
||||
|
||||
It can provide global access with `r` for read-only, or `m` for manage. For example:
|
||||
|
||||
```json
|
||||
{
|
||||
"access": "r"
|
||||
}
|
||||
```
|
||||
|
||||
It can also be specific to one or more collections. The `access` level for each collection is `r` for read-only, or `rw` for read-write, like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"access": [
|
||||
{
|
||||
"collection": "my_collection",
|
||||
"access": "rw"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
You can also specify which subset of the collection the user is able to access by specifying a `payload` restriction that the points must have.
|
||||
|
||||
```json
|
||||
{
|
||||
"access": [
|
||||
{
|
||||
"collection": "my_collection",
|
||||
"access": "r",
|
||||
"payload": {
|
||||
"user_id": "user_123456"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
This `payload` claim will be used to implicitly filter the points in the collection. It will be equivalent to appending this filter to each request:
|
||||
|
||||
```json
|
||||
{ "filter": { "must": [{ "key": "user_id", "match": { "value": "user_123456" } }] } }
|
||||
```
|
||||
|
||||
### Table of access
|
||||
|
||||
Check out this table to see which actions are allowed or denied based on the access level.
|
||||
|
||||
This is also applicable to using api keys instead of tokens. In that case, `api_key` maps to **manage**, while `read_only_api_key` maps to **read-only**.
|
||||
|
||||
<div style="text-align: right"> <strong>Symbols:</strong> ✅ Allowed | ❌ Denied | 🟡 Allowed, but filtered </div>
|
||||
|
||||
| Action | manage | read-only | collection read-write | collection read-only | collection with payload claim (r / rw) |
|
||||
|--------|--------|-----------|----------------------|-----------------------|------------------------------------|
|
||||
| list collections | ✅ | ✅ | 🟡 | 🟡 | 🟡 |
|
||||
| get collection info | ✅ | ✅ | ✅ | ✅ | ❌ |
|
||||
| create collection | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| delete collection | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| update collection params | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| get collection cluster info | ✅ | ✅ | ✅ | ✅ | ❌ |
|
||||
| collection exists | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| update collection cluster setup | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| update aliases | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| list collection aliases | ✅ | ✅ | 🟡 | 🟡 | 🟡 |
|
||||
| list aliases | ✅ | ✅ | 🟡 | 🟡 | 🟡 |
|
||||
| create shard key | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| delete shard key | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| create payload index | ✅ | ❌ | ✅ | ❌ | ❌ |
|
||||
| delete payload index | ✅ | ❌ | ✅ | ❌ | ❌ |
|
||||
| list collection snapshots | ✅ | ✅ | ✅ | ✅ | ❌ |
|
||||
| create collection snapshot | ✅ | ❌ | ✅ | ❌ | ❌ |
|
||||
| delete collection snapshot | ✅ | ❌ | ✅ | ❌ | ❌ |
|
||||
| download collection snapshot | ✅ | ✅ | ✅ | ✅ | ❌ |
|
||||
| upload collection snapshot | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| recover collection snapshot | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| list shard snapshots | ✅ | ✅ | ✅ | ✅ | ❌ |
|
||||
| create shard snapshot | ✅ | ❌ | ✅ | ❌ | ❌ |
|
||||
| delete shard snapshot | ✅ | ❌ | ✅ | ❌ | ❌ |
|
||||
| download shard snapshot | ✅ | ✅ | ✅ | ✅ | ❌ |
|
||||
| upload shard snapshot | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| recover shard snapshot | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| list full snapshots | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||||
| create full snapshot | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| delete full snapshot | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| download full snapshot | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||||
| get cluster info | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||||
| recover raft state | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| delete peer | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| get point | ✅ | ✅ | ✅ | ✅ | ❌ |
|
||||
| get points | ✅ | ✅ | ✅ | ✅ | ❌ |
|
||||
| upsert points | ✅ | ❌ | ✅ | ❌ | ❌ |
|
||||
| update points batch | ✅ | ❌ | ✅ | ❌ | ❌ |
|
||||
| delete points | ✅ | ❌ | ✅ | ❌ | ❌ / 🟡 |
|
||||
| update vectors | ✅ | ❌ | ✅ | ❌ | ❌ |
|
||||
| delete vectors | ✅ | ❌ | ✅ | ❌ | ❌ / 🟡 |
|
||||
| set payload | ✅ | ❌ | ✅ | ❌ | ❌ |
|
||||
| overwrite payload | ✅ | ❌ | ✅ | ❌ | ❌ |
|
||||
| delete payload | ✅ | ❌ | ✅ | ❌ | ❌ |
|
||||
| clear payload | ✅ | ❌ | ✅ | ❌ | ❌ |
|
||||
| scroll points | ✅ | ✅ | ✅ | ✅ | 🟡 |
|
||||
| search points | ✅ | ✅ | ✅ | ✅ | 🟡 |
|
||||
| search groups | ✅ | ✅ | ✅ | ✅ | 🟡 |
|
||||
| recommend points | ✅ | ✅ | ✅ | ✅ | ❌ |
|
||||
| recommend groups | ✅ | ✅ | ✅ | ✅ | ❌ |
|
||||
| discover points | ✅ | ✅ | ✅ | ✅ | ❌ |
|
||||
| count points | ✅ | ✅ | ✅ | ✅ | 🟡 |
|
||||
| version | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| readyz, healthz, livez | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| telemetry | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||||
| metrics | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||||
| update locks | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||||
| get locks | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||||
|
||||
## TLS
|
||||
|
||||
|
||||
Reference in New Issue
Block a user