Skip to main content

RelyAuth Concepts

Concepts​

RelyAuth manages a set of authentication policies that authenticate users' requests with the fallback strategy. The authenticator engine authenticates requests and passes session variables via valid credentials to be checked against your access control rules or "permissions" to determine what data the user can access.

Authentication modes​

RelyAuth can be set up in multiple modes. 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 which mode to use for a particular request by including the X-Rely-Auth-Mode or X-Hasura-Auth-Mode header with the identifier of the desired authentication mode.

API Key​

Your authentication service must include the static API key in an HTTP header, query or cookies that are passed to the Engine by the client on each request. Read more.

JSON Web Token (JWT)​

Your authentication service must issue JWTs which contain session variables that are passed to the engine by the client on each request. Read more.

Webhook​

The engine will call a webhook on each request with the client headers forwarded. On successful authentication, the webhook must return a valid http response with session variables in the body. Read more.

NoAuth mode​

No authentication is required for a specific role to access the data. Read more.

Transformation​

Sometimes configurations of third-party integration can not satisfy your needs, for example, incorrect JWT claims format, custom webhook requests or responses. In these use cases, transformation templates can help you.

RelyAuth supports 2 transformation templates. You can select or transform request and response bodies to your desired format:

  • JMESPath: the query language is evaluated against the JSON data. It is more powerful than JSONPath and JSON pointer with transform pipeline supports.
  • Go template: the built-in template of Go is great for generating dynamic text output. RelyAuth extends that template library with Sprig functions.

Transformation is supported for jwt and webhook authentication modes.

Harden the Security​

Security Rules​

You can configure the extra security rules for each authentication mode, such as allowed IPs and header matchings.

mTLS​

You can setup TLS certificates to the HTTP server for hardening the security. However, it is set up globally and you need to combine it with an auth mode such as NoAuth or API Key.