CtrlK
BlogDocsLog inGet started
Tessl Logo

webiny-configure-auth0

Configuring Auth0 as an identity provider (IDP) for Webiny projects. Use this skill when the developer asks about Auth0 authentication, Auth0 SSO, replacing Cognito with Auth0, setting up external identity providers, configuring OIDC authentication, mapping JWT claims to Webiny identities, or customizing the Auth0 login flow. Also relevant when asking about AUTH0_ISSUER, AUTH0_CLIENT_ID environment variables, Auth0IdpConfig, or the MyAuth0Extension pattern.

68

Quality

82%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Configure Auth0 Authentication

TL;DR

Webiny supports Auth0 as an external identity provider (IDP) to replace the default Cognito authentication. First, install the @webiny/auth0 package (using the same version as the webiny dependency in package.json). Then create two files: an API config class that maps Auth0 JWT claims to Webiny identity data (Auth0IdpConfig), and a React extension component (<Auth0 />) that wires issuer URL, client ID, and the API config path. Register the extension in webiny.config.tsx, set two environment variables (AUTH0_ISSUER, AUTH0_CLIENT_ID), and deploy.

Pattern / Core Concept

Auth0 integration has two parts:

  1. API Config — A class implementing Auth0IdpConfig.Interface that maps JWT token claims to Webiny's identity structure. Registered via Auth0IdpConfig.createImplementation() (the universal DI pattern).
  2. Extension Component — A React component that renders <Auth0 /> from @webiny/auth0, passing the issuer URL, client ID, and path to the API config file. The <Auth0 /> component handles environment variable injection, API extension registration, and Admin login screen setup automatically.

How <Auth0 /> Works Internally

The <Auth0 /> component (from @webiny/auth0) is a defineExtension that:

  • Sets Lambda env vars: AUTH0_ISSUER, AUTH0_CLIENT_ID
  • Sets Admin app env vars: REACT_APP_IDP_TYPE=auth0, REACT_APP_AUTH0_ISSUER, REACT_APP_AUTH0_CLIENT_ID
  • Registers the internal Auth0IdpFeature API extension (OIDC token verification)
  • Registers your custom API config extension (identity mapping)
  • Registers the Admin Auth0 login screen extension

Reference Tables

Auth0IdpConfig.Interface

MethodSignatureRequiredDescription
getIdentity(token: JwtPayload) => Auth0Identity | Promise<Auth0Identity>YesMaps JWT claims to Webiny identity data
verifyTokenClaims(token: JwtPayload) => void | Promise<void>NoCustom claim verification (throw to reject the token)

Auth0Identity (Return Type of getIdentity)

FieldTypeDescription
idstringUnique user ID (typically token["sub"])
displayNamestringUser's display name
rolesstring[]Webiny security roles to assign
teamsstring[]Webiny teams (optional, filter out falsy values)
profile{ firstName, lastName, email }User profile fields
contextobjectRuntime data (not stored in DB)

<Auth0 /> Component Props

