/configure-okta

name: webiny-configure-okta
description: >
  Configuring Okta as an identity provider (IDP) for Webiny projects.
  Use this skill when the developer asks about Okta authentication, Okta SSO,
  replacing Cognito with Okta, setting up external identity providers, configuring
  OIDC authentication, mapping JWT claims to Webiny identities, or customizing
  the Okta login flow. Also relevant when asking about OKTA_ISSUER, OKTA_CLIENT_ID
  environment variables, OktaIdpConfig, or the MyOktaExtension pattern.

Configure Okta Authentication

TL;DR

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

Pattern / Core Concept

Okta integration has two parts:

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

How `<Okta />` Works Internally

The `<Okta />` component (from `@webiny/okta`) is a `defineExtension` that:

• Sets Lambda env vars: `OKTA_ISSUER`, `OKTA_CLIENT_ID`
• Sets Admin app env vars: `REACT_APP_IDP_TYPE=okta`, `REACT_APP_OKTA_ISSUER`, `REACT_APP_OKTA_CLIENT_ID`
• Registers the internal `OktaIdpFeature` API extension (OIDC token verification)
• Registers your custom API config extension (identity mapping)
• Registers the Admin Okta login screen extension

Reference Tables

`OktaIdpConfig.Interface`

| Method | Signature | Required | Description | | ------------------- | -------------------------------------------------------------- | -------- | ----------------------------------------------------- | | `getIdentity` | `(token: JwtPayload) => OktaIdentity \| Promise<OktaIdentity>` | Yes | Maps JWT claims to Webiny identity data | | `verifyTokenClaims` | `(token: JwtPayload) => void \| Promise<void>` | No | Custom claim verification (throw to reject the token) |

`OktaIdentity` (Return Type of `getIdentity`)

| Field | Type | Description | | ------------- | -------------------------------- | ------------------------------------------------ | | `id` | `string` | Unique user ID (typically `token["sub"]`) | | `displayName` | `string` | User's display name | | `roles` | `string[]` | Webiny security roles to assign | | `teams` | `string[]` | Webiny teams (optional, filter out falsy values) | | `profile` | `{ firstName, lastName, email }` | User profile fields | | `context` | `object` | Runtime data (not stored in DB) |

`<Okta />` Component Props

| Prop | Type | Description | | ----------- | -------- | -------------------------------------------------- | | `issuer` | `string` | Okta issuer URL (e.g., `https://dev-xxx.okta.com`) | | `clientId` | `string` | Okta application client ID | | `apiConfig` | `string` | Absolute path to the API config file |

Environment Variables

| Variable | Used By | Description | | ---------------- | ----------- | -------------------------- | | `OKTA_ISSUER` | API + Admin | Okta issuer URL | | `OKTA_CLIENT_ID` | API + Admin | Okta application client ID |

Full Examples

Example 1: Basic Okta Configuration

**Step 0: Install the `@webiny/okta` dependency**

`@webiny/okta` 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/okta with the same version
# For example, if "webiny": "^0.0.0-unstable.xxx":
yarn add @webiny/okta@^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/okta/MyOktaConfig.ts`:

import { OktaIdpConfig } from "@webiny/okta";

class MyIdpConfig implements OktaIdpConfig.Interface {
  getIdentity(token: OktaIdpConfig.JwtPayload) {
    return {
      id: String(token["sub"]),
      displayName: token["name"],
      roles: [token["webiny_group"]],
      teams: [token["team"]].filter(Boolean),
      profile: {
        firstName: token["first_name"],
        lastName: token["last_name"],
        email: token["email"]
      },
      context: {
        canAccessTenant: true,
        defaultTenant: "root"
      }
    };
  }
}

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

export default MyOktaConfig;

**Step 2: Create the extension component**

Create `extensions/okta/MyOktaExtension.tsx`:

import React from "react";
import { Okta } from "@webiny/okta";

export const MyOktaExtension =