hasura/graphql-engine
1
0
Fork 0
mirror of https://github.com/hasura/graphql-engine.git synced 2024-09-11 10:46:25 +03:00
Code Issues Projects Releases Wiki Activity

Docs: Update unauthenticated access documentation with detailed steps and restructure content.

Browse Source 
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/10003
GitOrigin-RevId: 5b181e248f80102796437961df15af7afb1c0cce
This commit is contained in:
Sean Park-Ross 2023-07-31 18:46:26 +07:00 committed by hasura-bot
parent 0abf4368ae
commit 662607dadf
1 changed files with 38 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
docs/docs/auth/authentication/unauthenticated-access.mdx
View File

@ -16,21 +16,33 @@ sidebar_position: 40
It is a common requirement to have requests which are accessible to all users without the need for authentication or
logging in.
Once you have configured an [admin secret](/deployment/securing-graphql-endpoint.mdx), by default Hasura GraphQL Engine
will reject any unauthenticated request it receives.
## Enabling authenticated access with an admin secret
When Hasura GraphQL Engine has a configured [admin secret](/deployment/securing-graphql-endpoint.mdx), by default it
will reject any [unauthenticated request it receives](#unauthenticated-request-definitions). We need to configure an
unauthorized role in order to handle these requests via the Hasura permissions system.
## Enabling unauthenticated access with a unauthorized role
You can configure the Hasura Engine to allow access to unauthenticated users by defining a specific role which will be
used for all unauthenticated requests. Once an unauthenticated role is configured, unauthenticated requests will not be
used for all unauthenticated requests. Once an unauthorized role is configured, unauthenticated requests will not be
rejected and instead will be handled as the unauthenticated user with the relevant authorization permissions for that
role taking effect.
A guide on setting up permissions for the unauthenticated role can be found
[here](/auth/authorization/permissions/common-roles-auth-examples.mdx#unauthorized-users-example).
To set the unauthorized role, you can use the env variable
[`HASURA_GRAPHQL_UNAUTHORIZED_ROLE` or the `--unauthorized-role` flag](/deployment/graphql-engine-flags/reference.mdx#unauthorized-role)
to define a role name for unauthenticated (non-logged in) users. See
[GraphQL Engine server config reference](/deployment/graphql-engine-flags/index.mdx) for more details on setting this
flag or environment variable.
:::warning Risk of session variables with the unauthenticated role
Once that role is set, you can [configure permissions for it in the usual way](/auth/authorization/permissions/common-roles-auth-examples.mdx).
[Click here](/auth/authorization/permissions/common-roles-auth-examples.mdx#unauthorized-users-example) for a guide on setting up permissions for the unauthorized role.
:::warning Risk of session variables with the unauthorized role
You should not use [session variables](/auth/authorization/roles-variables.mdx#session-variables) in the permissions for
an unauthenticated role because the source of the session variables cannot be trusted.
an unauthorized role because the source of the session variables cannot be trusted.
Since session variables can be passed using request headers and they are not verified through the JWT or webhook
authentication methods or utilize an admin secret, a user can choose to set any values for them and bypass the
@ -38,29 +50,25 @@ permissions.
:::
## Configuring unauthenticated / public access
### Unauthenticated request definitions
You can use the env variable
[`HASURA_GRAPHQL_UNAUTHORIZED_ROLE` or the `--unauthorized-role` flag](/deployment/graphql-engine-flags/reference.mdx#unauthorized-role)
to define a role for unauthenticated (non-logged in) users. See
[GraphQL Engine server config reference](/deployment/graphql-engine-flags/index.mdx) for more details on setting this
flag or environment variable.
The following situations are considered unauthenticated requests and will default to the unauthorized role:
### No-auth setup
- When [JWT](/auth/authentication/jwt.mdx) or [webhook](/auth/authentication/webhook.mdx) modes are not configured, and
the request does not contain the admin secret header, then every request is considered an unauthenticated request
no matter the headers supplied.
- When [JWT](/auth/authentication/jwt.mdx) mode is configured, and the request does not contain the admin secret
header, then a request will be considered unauthenticated if it does not have a JWT.
- When [webhook](/auth/authentication/webhook.mdx) mode is configured, and the request does not contain the admin
secret header, then a request will be considered unauthenticated if the webhook returns the following response:
```http
HTTP/1.1 200 OK
Content-Type: application/json
When JWT or webhook modes are not configured, and the request does not contain the admin secret header, then every
request is considered an unauthenticated request.
### JWT
For [JWT authentication mode](/auth/authentication/jwt.mdx), any request which does not contain a JWT token is
considered an unauthenticated request.
### Webhooks
When using [webhook mode](/auth/authentication/webhook.mdx), any request for which the webhook returns a
`401 Unauthorized` response is denied.
To allow unauthenticated access, say for public data, the server must be configured with an unauthorized role and the
auth webhook should return a `200` status response with your unauthenticated role specified in the headers. For details
on the webhook response, refer to [this section](/auth/authentication/webhook.mdx#webhook-response).
{
"X-Hasura-Role": "your-unauthorized-role-name",
}
```
To deny the request in webhook mode, a `401` response [should be returned](/auth/authentication/webhook.mdx#auth-denial).
Any response from the webhook which is not a `200` [response with a valid role](/auth/authentication/webhook.mdx#success)
or the above `401` response will raise a `500 Internal Server Error` exception in Hasura Engine.