PropTypeDescription
issuerstringAuth0 issuer URL (e.g., https://your-tenant.auth0.com)
clientIdstringAuth0 application client ID
apiConfigstringAbsolute path to the API config file

Environment Variables

VariableUsed ByDescription
AUTH0_ISSUERAPI + AdminAuth0 issuer URL
AUTH0_CLIENT_IDAPI + AdminAuth0 application client ID

Full Examples

Example 1: Basic Auth0 Configuration

Step 0: Install the @webiny/auth0 dependency

@webiny/auth0 is an optional dependency. Add it to package.json using the same version as the webiny dependency, then install:

# Check the webiny version in package.json, then add @webiny/auth0 with the same version
# For example, if "webiny": "^0.0.0-unstable.xxx":
yarn add @webiny/auth0@^0.0.0-unstable.xxx

Important: After adding the dependency, tell the user to run yarn to install it. Do NOT run yarn automatically — let the user do it.

Step 1: Create the API config

Create extensions/auth0/MyAuth0Config.ts:

import { Auth0IdpConfig } from "@webiny/auth0";

class MyIdpConfig implements Auth0IdpConfig.Interface {
  getIdentity(token: Auth0IdpConfig.JwtPayload) {
    return {
      id: String(token["sub"]),
      displayName: token["name"],
      roles: ["full-access"],
      profile: {
        firstName: token["given_name"],
        lastName: token["family_name"],
        email: token["email"]
      },
      context: {
        canAccessTenant: true,
        defaultTenant: "root"
      }
    };
  }
}

const MyAuth0Config = Auth0IdpConfig.createImplementation({
  implementation: MyIdpConfig,
  dependencies: []
});

export default MyAuth0Config;

Step 2: Create the extension component

Create extensions/auth0/MyAuth0Extension.tsx:

import React from "react";
import { Auth0 } from "@webiny/auth0";

export const MyAuth0Extension = () => {
  return (
    <Auth0
      issuer={String(process.env.AUTH0_ISSUER)}
      clientId={String(process.env.AUTH0_CLIENT_ID)}
      apiConfig={import.meta.dirname + "/MyAuth0Config.ts"}
    />
  );
};

Step 3: Register in webiny.config.tsx

import React from "react";
import { MyAuth0Extension } from "./extensions/auth0/MyAuth0Extension.js";

export const Extensions = () => {
  return (
    <>
      {/* Replace <Cognito /> with Auth0 */}
      <MyAuth0Extension />

      {/* ... other extensions ... */}
    </>
  );
};

Step 4: Set environment variables

Add to your .env file (or CI/CD environment):

AUTH0_ISSUER=https://your-tenant.auth0.com/
AUTH0_CLIENT_ID=your-auth0-client-id

Step 5: Deploy

yarn webiny deploy

Example 2: Custom Claim Verification

If your Auth0 setup uses custom claims (e.g., via Auth0 Actions or Rules) that need validation:

import { Auth0IdpConfig } from "@webiny/auth0";

class MyIdpConfig implements Auth0IdpConfig.Interface {
  getIdentity(token: Auth0IdpConfig.JwtPayload) {
    return {
      id: String(token["sub"]),
      displayName: token["name"],
      roles: [token["https://webiny.com/role"]],
      profile: {
        firstName: token["given_name"],
        lastName: token["family_name"],
        email: token["email"]
      },
      context: {
        canAccessTenant: true,
        defaultTenant: "root"
      }
    };
  }

  verifyTokenClaims(token: Auth0IdpConfig.JwtPayload) {
    // Reject tokens without the required custom claim
    if (!token["https://webiny.com/role"]) {
      throw new Error("Token is missing the 'https://webiny.com/role' claim.");
    }

    // Reject tokens from unauthorized organizations
    if (token["org_id"] && token["org_id"] !== "org_expected") {
      throw new Error("User does not belong to the authorized organization.");
    }
  }
}

const MyAuth0Config = Auth0IdpConfig.createImplementation({
  implementation: MyIdpConfig,
  dependencies: []
});

export default MyAuth0Config;

Example 3: Using DI Dependencies in Config

If your config needs access to other Webiny services (e.g., to look up tenant-specific roles):

import { Auth0IdpConfig } from "@webiny/auth0";
import { TenantContext } from "webiny/api/tenancy";

class MyIdpConfig implements Auth0IdpConfig.Interface {
  constructor(private tenantContext: TenantContext.Interface) {}

  getIdentity(token: Auth0IdpConfig.JwtPayload) {
    const tenant = this.tenantContext.getTenant();

    return {
      id: String(token["sub"]),
      displayName: token["name"],
      roles: [token["https://webiny.com/role"]],
      profile: {
        firstName: token["given_name"],
        lastName: token["family_name"],
        email: token["email"]
      },
      context: {
        canAccessTenant: true,
        defaultTenant: tenant?.id ?? "root"
      }
    };
  }
}

const MyAuth0Config = Auth0IdpConfig.createImplementation({
  implementation: MyIdpConfig,
  dependencies: [TenantContext]
});

export default MyAuth0Config;

Quick Reference

Imports

// API config
import { Auth0IdpConfig } from "@webiny/auth0";

// Extension component
import { Auth0 } from "@webiny/auth0";

Key Interfaces

InterfacePackagePurpose
Auth0IdpConfig.Interface@webiny/auth0API-side JWT-to-identity mapping
Auth0IdpConfig.JwtPayload@webiny/auth0JWT token payload type
Auth0IdpConfig.IdentityData@webiny/auth0Identity return type

File Structure

extensions/auth0/
├── MyAuth0Config.ts        # API config (JWT claim mapping)
└── MyAuth0Extension.tsx    # Extension component (Auth0 setup)

Registration

In webiny.config.tsx, replace <Cognito /> with <MyAuth0Extension />.

Deploy

yarn webiny deploy        # Deploy all (Core + API + Admin)

Both API and Admin need to be redeployed since Auth0 affects both the backend (token verification, identity mapping) and the frontend (login screen).

Related Skills

  • webiny-configure-okta — Alternative IDP: configuring Okta authentication
  • webiny-dependency-injection — The universal DI pattern used by Auth0IdpConfig.createImplementation()
  • webiny-project-structure — How webiny.config.tsx and extensions are organized
  • webiny-local-development — Deploying and testing your Auth0 configuration
Repository
webiny/webiny-js
Path

skills/user-skills/configure-auth0/SKILL.md

Commit

484553b

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.

Claim skill