mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-09-21 07:28:26 +03:00
docs: add multiple admin secrets and multiple jwt secrets pages
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/4164 Co-authored-by: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com> GitOrigin-RevId: 50d1e404f013024e845fb60bb2bda6594e8bcb50
This commit is contained in:
Tirumarai Selvan
hasura-bot
parent
7f4565fad2
commit
7dce0a0782
@ -26,3 +26,5 @@ All API security-related features can be found under the `Security` tab in the A
|
||||
- [Allow Lists](/graphql/cloud/security/allow-lists.mdx)
|
||||
- [API Limits](/graphql/cloud/security/api-limits.mdx)
|
||||
- [Disable GraphQL Introspection](/graphql/cloud/security/disable-graphql-introspection.mdx)
|
||||
- [Multiple Admin Secrets](/graphql/cloud/security/multiple-admin-secrets.mdx)
|
||||
- [Multiple JWT Secrets](/graphql/cloud/security/multiple-jwt-secrets.mdx)
|
||||
|
||||
52
docs/docs/graphql/cloud/security/multiple-admin-secrets.mdx
Normal file
52
docs/docs/graphql/cloud/security/multiple-admin-secrets.mdx
Normal file
@ -0,0 +1,52 @@
|
||||
---
|
||||
description: Hasura Cloud multiple admin secrets
|
||||
keywords:
|
||||
- hasura
|
||||
- docs
|
||||
- cloud
|
||||
- security
|
||||
- allow
|
||||
- rotating
|
||||
- multiple
|
||||
- admin
|
||||
- secrets
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# Multiple Admin Secrets
|
||||
|
||||
## Introduction
|
||||
|
||||
You can specify a list of admin secrets in GraphQL Engine which can be used to :
|
||||
|
||||
1. Implement security mechanisms like rotating secrets
|
||||
2. Have different lifecycles for individual admin secrets e.g. temporarily give admin access to an operator
|
||||
|
||||
## How to use
|
||||
|
||||
Multiple admin secrets can be provided in the env var `HASURA_GRAPHQL_ADMIN_SECRETS` which takes a list of admin secrets,
|
||||
|
||||
For example:
|
||||
|
||||
```json
|
||||
["secret-1", "secret-2"]
|
||||
```
|
||||
|
||||
When you launch the console from the Hasura Cloud dashboard, you can use any secret from the admin secrets list to authenticate yourself as an admin.
|
||||
If you want to make API calls as an admin from outside the console, you need to pass any one of the admin secrets as the `x-hasura-admin-secret` request header.
|
||||
|
||||
:::info Note
|
||||
|
||||
If both `HASURA_GRAPHQL_ADMIN_SECRET` and `HASURA_GRAPHQL_ADMIN_SECRETS` are set, then only `HASURA_GRAPHQL_ADMIN_SECRETS` will be used.
|
||||
|
||||
:::
|
||||
|
||||
## Rotating admin secrets (Self-hosted environments)
|
||||
|
||||
When you have a self-hosted Hasura EE setup, you can use this feature to implement a secret rotation mechanism without downtime as outlined below:
|
||||
|
||||
1. Add a new secret to the list of admin secrets (and perform a rolling deploy)
|
||||
2. Update applications/services using the old admin secret to use the new secret
|
||||
3. Remove the old secret from the admin secret list (and perform a rolling deploy)
|
||||
|
||||
Note that a rolling deploy ensures that there is atleast one service which is active.
|
||||
50
docs/docs/graphql/cloud/security/multiple-jwt-secrets.mdx
Normal file
50
docs/docs/graphql/cloud/security/multiple-jwt-secrets.mdx
Normal file
@ -0,0 +1,50 @@
|
||||
---
|
||||
description: Hasura Cloud multiple JWT Secrets
|
||||
keywords:
|
||||
- hasura
|
||||
- docs
|
||||
- cloud
|
||||
- security
|
||||
- allow
|
||||
- multiple
|
||||
- JWT
|
||||
- secrets
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# Multiple JWT Secrets
|
||||
|
||||
## Introduction
|
||||
|
||||
You can configure GraphQL Engine with a list of JWT secrets. This enables you to authenticate with different JWT issuers.
|
||||
|
||||
## How to use
|
||||
|
||||
Multiple JWT secrets can be provided in the env var `HASURA_GRAPHQL_JWT_SECRETS` which takes a list of JWT secret objects.
|
||||
|
||||
For example:
|
||||
|
||||
```json
|
||||
[
|
||||
{ "jwk_url": "https://...", "issuer": "myapp" },
|
||||
{ "type":"HS256", "key": "3EK6FD...", "issuer": "test" }
|
||||
]
|
||||
```
|
||||
|
||||
The structure of an individual JWT secret is described [here](/graphql/core/auth/authentication/jwt.mdx#configuring-jwt-mode).
|
||||
|
||||
:::info Note
|
||||
|
||||
If both `HASURA_GRAPHQL_JWT_SECRET` and `HASURA_GRAPHQL_JWT_SECRETS` are set, then `HASURA_GRAPHQL_JWT_SECRETS` will be used.
|
||||
|
||||
:::
|
||||
|
||||
## Resolution logic
|
||||
|
||||
The authentication is resolved as follows:
|
||||
|
||||
1. Bearer tokens are extracted from headers or cookie locations (as configured by each JWT secret)
|
||||
2. Tokens are filtered to ensure that the **issuer** field matches the configuration, or that the issuer is absent either from the configuration or the token.
|
||||
3. If no matching tokens are found then the unauthenticated flow is performed (depends on [HASURA_GRAPHQL_UNAUTHORIZED_ROLE](/graphql/core/auth/authentication/unauthenticated-access.mdx)).
|
||||
4. If multiple matching tokens are found then an error is raised as the desired token is ambiguous.
|
||||
5. If only one matching token is found then it is verified against the corresponding configured secret.
|
||||
@ -1,49 +0,0 @@
|
||||
---
|
||||
description: Hasura Cloud multiple JWT Secrets
|
||||
keywords:
|
||||
- hasura
|
||||
- docs
|
||||
- cloud
|
||||
- security
|
||||
- allow
|
||||
- multiple
|
||||
- JWT
|
||||
- secrets
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# Multiple JWT Secrets
|
||||
|
||||
## Introduction
|
||||
|
||||
You can configure Hasura with a list of JWT Secrets so that you can integrate with different JWT issuers.
|
||||
This is useful when you have different authentication providers using the same Hasura infrastructure.
|
||||
|
||||
|
||||
## How to use multiple jwt secrets
|
||||
|
||||
Multiple JWT secrets can be provided in the env var `HASURA_GRAPHQL_JWT_SECRETS` which takes a JSON array of JWT secret objects.
|
||||
|
||||
Bearer Tokens are authenticated against the secret with a matching or absent <em>issuer</em>.
|
||||
|
||||
The authentication is resolved as follows:
|
||||
|
||||
1. Raw token values matched with configurations by looking in locations configured in HASURA_GRAPHQL_JWT_SECRETS under the "header" field (Authorization Header if missing).
|
||||
2. Tokens are filtered to ensure that the <em>issuer</em> field matches, or that the issuer is absent either from the configuration, or the token.
|
||||
3. If no candidate tokens are found then the unauthorized flow is performed (depends on `HASURA_GRAPHQL_UNAUTHORIZED_ROLE`).
|
||||
4. If multiple candidate tokens are found then an error is raised as the desired token is ambiguous.
|
||||
5. If one candidate token is found then it is verified against the corresponding configured secret.
|
||||
|
||||
|
||||
:::info Note
|
||||
|
||||
Authentication resolution is identical when using `HASURA_GRAPHQL_JWT_SECRET` or a single `HASURA_GRAPHQL_JWT_SECRETS` configuration.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
:::info Note
|
||||
|
||||
If both `HASURA_GRAPHQL_JWT_SECRET` and `HASURA_GRAPHQL_JWT_SECRETS` are set, then `HASURA_GRAPHQL_JWT_SECRETS` will be used.
|
||||
|
||||
:::
|
||||
@ -1,41 +0,0 @@
|
||||
---
|
||||
description: Hasura Cloud multiple admin secrets
|
||||
keywords:
|
||||
- hasura
|
||||
- docs
|
||||
- cloud
|
||||
- security
|
||||
- allow
|
||||
- rotating
|
||||
- multiple
|
||||
- admin
|
||||
- secrets
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# Rotating Admin Secrets
|
||||
|
||||
## Introduction
|
||||
|
||||
You can specify a list of admin secrets which can be used to implement security mechanisms like rotating admin secrets.
|
||||
|
||||
## How to use multiple admin secrets
|
||||
|
||||
Multiple admin secrets can be provided in the env var `HASURA_GRAPHQL_ADMIN_SECRETS` which takes a JSON array of admin secrets (strings).
|
||||
|
||||
When you launch the console from the Hasura Cloud dashboard, you can use any secret from the admin secrets list to authenticate yourself as an admin.
|
||||
If you want to make API calls from outside the console, you need to pass any one of the admin secrets as the `x-hasura-admin-secret` request header.
|
||||
|
||||
:::info Note
|
||||
|
||||
If both `HASURA_GRAPHQL_ADMIN_SECRET` and `HASURA_GRAPHQL_ADMIN_SECRETS` are set, then only `HASURA_GRAPH_ADMIN_SECRETS` will be used.
|
||||
|
||||
:::
|
||||
|
||||
## How to rotate an admin secret
|
||||
|
||||
To implement a secret rotation mechanism, the following can be done:
|
||||
|
||||
1. Add a new secret to the list of admin secrets (and perform a rolling deploy)
|
||||
2. Update applications/services using the old admin secret to use the new secret
|
||||
3. Remove the old secret from the admin secret list (and perform a rolling deploy)
|
||||
Loading…
Reference in New Issue
Block a user