@webiny/mcp 6.0.0-rc.5 → 6.0.0-rc.7

package/skills/configure-okta/SKILL.md

@@ -0,0 +1,303 @@
+---
+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:
+
+```bash
+# 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`:
+
+```typescript
+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`:
+
+```tsx
+import React from "react";
+import { Okta } from "@webiny/okta";
+
+export const MyOktaExtension = () => {
+  return (
+    <Okta
+      issuer={String(process.env.OKTA_ISSUER)}
+      clientId={String(process.env.OKTA_CLIENT_ID)}
+      apiConfig={import.meta.dirname + "/MyOktaConfig.ts"}
+    />
+  );
+};
+```
+
+**Step 3: Register in `webiny.config.tsx`**
+
+```tsx
+import React from "react";
+import { MyOktaExtension } from "./extensions/okta/MyOktaExtension.js";
+
+export const Extensions = () => {
+  return (
+    <>
+      {/* Replace <Cognito /> with Okta */}
+      <MyOktaExtension />
+
+      {/* ... other extensions ... */}
+    </>
+  );
+};
+```
+
+**Step 4: Set environment variables**
+
+Add to your `.env` file (or CI/CD environment):
+
+```
+OKTA_ISSUER=https://dev-xxxxx.okta.com/oauth2/default
+OKTA_CLIENT_ID=your-okta-client-id
+```
+
+**Step 5: Deploy**
+
+```bash
+yarn webiny deploy
+```
+
+### Example 2: Custom Claim Verification
+
+If your Okta setup uses custom claims that need validation:
+
+```typescript
+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_role"]],
+      profile: {
+        firstName: token["given_name"],
+        lastName: token["family_name"],
+        email: token["email"]
+      },
+      context: {
+        canAccessTenant: true,
+        defaultTenant: "root"
+      }
+    };
+  }
+
+  verifyTokenClaims(token: OktaIdpConfig.JwtPayload) {
+    // Reject tokens without the required custom claim
+    if (!token["webiny_role"]) {
+      throw new Error("Token is missing the 'webiny_role' claim.");
+    }
+
+    // Reject tokens from unauthorized organizations
+    const allowedOrgs = ["org_abc123", "org_def456"];
+    if (!allowedOrgs.includes(token["org_id"] as string)) {
+      throw new Error("User does not belong to an authorized organization.");
+    }
+  }
+}
+
+const MyOktaConfig = OktaIdpConfig.createImplementation({
+  implementation: MyIdpConfig,
+  dependencies: []
+});
+
+export default MyOktaConfig;
+```
+
+### Example 3: Using DI Dependencies in Config
+
+If your config needs access to other Webiny services (e.g., to look up tenant-specific roles):
+
+```typescript
+import { OktaIdpConfig } from "@webiny/okta";
+import { TenantContext } from "webiny/api/tenancy";
+
+class MyIdpConfig implements OktaIdpConfig.Interface {
+  constructor(private tenantContext: TenantContext.Interface) {}
+
+  getIdentity(token: OktaIdpConfig.JwtPayload) {
+    const tenant = this.tenantContext.getTenant();
+
+    return {
+      id: String(token["sub"]),
+      displayName: token["name"],
+      roles: [token["webiny_group"]],
+      profile: {
+        firstName: token["first_name"],
+        lastName: token["last_name"],
+        email: token["email"]
+      },
+      context: {
+        canAccessTenant: true,
+        defaultTenant: tenant?.id ?? "root"
+      }
+    };
+  }
+}
+
+const MyOktaConfig = OktaIdpConfig.createImplementation({
+  implementation: MyIdpConfig,
+  dependencies: [TenantContext]
+});
+
+export default MyOktaConfig;
+```
+
+## Quick Reference
+
+### Imports
+
+```typescript
+// API config
+import { OktaIdpConfig } from "@webiny/okta";
+
+// Extension component
+import { Okta } from "@webiny/okta";
+```
+
+### Key Interfaces
+
+| Interface                    | Package        | Purpose                          |
+| ---------------------------- | -------------- | -------------------------------- |
+| `OktaIdpConfig.Interface`    | `@webiny/okta` | API-side JWT-to-identity mapping |
+| `OktaIdpConfig.JwtPayload`   | `@webiny/okta` | JWT token payload type           |
+| `OktaIdpConfig.IdentityData` | `@webiny/okta` | Identity return type             |
+
+### File Structure
+
+```
+extensions/okta/
+├── MyOktaConfig.ts        # API config (JWT claim mapping)
+└── MyOktaExtension.tsx    # Extension component (Okta setup)
+```
+
+### Registration
+
+In `webiny.config.tsx`, replace `<Cognito />` with `<MyOktaExtension />`.
+
+### Deploy
+
+```bash
+yarn webiny deploy        # Deploy all (Core + API + Admin)
+```
+
+Both API and Admin need to be redeployed since Okta affects both the backend (token verification, identity mapping) and the frontend (login screen).
+
+## Related Skills
+
+- **dependency-injection** — The universal DI pattern used by `OktaIdpConfig.createImplementation()`
+- **project-structure** — How `webiny.config.tsx` and extensions are organized
+- **local-development** — Deploying and testing your Okta configuration

