Configuration
With JWT-based authentication, the token issuer signs JWT claims, and receivers (an Exograph server, for example) check its validity. Exograph supports two authentication methods out of the box: symmetric key and OpenID Connect. On the Exograph model side, both methods work identically with the @jwt annotation, so nothing changes in the application code.
With the default configuration, the clients pass the Authorization header with the JWT token to the GraphQL endpoint with each request. However, you can change the header name using the EXO_JWT_SOURCE_HEADER environment variable. If you prefer to pass the token in a cookie, you can set the EXO_JWT_SOURCE_COOKIE environment variable. It is an error to set both EXO_JWT_SOURCE_HEADER and EXO_JWT_SOURCE_COOKIE environment variables.
Note that if you use a header to pass the token, the token must be prefixed with Bearer (for example, Authorization: Bearer <token>). If you use a cookie, you should not add the Bearer prefix.
While Exograph has dedicated support for JWT authentication, it is possible to implement other forms of authentication using the @query annotation. For example, you could extract any header value, such as X-API-Token, decode it, and use it in access control rules. See this blog for an esoteric, yet interesting, example.
Symmetric Key
This method uses the same secret key to sign and verify the JWT token. Since it involves a single key, the issuer and receiver must be the same (unless you share the key between the issuing server and the receiving servers, which can be done only in particular situations).
To enable symmetric JWT authentication, set the EXO_JWT_SECRET environment variable to the secret key to exo dev or exo-server commands. You can also set it with exo yolo to override the automatically generated secret key.
EXO_JWT_SECRET=secret exo dev
This helps to keep the secret key stable across multiple invocations of exo yolo.
With this method, your Exograph server must manage users and associated information such as passwords and roles. You can include a type to represent users in your model. You must also provide an authentication query to authenticate users and return a JWT token. You can implement a Deno module that exports a login function. You may also need to implement a "sign-in" mutation. Please see a complete example of using symmetric JWT authentication. The example uses Google Identity, but you can easily extend it to work with other providers and email/password login. Furthermore, you will need another query to refresh the JWT token.
You can alternatively use an external authentication provider such as Auth0 or Clerk, which we will explore next.
OpenID Connect
OpenID Connect (OIDC) is a standard for authentication supported by many authentication providers such as Auth0 and Clerk. The underlying mechanism uses a public/private key pair to sign and verify the JWT token. Unlike symmetric key authentication, OIDC authentication does not require the Exograph server to manage users. Instead, it relies on the authentication provider for that.
To enable OIDC-based authentication, set the EXO_OIDC_URL environment variable to point to the authentication provider's URL to exo dev or exo-server commands.
By default, exo yolo uses symmetric JWT authentication. To use OIDC authentication, specify the EXO_OIDC_URL environment variable.
EXO_OIDC_URL=https://<your-authentication-provider-url> exo yolo
Please see a complete example with Clerk and with Auth0 for how to use OIDC authentication.