Docs: Refactor auth (#448)

Co-authored-by: Sean Park-Ross <[email protected]>
hasura · Jun 27, 2024 · 6bb3ae2 · 6bb3ae2
1 parent 61fee92
commit 6bb3ae2
Show file tree

Hide file tree

Showing 13 changed files with 692 additions and 1,103 deletions.
diff --git a/docs/auth/authentication/index.mdx b/docs/auth/authentication/index.mdx
@@ -1,7 +1,10 @@
 ---
 sidebar_position: 2
 sidebar_label: Auth Config
-description: "Explore our comprehensive guide on setting up Hasura authentication via JWT or a webhook service. Implement effective and secure authentication strategies by learning how to utilize session variables. Manage permissions and integrate with 3rd party authentication providers."
+description:
+  "Explore our comprehensive guide on setting up Hasura authentication via JWT or a webhook service. Implement effective
+  and secure authentication strategies by learning how to utilize session variables. Manage permissions and integrate
+  with 3rd party authentication providers."
 keywords:
   - hasura authentication
   - hasura session variables
@@ -16,87 +19,28 @@ keywords:
 seoFrontMatterUpdated: true
 ---
 
-# Hasura Authentication
+# Authentication & Hasura
 
 ## Introduction
 
 **Authentication verifies the identity of a user.**
 
-Hasura GraphQL Engine utilizes "session variables", with specific user, role, organization and any other information you
-may need to determine the data access rights of the user.
+Hasura DDN utilizes session variables, with specific user, role, organization and any other information you may need to
+determine the data access rights of the user.
 
 With these session variables you are able to define permission rules on your data domain to provide fine-grained access
 control to resources.
 
-Actual authentication is handled outside of Hasura i.e. the responsibility for generating session variables is delegated
-to your (new or existing) authentication service in order to provide you with the greatest flexibility and range of
-options for your authentication needs.
+Hasura is agnostic about your authentication service. Hasura delegates the responsibility of generating session
+variables to your new or existing authentication service, thereby providing you with the greatest flexibility and range
+of options for your authentication needs.
 
-Hasura's authentication can be configured via JSON web tokens (JWT) or a webhook service and can be integrated with any
-other provider you choose (e.g. [Auth0](https://auth0.com/), [Firebase Auth](https://firebase.google.com/products/auth),
+Authentication can be configured via JSON web tokens (JWT) or a webhook service and can be integrated with any provider
+you choose (e.g., [Auth0](https://auth0.com/), [Firebase Auth](https://firebase.google.com/products/auth),
 [AWS Cognito](https://aws.amazon.com/cognito/), a custom solution, etc.) in order to verify the user and set session
 variables that then control access to data.
 
-This document details the `AuthConfig` metadata object used to set up authentication for incoming requests in Hasura.
+## Next steps
 
-## Auth Config {#auth-config}
-
-Only a single `AuthConfig` object can be defined in the metadata. It has the following structure:
-
-| Field                  | Type   | Required | Description                                                                                                              |
-|------------------------|--------|----------|--------------------------------------------------------------------------------------------------------------------------|
-| `allowRoleEmulationBy` | String | false    | Name of the role which allows role emulation. Read more about role emulation [here](./role-emulation.mdx).               |
-| `webhook`              | Object | false    | Configuration of the authentication webhook.                                                                             |
-| `jwt`                  | Object | false    | Configuration of the JWT secret.                                                                                         |
-
-:::info You must select one of the supported authentication modes
-
-In the object, only one of the supported authentication modes (`jwt` or `webhook`) is expected.
-
-:::
-
-## JWT authentication {#jwt-auth-config}
-
-### Example
-
-```yaml
-kind: AuthConfig
-version: v1
-definition:
-  jwt:
-    key:
-      fixed:
-        algorithm: HS256
-        key:
-          value: token
-    tokenLocation:
-      type: BearerAuthorization
-    claimsConfig:
-      namespace:
-        claimsFormat: Json
-        location: "/https:~1~1hasura.io~1jwt~1claims"
-```
-
-For a full description of JWT mode [see here](./jwt.mdx).
-
-## Webhook authentication {#webhook-auth-config}
-
-### Example
-
-```yaml
----
-kind: AuthConfig
-version: v1
-definition:
-  allowRoleEmulationBy: admin
-  webhook:
-    url: http://auth.yourservice.com/validate-request
-    method: Get
-```
-
-| Field    | Type   | Required | Description                                                                                                             |
-|----------|--------|----------|-------------------------------------------------------------------------------------------------------------------------|
-| `url`    | URL    | true     | URL of the authentication webhook.                                                                                      |
-| `method` | String | false    | HTTP method to use while making the request to the authentication webhook. Only `Get` and `Post` methods are supported. |
-
-For a full description of webhook mode [see here](./webhook.mdx).
+- Learn how to [integrate JWTs](auth/authentication/jwt/index.mdx) to authenticate requests to Hasura DDN.
+- Learn how to [integrate webhooks](auth/authentication/webhook/index.mdx) to authenticate requests to Hasura DDN.