mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-10-26 10:20:54 +03:00
Docs: improve backend-only permissions
[DOCS-1983]: https://hasurahq.atlassian.net/browse/DOCS-1983?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ PR-URL: https://github.com/hasura/graphql-engine-mono/pull/10776 GitOrigin-RevId: 7252aad199edfabe0d207edfa3f437f2ccaeab94
This commit is contained in:
parent
8b0ae5fcb0
commit
c42aeb15e3
@ -17,34 +17,27 @@ import TabItem from '@theme/TabItem';
|
|||||||
|
|
||||||
## Introduction
|
## Introduction
|
||||||
|
|
||||||
If a mutation permission is marked as "backend only", it is accessible to the given role only if the
|
Backend only permissions in Hasura allow certain mutations to be hidden from the public-facing API while still
|
||||||
`x-hasura-use-backend-only-permissions` session variable exists on the request and is set to `true`. The
|
accessible via a trusted backend. This is useful for operations that should bypass standard client-side validation or
|
||||||
`x-hasura-admin-secret` must also be present if any auth is configured.
|
business logic, ensuring that only authorized back-end services can perform these operations.
|
||||||
|
|
||||||
This is useful if you would like to hide a mutation from a public facing API but allow access to it via a trusted
|
|
||||||
backend.
|
|
||||||
|
|
||||||
Setting "backend only" is available for `insert`, `update` and `delete` mutations.
|
Setting "backend only" is available for `insert`, `update` and `delete` mutations.
|
||||||
|
|
||||||
<Tabs groupId="user-preference" className="api-tabs">
|
<Tabs groupId="user-preference" className="api-tabs">
|
||||||
<TabItem value="console" label="Console">
|
<TabItem value="console" label="Console">
|
||||||
|
Set a mutation permission for a role as backend only in the Hasura Console under **Data -> [table] -> Permissions ->
|
||||||
You can set a mutate permission for a role as backend only in the Hasura Console in **Data -> [table] -> Permissions ->
|
[role] -> insert / update / delete -> Backend only**
|
||||||
[role] -> insert / update / delete -> Backend only **
|
|
||||||
|
|
||||||
<Thumbnail
|
<Thumbnail
|
||||||
src="/img/auth/allow-backends-only_console_2.10.1.png"
|
src="/img/auth/allow-backends-only_console_2.10.1.png"
|
||||||
alt="Allow backends only in Hasura Console"
|
alt="Allow backends only in Hasura Console"
|
||||||
width="600px"
|
width="600px"
|
||||||
/>
|
/>
|
||||||
|
|
||||||
</TabItem>
|
</TabItem>
|
||||||
<TabItem value="cli" label="CLI">
|
<TabItem value="cli" label="CLI">
|
||||||
|
Set a mutation permission for a role as backend only in the `metadata -> databases -> [database-name] -> tables ->
|
||||||
|
[table-name].yaml` file, e.g., `public_users.yaml`:
|
||||||
|
|
||||||
You can set a mutate permission for a role as backend only in the `metadata -> databases -> [database-name] -> tables ->
|
```yaml
|
||||||
[table-name].yaml` file, eg: `public_users.yaml`:
|
|
||||||
|
|
||||||
```yaml {10,14}
|
|
||||||
table:
|
table:
|
||||||
name: users
|
name: users
|
||||||
schema: public
|
schema: public
|
||||||
@ -65,15 +58,14 @@ delete_permissions:
|
|||||||
</TabItem>
|
</TabItem>
|
||||||
<TabItem value="api" label="API">
|
<TabItem value="api" label="API">
|
||||||
|
|
||||||
You can set a mutate permission for a role as backend only with the Metadata API and the
|
Set a mutate permission for a role as backend only with the Metadata API using the
|
||||||
[insert](/api-reference/syntax-defs.mdx#insertpermission), [update](/api-reference/syntax-defs.mdx#updatepermission) or
|
[insert](/api-reference/syntax-defs.mdx#insertpermission), [update](/api-reference/syntax-defs.mdx#updatepermission), or
|
||||||
[delete](/api-reference/syntax-defs.mdx#deletepermission) permissions.
|
[delete](/api-reference/syntax-defs.mdx#deletepermission) permissions.
|
||||||
|
|
||||||
```http {19}
|
```http
|
||||||
POST /v1/metadata HTTP/1.1
|
POST /v1/metadata HTTP/1.1
|
||||||
Content-Type: application/json
|
Content-Type: application/json
|
||||||
X-Hasura-Role: admin
|
X-Hasura-Role: admin
|
||||||
|
|
||||||
{
|
{
|
||||||
"type": "pg_create_insert_permission",
|
"type": "pg_create_insert_permission",
|
||||||
"args": {
|
"args": {
|
||||||
@ -100,7 +92,47 @@ X-Hasura-Role: admin
|
|||||||
|
|
||||||
:::info Supported from
|
:::info Supported from
|
||||||
|
|
||||||
Backend only permissions for `update` and `delete` mutations are supported in Hasura GraphQL Engine versions `v2.8.0`
|
Backend only permissions for update and delete mutations are supported in Hasura GraphQL Engine versions v2.8.0 and
|
||||||
and above.
|
above.
|
||||||
|
|
||||||
:::
|
:::
|
||||||
|
|
||||||
|
## How it Works
|
||||||
|
|
||||||
|
### Scenarios
|
||||||
|
|
||||||
|
Backend only permissions create two operation modes within Hasura:
|
||||||
|
|
||||||
|
- Frontend Scenario: All mutation operations are visible when no backend-only permissions are set.
|
||||||
|
- Backend Scenario: Specific mutations set with backend-only permissions become visible only when the
|
||||||
|
x-hasura-use-backend-only-permissions header is set to true.
|
||||||
|
|
||||||
|
### Schema Generation
|
||||||
|
|
||||||
|
Hasura maintains two GraphQL schemas per role per table:
|
||||||
|
|
||||||
|
| Schema Type | Description | Example |
|
||||||
|
| ------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
|
| **Frontend Schema** | Visible mutations without backend-only permissions. | Given a role "public" and a table "user", mutations like `insert_user` and `delete_user` are visible by default. |
|
||||||
|
| **Backend Schema** | Mutations visible only when backend-only permissions are enabled. | For the same role and table, the `update_user` mutation is only visible when the `x-hasura-use-backend-only-permissions` header is set to `true`. |
|
||||||
|
|
||||||
|
All operations are visible by default.
|
||||||
|
|
||||||
|
### Access Requirements
|
||||||
|
|
||||||
|
For a mutation to be accessible under backend only permissions, the following conditions must be met:
|
||||||
|
|
||||||
|
- `x-hasura-admin-secret` is present if authorization is configured.
|
||||||
|
- `x-hasura-use-backend-only-permissions` must be set to `true`.
|
||||||
|
- `x-hasura-role` is used to identify the role.
|
||||||
|
|
||||||
|
This table outlines the visibility of mutations based on the `Backend Only` permission along with the presence of
|
||||||
|
necessary headers:
|
||||||
|
|
||||||
|
| Backend Only | `x-hasura-admin-secret` | `x-hasura-use-backend-only-permissions` | Result |
|
||||||
|
| ------------ | ----------------------- | --------------------------------------- | -------------- |
|
||||||
|
| FALSE | ANY | ANY | Always Visible |
|
||||||
|
| TRUE | FALSE | ANY | Always Hidden |
|
||||||
|
| FALSE | TRUE | ANY | Always Visible |
|
||||||
|
| TRUE | TRUE (OR NOT-SET) | FALSE | Hidden |
|
||||||
|
| TRUE | TRUE (OR NOT-SET) | TRUE | Shown |
|
||||||
|
Loading…
Reference in New Issue
Block a user