Skip to main content

Enabling authentication

Added in eventcatalog@2.43.0
i
This feature is available on the Scale plan.

To enable authentication for your site, you will need to do three things:

  1. Setup Environment
  2. Enable EventCatalog Server Side Rendering (SSR)
  3. Create your eventcatalog.auth.js file
Authentication is a paid feature

Authentication is a paid feature, and is available on EventCatalog Scale and Enterprise plans.

You can get a 14 day free trial of EventCatalog Scale and Enterprise here.

You will need to set your license key in your .env file.

.env
EVENTCATALOG_LICENSE_KEY=your-license-key

Setup Environment​

EventCatalog uses Auth.js to handle the authentication flow.

Auth.js libraries require you to set an AUTH_SECRET environment variable. This is used to encrypt cookies and tokens. It should be a cryptographically secure random string of at least 32 characters:

This is the only strictly required environment variable. It is the secret used to encode the JWT and encrypt things in transit. We recommend at least a 32 character random string. This can be generated via openssl with openssl rand -base64 33.

.env
AUTH_SECRET=your-secret

AUTH_TRUST_HOST​

When deploying your application behind a reverse proxy, you’ll need to set AUTH_TRUST_HOST equal to true. This tells Auth.js to trust the X-Forwarded-Host header from the reverse proxy. Auth.js will automatically infer this to be true if we detect the environment variable indicating that your application is running on one of the supported hosting providers. Currently VERCEL and CF_PAGES (Cloudflare Pages) are supported.

To learn more about Auth.js, please refer to the Auth.js documentation.

Enable EventCatalog Server Side Rendering (SSR)​

Authentication requires EventCatalog to be SSR enabled. This is because EventCatalog needs to be able to access the user's session to determine if they are authenticated.

To enable SSR, you will need to add the following to your eventcatalog.config.js file:

eventcatalog.config.js
module.exports = {
  // ... other config options
  output: 'server',
};

This will ensure that EventCatalog is rendered on the server side, and that the user's session is available to the client.

Deploying EventCatalog in SSR mode

You will be running EventCatalog in SSR mode when you deploy your site. This means the output of your site will require a server to be running. You can use EventCatalog Docker file to deploy your site or read our deployment guide for more information.

Create your eventcatalog.auth.js file​

The eventcatalog.auth.js file is used to configure the authentication for your site, and is created in the root of your EventCatalog project.

eventcatalog.auth.js
module.exports = {
  // Enable debug mode for development
  debug: false,
  // List of providers you want to enable
  providers: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID,
      clientSecret: process.env.GITHUB_CLIENT_SECRET,
    },
  },
  // Optional session configuration
  session?: {
    // 30 days default
    maxAge?: number;
  };
};

Once you have these three things, you can start setting up your authentication providers.

Setting up your authentication providers​

EventCatalog supports a range of authentication providers, and you can find the documentation for each provider below.

Scale

Setting up GitHub

Enterprise

Setting up Azure AD

Enterprise

Setting up Okta

Enterprise

Setting up Auth0

Missing a provider? Let us know and we'll add it to the list.