package/skills/custom-graphql-api/SKILL.md

@@ -13,187 +13,197 @@ description: >
 
 ## TL;DR
 
-Add custom GraphQL queries and mutations using the `GraphQLSchemaFactory` pattern. Define `typeDefs` and `resolvers`, inject backend services (identity, tenancy, CMS use-cases) via constructor DI, and export with `GraphQLSchemaFactory.createImplementation()`. Register in `webiny.config.tsx` as `<Api.Extension>`.
+Add custom GraphQL queries and mutations using the `GraphQLSchemaFactory` builder pattern. Implement `GraphQLSchemaFactory.Interface`, use the builder to add type definitions and resolvers (with per-resolver DI), and export with `GraphQLSchemaFactory.createImplementation()`. Register as `<Api.Extension>`.
 
 ## The GraphQLSchemaFactory Pattern
 
+The `execute` method receives a `builder` (`GraphQLSchemaBuilder.Interface`) and returns it after adding type defs and resolvers.
+
 ```typescript
-// extensions/MyGraphQLSchema.ts
+// extensions/mySchema/MyGraphQLSchema.ts
 import { GraphQLSchemaFactory } from "webiny/api/graphql";
 
-class SchemaImpl implements GraphQLSchemaFactory.Interface {
-    execute(): GraphQLSchemaFactory.Return {
-        return [
-            {
-                typeDefs: /* GraphQL */ `
-                    type Query {
-                        hello: String
-                    }
-                `,
-                resolvers: {
-                    Query: {
-                        hello: () => "Hello, World!"
-                    }
-                }
-            }
-        ];
-    }
+class MySchema implements GraphQLSchemaFactory.Interface {
+  async execute(
+    builder: GraphQLSchemaFactory.SchemaBuilder
+  ): Promise<GraphQLSchemaFactory.SchemaBuilder> {
+    builder.addTypeDefs(/* GraphQL */ `
+      extend type Query {
+        hello: String!
+      }
+    `);
+
+    builder.addResolver({
+      path: "Query.hello",
+      resolver: () => {
+        return () => "Hello, World!";
+      }
+    });
+
+    return builder;
+  }
 }
 
 export default GraphQLSchemaFactory.createImplementation({
-    implementation: SchemaImpl,
-    dependencies: []
+  implementation: MySchema,
+  dependencies: []
 });
 ```
 
-Register in `webiny.config.tsx`:
+Register as an extension:
 
 ```tsx
-<Api.Extension src={"/extensions/MyGraphQLSchema.ts"} />
+// extensions/mySchema/Extension.tsx
+import React from "react";
+import { Api } from "webiny/extensions";
+
+export const MySchema = () => {
+  return <Api.Extension src={"@/extensions/mySchema/MyGraphQLSchema.ts"} />;
+};
 ```
 
-## Using Dependency Injection
+## Builder API Reference
 
