Skip to main content

Multiple Authentication Modes

Introduction​

RelyAuth supports configuring multiple authentication modes simultaneously, allowing you to use different authentication methods for different scenarios or clients. This feature enables you to have both JWT and webhook authentication enabled, or multiple configurations of the same authentication type with different settings.

How It Works​

The definitions field is an array that defines a list of authentication strategies. The engine loops over each mode to authenticate in order. The priority of authentication is evaluated by the performance decision:

  • API key: static strings are cheap to compare. Therefore, this mode should be placed at the top.
  • JSON web token (JWT): higher compute resources for signature verification algorithms. However, it is much faster than network latency.
  • Webhook: low priority due to network side effects.
  • No auth: this mode is the bottom option to indicate unauthenticated users if all above auth modes have failed.

You can configure a single authentication mode or multiple authentication modes in the definitions array. When using multiple authentication modes, you can specify exactly which mode to use for a particular request by including the following header:

  • X-Rely-Auth-Mode or X-Hasura-Auth-Mode with the identifier of the desired authentication mode. The engine will select authenticate strategies of that mode to authenticate only.
  • X-Rely-Auth-ID with the identifier of the desired authentication strategy. You should set the id field to each authentication strategy. Otherwise, the engine will automatically fill the ID with the array index.

Configuring Multiple Auth Modes​

Example Configuration​

Here's an example of a configuration file with multiple authentication modes:

version: v1
kind: RelyAuth
definition:
  modes:
    - id: admin
      mode: apiKey
      tokenLocation:
        in: header
        name: Authorization
      value:
        value: "randomsecret"
      sessionVariables:
        x-hasura-role:
          value: admin
    - id: user
      mode: jwt
      tokenLocation:
        in: header
        name: Authorization
        scheme: bearer
      key:
        algorithm: HS256
        key:
          env: JWT_KEY
      claimsConfig:
        namespace:
          location: '"claims.jwt.hasura.io"'
          claimsFormat: Json
    - id: anonymous
      mode: noAuth
      sessionVariables:
        x-hasura-role:
          value: anonymous

In this example:

  • The apiKey authentication mode is validated first.
  • If failed, fallback to the jwt mode with a fixed key.
  • Finally, fallback to the noAuth mode if all above strategies are failed.

Authenticate with a specific Auth Modes​

To use a specific authentication mode when making a request to your API server, include the X-Rely-Auth-Mode header with the identifier of the desired mode.

Example Requests​

Authenticate with all modes:

curl https://your-hasura-endpoint.hasura-ddn.com/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-fixed-key-jwt-token" \
  -d '{"query": "{ users { id name } }"}'

Using the API key mode:

curl https://your-hasura-endpoint.hasura-ddn.com/v1/graphql \
  -H "Content-Type: application/json" \
  -H "X-Rely-Auth-Mode: apiKey" \
  -H "x-hasura-admin-secret: your-api-key" \
  -d '{"query": "{ users { id name } }"}'

Using the JWT mode:

curl https://your-hasura-endpoint.hasura-ddn.com/v1/graphql \
  -H "Content-Type: application/json" \
  -H "X-Rely-Auth-Mode: jwt" \
  -H "Authorization: Bearer your-jwt-token" \
  -d '{"query": "{ users { id name } }"}'

Using the webhook mode:

curl https://your-hasura-endpoint.hasura-ddn.com/v1/graphql \
  -H "Content-Type: application/json" \
  -H "X-Rely-Auth-Mode: webhook" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{"query": "{ users { id name } }"}'

Use Cases​

Multiple authentication modes can be useful in various scenarios:

  1. Development and Testing: Use fixed key JWT for development and webhook for testing, and switch to production custom claims JWT mode when ready
  2. Multiple Client Types: Support different authentication methods for different client applications
  3. Migration: Gradually migrate from one authentication provider to another (or from one permission model to another)
  4. Admin Access: Provide a separate authentication mode for administrative access

Security Considerations​

When using multiple authentication modes:

  • Set up role-based permissions for each authentication mode to control data access appropriately.
  • Keep in mind that the X-Rely-Auth-Mode header may be included in standard HTTP request monitoring tools, just like other headers.
  • Consider using network controls and security rules (like IP allowlists) to control which clients can use specific authentication modes.

Next Steps​