Unauthenticated / Public Access

Introduction

It is a common requirement to have requests which are accessible to all users without the need for authentication or logging in.

Enabling authenticated access with an admin secret

When Hasura GraphQL Engine has a configured admin secret, by default it will reject any unauthenticated request it receives. 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 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.

To set the unauthorized role, you can use the env variable HASURA_GRAPHQL_UNAUTHORIZED_ROLE or the --unauthorized-role flag to define a role name for unauthenticated (non-logged in) users. See GraphQL Engine server config reference for more details on setting this flag or environment variable.

Once that role is set, you can configure permissions for it in the usual way.

Click here 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 in the permissions for 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 permissions.

:::

Unauthenticated request definitions

The following situations are considered unauthenticated requests and will default to the unauthorized role:

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 no matter the headers supplied.
When JWT 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 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

{
    "X-Hasura-Role": "your-unauthorized-role-name",
}
```
To deny the request in webhook mode, a 401 response should be returned. Any response from the webhook which is not a 200 response with a valid role or the above 401 response will raise a 500 Internal Server Error exception in Hasura Engine.