Authentication Concepts

• Authentication Methods
• Primary Authentication Methods
• Secondary Authentication Methods and Multi-factor Authentication
• API Key Authentication
• Authentication Token
• Graphweaver Config
• Forbidden Requests
• X-Auth-Redirect header
• X-Auth-Request-Redirect and AUTH_BASE_URI
• Whitelisted Domains
• Authentication GraphQL Errors
• ForbiddenError
• ChallengeError
• RestrictedFieldError
• Environment Variables

Many of the basic integration tasks are implemented for you in Graphweaver. However, there are a number of concepts and configuration options that are important to understand.

Authentication Methods

There are a number of pre-built authentication methods. Some of these can be used as a primary authentication method. That is an authentication method that can be exchanged for an authentication token. There are also secondary authentication methods. These are methods that can be used to step-up your authentication. For example, you can login with the primary authentication method such as password then require a step up using One Time Password when writing data.

Primary Authentication Methods

The following primary authentication methods are available:

• Password
• Magic Links
• Auth0

Secondary Authentication Methods and Multi-factor Authentication

The following secondary authentication methods are available:

• Password
• Magic Links
• One Time Password
• Web3
• Passkey

API Key Authentication

API Key authentication can be used when you need machine-to-machine communication. This allows another service to call your Graphweaver instance. For more information on setting up API Key Authentication see the 🗝️Adding API Key Authentication page.

Authentication Token

The authentication token used by Graphweaver is a JWT. The JWT stores very little information so that it stays small and does not become bloated. Here is the contents of a typical JWT:

{
  "sub": "1",
  "amr": [
    "pwd"
  ],
  "iat": 1723614685,
  "exp": 1723643485
}

Let’s look at each part:

Graphweaver Config

In order to implement authentication on Graphweaver you need to use the Graphweaver config.

Each of these keys are inside the path adminUI.auth .

Forbidden Requests

X-Auth-Redirect header

This header is returned from the server to tell the client where it should send the user. This is used in the AdminUI to redirect users for authentication requests. This can also be used by an external app to redirect users as needed.

X-Auth-Request-Redirect and AUTH_BASE_URI

This header is sent from the client to the server to redirect the user after a successful login. This has the potential to be hijacked by an unauthorised request so only whitelisted domains can be redirected to.

Whitelisted Domains

Whitelisted domains are domains that have been authorised for redirection. This is used to check that a X-Auth-Request-Redirect header is a valid URL before allowing redirection.

Authentication GraphQL Errors

The authentication system uses several custom error classes. While not always returned to the client directly, these errors may appear in the errors array of a GraphQL response if they occur.

ForbiddenError

A ForbiddenError is thrown when a request attempts to access a restricted part of the graph. This indicates that the request violates the Access Control List (ACL) applied to the requested entity.

ChallengeError

This error occurs when a request requires a higher level of authentication. When this error is caught, an X-Auth-Redirect header is returned to the client, triggering a redirect to the appropriate authentication step.

RestrictedFieldError

This is an internal error not exposed to the client. It's thrown when a request tries to access a field that the current user does not have permission to view or write to.

Environment Variables

There are a number of environment variable that you can configure in Graphweaver to change the defaults.