-Inject backend services to access user identity, tenant info, or CMS data:
+| Method                                  | Description                                                                                   |
+| --------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `builder.addTypeDefs(typeDefs: string)` | Add GraphQL type definitions (use `extend type Query/Mutation` to add to existing root types) |
+| `builder.addResolver<TArgs>(config)`    | Add a resolver with optional per-resolver DI dependencies                                     |
+
+### `addResolver` Config
+
+```typescript
+builder.addResolver<TArgs>({
+    path: "TypeName.fieldName",         // dot-separated path
+    dependencies: [SomeAbstraction],    // optional: DI tokens resolved at request time
+    resolver: (dep1, dep2, ...) => {    // factory: receives resolved deps
+        return ({ parent, args, context, info }) => {
+            // actual resolver logic
+            return result;
+        };
+    }
+});
+```
+
+Key points:
+
+- **`path`**: Dot-separated GraphQL type path, e.g. `"Query.hello"`, `"Mutation.createOrder"`, `"OrderMutation.create"`
+- **`dependencies`**: Array of DI abstraction tokens. Resolved **per-request** from `context.container`, not at schema build time
+- **`resolver`**: A factory function that receives resolved dependencies and returns the actual resolver function
+- **Resolver params**: The inner function receives `{ parent, args, context, info }` (named object, not positional)
+
+## Per-Resolver Dependency Injection
+
+Dependencies in `addResolver` are resolved at request time from the request-scoped container. This is different from class-level constructor DI -- it gives each resolver access to request-scoped services like identity and tenant context.
 
 ```typescript
-// extensions/MyGraphQLSchema.ts
 import { GraphQLSchemaFactory } from "webiny/api/graphql";
 import { IdentityContext } from "webiny/api/security";
 
-class SchemaImpl implements GraphQLSchemaFactory.Interface {
-    constructor(private identityContext: IdentityContext.Interface) {}
-
-    execute(): GraphQLSchemaFactory.Return {
-        return [
-            {
-                typeDefs: /* GraphQL */ `
-                    type Query {
-                        whoAmI: String
-                    }
-                `,
-                resolvers: {
-                    Query: {
-                        whoAmI: () => {
-                            const identity = this.identityContext.getIdentity();
-                            return `Hello, ${identity.displayName}!`;
-                        }
-                    }
-                }
-            }
-        ];
-    }
+class WhoAmISchema implements GraphQLSchemaFactory.Interface {
+  async execute(
+    builder: GraphQLSchemaFactory.SchemaBuilder
+  ): Promise<GraphQLSchemaFactory.SchemaBuilder> {
+    builder.addTypeDefs(/* GraphQL */ `
+      extend type Query {
+        whoAmI: String
+      }
+    `);
+
+    builder.addResolver({
+      path: "Query.whoAmI",
+      dependencies: [IdentityContext],
+      resolver: (identityContext: IdentityContext.Interface) => {
+        return () => {
+          const identity = identityContext.getIdentity();
+          return `Hello, ${identity.displayName}!`;
+        };
+      }
+    });
+
+    return builder;
+  }
 }
 
 export default GraphQLSchemaFactory.createImplementation({
-    implementation: SchemaImpl,
-    dependencies: [IdentityContext]
+  implementation: WhoAmISchema,
+  dependencies: []
 });
 ```
 
-## Injecting CMS Use-Cases
+## Nested Mutation Pattern
 
-You can inject Headless CMS features to read/write content entries from within your custom resolvers:
+For namespaced mutations (e.g. `mutation { tenantManager { installTenant } }`), add a pass-through resolver for the namespace type:
 
 ```typescript
 import { GraphQLSchemaFactory } from "webiny/api/graphql";
-import { ListLatestEntriesUseCase } from "@webiny/api-headless-cms/features/contentEntry/ListEntries";
-import { GetModelUseCase } from "@webiny/api-headless-cms/features/contentModel/GetModel";
-
-class SchemaImpl implements GraphQLSchemaFactory.Interface {
-    constructor(
-        private listEntries: ListLatestEntriesUseCase.Interface,
-        private getModel: GetModelUseCase.Interface
-    ) {}
-
-    execute(): GraphQLSchemaFactory.Return {
-        return [
-            {
-                typeDefs: /* GraphQL */ `
-                    type ProductSummary {
-                        totalCount: Int
-                    }
-                    type Query {
-                        productSummary: ProductSummary
-                    }
-                `,
-                resolvers: {
-                    Query: {
-                        productSummary: async () => {
-                            const model = await this.getModel.execute("product");
-                            const result = await this.listEntries.execute(model, {
-                                limit: 1000
-                            });
-                            return { totalCount: result.items.length };
-                        }
-                    }
-                }
-            }
-        ];
-    }
+import { IdentityContext } from "webiny/api/security";
+import { MyService } from "@/extensions/myFeature/MyFeature.js";
+
+class OrderSchema implements GraphQLSchemaFactory.Interface {
+  async execute(
+    builder: GraphQLSchemaFactory.SchemaBuilder
+  ): Promise<GraphQLSchemaFactory.SchemaBuilder> {
+    builder.addTypeDefs(/* GraphQL */ `
+      type Order {
+        id: ID!
+        total: Float!
+      }
+
+      type OrderMutation {
+        create(total: Float!): Order
+      }
+
+      extend type Mutation {
+        orders: OrderMutation
+      }
+    `);
+
+    // Pass-through resolver for the namespace
+    builder.addResolver({
+      path: "Mutation.orders",
+      resolver: () => {
+        return () => ({});
+      }
+    });
+
+    // Actual mutation with DI
+    builder.addResolver<{ total: number }>({
+      path: "OrderMutation.create",
+      dependencies: [IdentityContext, MyService],
+      resolver: (identityContext: IdentityContext.Interface, myService: MyService.Interface) => {
+        return async ({ args }) => {
+          if (!identityContext.getPermission("orders.create")) {
+            throw new Error("Not authorized");
+          }
+          return { id: "order-1", total: args.total };
+        };
+      }
+    });
+
+    return builder;
+  }
 }
 
 export default GraphQLSchemaFactory.createImplementation({
-    implementation: SchemaImpl,
-    dependencies: [ListLatestEntriesUseCase, GetModelUseCase]
+  implementation: OrderSchema,
+  dependencies: []
 });
 ```
 
