add docs page for setting up unauthenticated acess (#3231)

docs/graphql/manual/auth/authentication/index.rst

@@ -16,27 +16,41 @@ Your authentication service is required to pass a user's **role** information in
 variables like ``X-Hasura-Role``, etc. More often than not, you'll also need to pass user information
 for your access control use cases, like ``X-Hasura-User-Id``, to build permission rules.
 
+You can also configure Hasura to allow access to unauthenticated users by configuring a specific role
+which will be set for all unauthenticated requests.
+
 Authentication options
 ----------------------
 
 Hasura supports two modes of authentication configuration:
 
-1) **Webhook**: Your auth server exposes a webhook that is used to authenticate all incoming requests
-   to the Hasura GraphQL engine server and to get metadata about the request, to evaluate access control
-   rules. Here's how a GraphQL request is processed in webhook mode:
+1. Webhook
+^^^^^^^^^^
+
+Your auth server exposes a webhook that is used to authenticate all incoming requests
+to the Hasura GraphQL engine server and to get metadata about the request to evaluate access control
+rules.
+
+Here's how a GraphQL request is processed in webhook mode:
+
+.. thumbnail:: ../../../../img/graphql/manual/auth/auth-webhook-overview.png
+
+2. JWT (JSON Web Token)
+^^^^^^^^^^^^^^^^^^^^^^^
 
-   .. thumbnail:: ../../../../img/graphql/manual/auth/auth-webhook-overview.png
+Your auth server issues JWTs to your client app, which, when sent as part
+of the request, are verified and decoded by the GraphQL engine to get metadata about the request to
+evaluate access control rules.
 
-2) **JWT** (JSON Web Token): Your auth server issues JWTs to your client app, which, when sent as part
-   of the request, are verified and decoded by the GraphQL engine to get metadata about the request to
-   evaluate access control rules. Here's how a GraphQL query is processed in JWT mode:
+Here's how a GraphQL query is processed in JWT mode:
 
-   .. thumbnail:: ../../../../img/graphql/manual/auth/auth-jwt-overview.png
+.. thumbnail:: ../../../../img/graphql/manual/auth/auth-jwt-overview.png
 
-**See more details about these at:**
+**See more details at:**
 
 .. toctree::
   :maxdepth: 1
 
   Using webhooks <webhook>
   Using JWT <jwt>
+  Unauthenticated access <unauthenticated-access>

docs/graphql/manual/auth/authentication/unauthenticated-access.rst

@@ -0,0 +1,42 @@
+Unauthenticated access
+======================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Use case
+--------
+
+It is a common requirement to have requests which are accessible to all users without the need for any authentication
+(logging in). For example, to display a public feed of events.
+
+You can configure Hasura GraphQL engine to allow access to unauthenticated users by defining a specific role
+which will be set for all unauthenticated requests.
+
+Configuring unauthenticated access
+----------------------------------
+
+You can use the env variable ``HASURA_GRAPHQL_UNAUTHORIZED_ROLE`` or ``--unauthorized-role`` flag to set a role
+for unauthenticated (non-logged in) users. See :doc:`../../deployment/graphql-engine-flags/reference` for more details
+on setting this flag/env var.
+
+This role can then be used to define the permissions for unauthenticated users as described in :doc:`../authorization/index`.
+A guide on setting up unauthenticated user permissions can be found :ref:`here <anonymous_users_example>`.
+
+How it works
+------------
+
+Once you have configured authentication, by default Hasura GraphQL engine will reject any unauthenticated request it
+receives.
+
+Based on your authentication setup, an unauthenticated request is any request:
+
+- for which the webhook returns a ``401 Unauthorized`` response in case of :doc:`webhook authentication <./webhook>`.
+- which does not contain a JWT token in case of :doc:`JWT authentication <./jwt>`.
+
+Once an unauthenticated role is configured, unaunthenticated requests will not be rejected and instead the request will
+be made with the configured role.
+
+

docs/graphql/manual/auth/authorization/common-roles-auth-examples.rst

@@ -12,6 +12,8 @@ that will be referred to throughout this guide.
 
 Here are some examples of common use cases.
 
+.. _anonymous_users_example:
+
 Anonymous (not logged in) users
 -------------------------------
 
@@ -26,9 +28,7 @@ Anonymous (not logged in) users
 .. thumbnail:: ../../../../img/graphql/manual/auth/anonymous-role-examples.png
    :class: no-shadow
 
-You can use the env variable ``HASURA_GRAPHQL_UNAUTHORIZED_ROLE`` or ``--unauthorized-role`` flag to set a role
-for non-logged in users. The configured unauthorized role will be used whenever an access token is not present
-in a request to the GraphQL API.
+See :doc:`../authentication/unauthenticated-access` for steps to configure the anonymous user role in Hasura.
 
 Logged-in users
 ---------------