From fcf03919de2f125e78c072fc92b6d36bffca9fa4 Mon Sep 17 00:00:00 2001 From: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com> Date: Mon, 28 Oct 2019 11:46:25 +0530 Subject: [PATCH] add docs page for setting up unauthenticated acess (#3231) --- .../manual/auth/authentication/index.rst | 32 ++++++++++---- .../authentication/unauthenticated-access.rst | 42 +++++++++++++++++++ .../common-roles-auth-examples.rst | 6 +-- 3 files changed, 68 insertions(+), 12 deletions(-) create mode 100644 docs/graphql/manual/auth/authentication/unauthenticated-access.rst diff --git a/docs/graphql/manual/auth/authentication/index.rst b/docs/graphql/manual/auth/authentication/index.rst index 1bb6a9b2488..4f4d04787ea 100644 --- a/docs/graphql/manual/auth/authentication/index.rst +++ b/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 +^^^^^^^^^^ - .. thumbnail:: ../../../../img/graphql/manual/auth/auth-webhook-overview.png +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. -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 request is processed in webhook mode: - .. thumbnail:: ../../../../img/graphql/manual/auth/auth-jwt-overview.png +.. thumbnail:: ../../../../img/graphql/manual/auth/auth-webhook-overview.png -**See more details about these at:** +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: + +.. thumbnail:: ../../../../img/graphql/manual/auth/auth-jwt-overview.png + +**See more details at:** .. toctree:: :maxdepth: 1 Using webhooks Using JWT + Unauthenticated access diff --git a/docs/graphql/manual/auth/authentication/unauthenticated-access.rst b/docs/graphql/manual/auth/authentication/unauthenticated-access.rst new file mode 100644 index 00000000000..cef45a9b1f0 --- /dev/null +++ b/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 `. + +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. + + diff --git a/docs/graphql/manual/auth/authorization/common-roles-auth-examples.rst b/docs/graphql/manual/auth/authorization/common-roles-auth-examples.rst index edf6a56e09a..a3dc13c0209 100644 --- a/docs/graphql/manual/auth/authorization/common-roles-auth-examples.rst +++ b/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 ---------------