-## Available Injectable Services
-
-### Core Features
-
-| Feature | Import Path                                  | Purpose |
-|---|----------------------------------------------|---|
-| `IdentityContext` | `"webiny/api/security"`                      | Access current user identity and permissions |
-| `TenantContext` | `"@webiny/api-core/features/TenantContext"`  | Access current tenant information |
-| `EventPublisher` | `"@webiny/api-core/features/EventPublisher"` | Publish domain events |
-| `WcpContext` | `"@webiny/api-core/features/WcpContext"`     | Webiny Control Panel integration |
-| `Logger` | `"webiny/api/logger"`                        | Logging (persists to CloudWatch) |
-| `BuildParams` | `"webiny/api/build-params"`                  | Access build-time parameters |
-
-### Headless CMS Use-Cases
-
-| Feature | Import Path | Purpose |
-|---|---|---|
-| `GetEntryByIdUseCase` | `"@webiny/api-headless-cms/features/contentEntry/GetEntryById"` | Fetch entry by exact revision ID |
-| `GetEntryUseCase` | `"@webiny/api-headless-cms/features/contentEntry/GetEntry"` | Get entry by query (where + sort) |
-| `ListLatestEntriesUseCase` | `"@webiny/api-headless-cms/features/contentEntry/ListEntries"` | List latest entries |
-| `ListPublishedEntriesUseCase` | `"@webiny/api-headless-cms/features/contentEntry/ListEntries"` | List published entries |
-| `CreateEntryUseCase` | `"@webiny/api-headless-cms/features/contentEntry/CreateEntry"` | Create a new entry |
-| `UpdateEntryUseCase` | `"@webiny/api-headless-cms/features/contentEntry/UpdateEntry"` | Update an existing entry |
-| `DeleteEntryUseCase` | `"@webiny/api-headless-cms/features/contentEntry/DeleteEntry"` | Delete an entry |
-| `GetModelUseCase` | `"@webiny/api-headless-cms/features/contentModel/GetModel"` | Retrieve a content model by ID |
-| `ListModelsUseCase` | `"@webiny/api-headless-cms/features/contentModel/ListModels"` | List all accessible models |
-
-### Settings
-
-| Feature | Import Path | Purpose |
-|---|---|---|
-| `GetSettings` | `"@webiny/api-core/features/settings/GetSettings"` | Retrieve settings by name |
-| `UpdateSettings` | `"@webiny/api-core/features/settings/UpdateSettings"` | Create or update settings |
-
-### Tenancy
-
-| Feature | Import Path | Purpose |
-|---|---|---|
-| `GetTenantByIdUseCase` | `"@webiny/api-core/features/tenancy/GetTenantById"` | Fetch a tenant by ID |
-| `CreateTenantUseCase` | `"@webiny/api-core/features/tenancy/CreateTenant"` | Create a new tenant |
-| `UpdateTenantUseCase` | `"@webiny/api-core/features/tenancy/UpdateTenant"` | Update a tenant |
-| `DeleteTenantUseCase` | `"@webiny/api-core/features/tenancy/DeleteTenant"` | Delete a tenant |
-
 ## Quick Reference
 
 ```
 Import:       import { GraphQLSchemaFactory } from "webiny/api/graphql";
 Interface:    GraphQLSchemaFactory.Interface
-Return type:  GraphQLSchemaFactory.Return
-Export:        GraphQLSchemaFactory.createImplementation({ implementation, dependencies })
-Register:     <Api.Extension src={"/extensions/MyGraphQLSchema.ts"} />
-Deploy:       yarn webiny deploy api
+Builder:      GraphQLSchemaFactory.SchemaBuilder (param type for execute)
+Return:       Promise<GraphQLSchemaFactory.SchemaBuilder>
+Export:       GraphQLSchemaFactory.createImplementation({ implementation, dependencies })
+Register:     <Api.Extension src={"@/extensions/mySchema/MyGraphQLSchema.ts"} />
+Deploy:       yarn webiny deploy api --env=dev
 ```
 
 ## Related Skills
 
+- `api-custom-feature` -- Define custom abstractions and services consumed by resolvers
 - `dependency-injection` -- Full DI reference for all injectable services
 - `project-structure` -- How to register extensions in `webiny.config.tsx`