Authentication and Authorization

When using Zendro in a default setup, Zendro implements authorization and authentication of users and roles via OAuth2, using third-party libraries to provide a secure and stable experience.

As an OAuth2 backend, Zendro sets up a keycloak server to handle all authentication and user management, which also supports OpenID Connect. Zendro itself, when started with authorization rules enabled, only requires a valid access_token to be present in the request header.

The two web interfaces authenticate differently:

single-page-app uses NextAuth.js to talk to Keycloak directly, using the recommended OAuth2 Authorization Code grant flow to exchange an authorization code for an access token.
GraphiQL holds no Keycloak credentials of its own. graphql-server runs a small auth backend on its behalf (login/callback/logout, using OIDC discovery against your identity provider) — GraphiQL just redirects the browser there.

Keycloak
Using a different authorization service
Requesting an access token for third-party requests

Keycloak

When setting up a new Zendro instance using the Zendro CLI and the recommended docker setup, a default Keycloak migration sets up the necessary infrastructure on the Keycloak server. This includes creating a default user, default roles, and the OAuth2 clients for the different Zendro interfaces (graphql-server, graphiql-auth, single-page-app). This migration runs automatically on the first startup of any Zendro installation, unless manually removed from the graphql-server/migrations folder. For more detail, see the Keycloak documentation.

User management

All user management is handled by Keycloak. To create new users, set their permissions, reset passwords, etc., use the Keycloak admin-cli, available by default at:

<your-url>:8081/auth

Also refer to the Keycloak documentation on how to manage users.

Third-party identity providers

Keycloak can be configured to delegate authentication to one or more identity providers — social login via Facebook or Google is one example of identity provider federation. You can also hook Keycloak up to delegate authentication to any other OpenID Connect or SAML 2.0 identity provider.

Role management

By default, Zendro exposes three different roles for its users — see Roles for the full breakdown of administrator, editor and reader, and how roles are decoded from the access token.

Environment variables

To configure the Zendro interfaces to correctly connect to Keycloak (or any other OAuth2 endpoint), a set of environment variables is exposed to the user — see Environment variables for the full reference. The most relevant ones here:

GraphQL server

OAUTH2_TOKEN_URI - Endpoint of the OAuth2 token service
OAUTH2_PUBLIC_KEY- OAuth2 service public key used to encrypt / verify tokens
OAUTH2_CLIENT_ID- GraphQL server OAuth2 Client ID
AUTH_REDIRECT_URI- Comma-separated redirect URIs graphql-server’s own auth backend is allowed to send users back to (one per GraphiQL/SPA deployment)
SPA_REDIRECT_URI- RedirectURI of the single-page-app client, used to migrate the default Keycloak OAuth2 service
AUTH_ENABLED, OAUTH2_GRAPHIQL_CLIENT_ID, OAUTH2_GRAPHIQL_CLIENT_SECRET, OAUTH2_GRAPHIQL_ISSUER_URI, SESSION_SECRET - configure graphql-server’s own auth backend, used on GraphiQL’s behalf

Single-page-app

OAUTH2_ISSUER - OAuth2 Issuer URL
OAUTH2_TOKEN_URI - Endpoint of the OAuth2 token service
OAUTH2_CLIENT_ID - SPA OAuth2 Client ID
OAUTH2_CLIENT_SECRET - SPA OAuth2 Client Secret
NEXTAUTH_URL - When deploying to production, set this to the canonical URL of your site
NEXTAUTH_SECRET - Used to encrypt the NextAuth.js JWT, and to hash email verification tokens

Using a different authorization service

If you do not want to use Keycloak as the authorization service for your Zendro installation, set the environment variables above to your needs — the two web interfaces are customized differently, since they authenticate differently (see above):

GraphiQL talks to graphql-server’s own auth backend, which discovers its identity provider via OIDC discovery — any OIDC-compliant provider works out of the box by pointing OAUTH2_GRAPHIQL_ISSUER_URI at it, no code changes needed.
single-page-app uses NextAuth.js, so a non-OIDC provider needs a custom provider definition (NextAuth also ships a long list of built-in providers). Customize this in single-page-app’s src/pages/api/auth/[...nextauth].ts — either reconfigure the default zendro Keycloak provider, or add your custom provider to the providers list:
```
{
  providers: [
    // ...add more providers here
    {
      id: 'zendro',
      // ...
    },
    {
  	// add your custom provider
    }
  ]
}
```

Requesting an access token for third-party requests

To support requesting an access token from the GraphQL server, the OAuth2 graphql-server client supports the password grant type. Those tokens can then be used by any third-party script — e.g. Python, R, curl — to request data via Zendro’s GraphQL API.

Example using curl:

Request a token:

curl -X POST --url <oauth2-token-url> -d 'Content-Type: application/x-www-form-urlencoded' -d grant_type=password -d client_id=<graphql-server-client_id> -d username=<username> -d password=<password>

Send it in the header:

curl --url <graphql-server>/graphql -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer <access_token>' -d '{"query": "{ ...<your query> }" }'

Roles