is a free service by `OneGraph <https://www.onegraph.com/>`__ that allows you to both add sign-on with dozens of services like GitHub, Twitch, Stripe, Salesforce, and more, and also to easily visually describe authentication and authorization rules for your app, API, or service.
It will generate JWTs compatible with any service that supports JWTs - like Hasura! And on top of that, AuthGuardian has built-in support for generating Hasura roles to make working with Hasura's permission system as easy as possible.
Step 1: Create an account
^^^^^^^^^^^^^^^^^^^^^^^^^
Sign into `OneGraph <https://www.onegraph.com/>`__ with either GitHub or an email/password.
On the left sidebar, chose "Auth Services" and then "AuthGuardian", and we're ready to start!
Step 2: Add an auth rule
^^^^^^^^^^^^^^^^^^^^^^^^
AuthGuardian works with two basic concepts: ``rules`` and ``effects``.
``Effects`` are useful for modifying the JWT during sign-in. AuthGuardian supports four ``effects``:
- Set the ``user_id`` for Hasura in the JWT
- Set the default Hasura user role in the JWT
- Set the allowed Hasura user roles in the JWT
- Set session variables for Hasura to use in the JWT
These can all be mixed and matched when creating Hasura-compatible JWTs to fully cover your app's permission settings.
The second concept, ``rules`` determines whether the ``effects`` are allowed to be added to the JWT. The rules might look like:
- "If this user is logged into Twitch.tv"
- "If this user has an email on Salesforce that belongs to my organization's domain"
- "If this user is a member of my GitHub organization"
Let's see how to use these ``rules`` and ``effects`` in action!
Option 1: Set Hasura ``user_id``
--------------------------------
Let's say you're using GitHub as the primary login for your Hasura app, and that you want to use their GitHub ``user_id`` as a primary key:
- For the section "When the user on", select ``GitHub`` -> ``login status`` -> ``is true`` ("When this user is logged into GitHub")
- For the section "Then", choose ``On hasura set user id``.
- Add set the user id in the "built-in value" field to ``GITHUB_USER_ID``
- Click the ``save`` button on the right hand side.
Note that AuthGuardian knows that Hasura requires that the ``default role``*also* appear in the list of ``x-hasura-allowed-roles``, and added it in both places automatically.
Option 3: Allow additional Hasura roles
---------------------------------------
Now, you want to restrict access to some data in Hasura so that only you and your teammates can read it. We'll use Hasura's permissions to restrict data to those who have an ``admin`` role, and use AuthGuardian's rules to set that role in the JWT to people who belong to your GitHub organization:
- For the section "When the user is on", select ``GitHub`` -> ``is member of organization named`` -> ``<your org name, e.g. AcmeCo>`` ("When this user is a member of AcmeCo on GitHub")
- For the section "Then", choose ``On hasura add roles``.
- Click on "Add" and add an additional role, e.g. ``admin``.
- Click the ``save`` button on the right hand side.
:alt:Set an AuthGuardian JWT with additional roles
Option 4: Set a session variable
--------------------------------
Hasura can use **session variables** for all sorts of `powerful cases <https://docs.hasura.io/1.0/graphql/manual/auth/authorization/roles-variables.html#dynamic-session-variables>`_. AuthGuardian also supports setting these in your JWT!
Let's say we want to restrict access to some super-interesting data in our Hasura backend to users who have starred a particular GitHub repository:
- For the section "When the user is on", select ``GitHub`` -> ``has starred a repository with a full name of`` -> ``hasura/graphql-engine`` ("When this user has starred the 'hasura/graphql-engine' on GitHub")
- For the section "Then", choose ``On hasura set session variable``.
- Add your session variable name ``is-our-biggest-fan`` and value to JSON ``true``.
- Click the ``save`` button on the right hand side.
:alt:Use the JWT-signer form to quickly sign any JSON and test in the Hasura console
- In GraphiQL, try out queries to test that the integration works as expected by adding an ``Authorization`` header, with a value of ``Bearer <the-copied-JWT-text>``. Hasura's GraphiQL will recognize this header, show you its content, and confirm whether it recognizes the JWT as securely signed.
AuthGuardian supports much more, including the ability to eject your rules as a pair of GraphQL request and JavaScript function so you can customize the auth as necessary. To read more about it, please visit the `AuthGuardian docs <https://www.onegraph.com/docs/>`__.
