@mastra/auth-okta 0.0.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @mastra/auth-okta
+
+## 0.0.1
+
+### Patch Changes
+
+- Initial release with Okta RBAC and Auth integration

package/README.md

@@ -0,0 +1,204 @@
+# @mastra/auth-okta
+
+Okta integration for Mastra, providing RBAC based on Okta groups and optional JWT authentication.
+
+## Features
+
+- 🔐 **RBAC Provider** - Map Okta groups to Mastra permissions
+- 🔑 **Auth Provider** - JWT token verification using Okta's JWKS
+- 🔄 **Cross-provider support** - Use with Auth0, Clerk, or any other auth provider
+- ⚡ **Caching** - LRU cache for group lookups to minimize API calls
+- 🛡️ **Type-safe** - Full TypeScript support with strict types
+
+## Installation
+
+```bash
+npm install @mastra/auth-okta
+# or
+yarn add @mastra/auth-okta
+# or
+pnpm add @mastra/auth-okta
+```
+
+## Usage
+
+### Auth0 + Okta RBAC (Recommended)
+
+Use Auth0 for authentication and Okta for role-based access control:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+import { MastraAuthAuth0 } from '@mastra/auth-auth0';
+import { MastraRBACOkta } from '@mastra/auth-okta';
+
+const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthAuth0(),
+    rbac: new MastraRBACOkta({
+      // Extract Okta user ID from Auth0 user metadata
+      getUserId: user => user.metadata?.oktaUserId || user.email,
+      roleMapping: {
+        Engineering: ['agents:*', 'workflows:*'],
+        Product: ['agents:read', 'workflows:read'],
+        Admin: ['*'],
+        _default: [], // Users with unmapped groups get no permissions
+      },
+    }),
+  },
+});
+```
+
+### Full Okta Setup
+
+For complete Okta authentication + RBAC:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+import { MastraAuthOkta, MastraRBACOkta } from '@mastra/auth-okta';
+
+const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthOkta(),
+    rbac: new MastraRBACOkta({
+      roleMapping: {
+        Admin: ['*'],
+        Member: ['agents:read', 'workflows:*'],
+        _default: [],
+      },
+    }),
+  },
+});
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable               | Description                               | Required                                           |
+| ---------------------- | ----------------------------------------- | -------------------------------------------------- |
+| `OKTA_DOMAIN`          | Okta domain (e.g., `dev-123456.okta.com`) | Yes                                                |
+| `OKTA_CLIENT_ID`       | OAuth client ID                           | For auth only                                      |
+| `OKTA_CLIENT_SECRET`   | OAuth client secret                       | For auth only                                      |
+| `OKTA_REDIRECT_URI`    | OAuth redirect URI for SSO callback       | For auth only                                      |
+| `OKTA_ISSUER`          | Token issuer URL                          | No (defaults to `https://{domain}/oauth2/default`) |
+| `OKTA_COOKIE_PASSWORD` | Session encryption key (min 32 chars)     | No (auto-generated if omitted; set for production) |
+| `OKTA_API_TOKEN`       | API token for management SDK              | For RBAC only                                      |
+
+### MastraAuthOkta Options
+
+```typescript
+interface MastraAuthOktaOptions {
+  domain?: string; // Okta domain (or OKTA_DOMAIN env var)
+  clientId?: string; // OAuth client ID (or OKTA_CLIENT_ID)
+  clientSecret?: string; // OAuth client secret (or OKTA_CLIENT_SECRET)
+  redirectUri?: string; // SSO callback URI (or OKTA_REDIRECT_URI)
+  issuer?: string; // Token issuer URL (or OKTA_ISSUER)
+  scopes?: string[]; // OAuth scopes (default: ['openid', 'profile', 'email', 'groups'])
+  name?: string; // Provider name (default: 'okta')
+  session?: {
+    cookieName?: string; // Cookie name (default: 'okta_session')
+    cookieMaxAge?: number; // Cookie max age in seconds (default: 86400)
+    cookiePassword?: string; // Encryption key, min 32 chars (or OKTA_COOKIE_PASSWORD)
+    secureCookies?: boolean; // Set Secure flag (default: auto-detect from NODE_ENV)
+  };
+}
+```
+
+### MastraRBACOkta Options
+
+```typescript
+interface MastraRBACOktaOptions {
+  domain?: string; // Okta domain
+  apiToken?: string; // API token for group fetching
+
+  // Map Okta groups to Mastra permissions
+  roleMapping: {
+    [groupName: string]: string[]; // e.g., 'Admin': ['*']
+  };
+
+  // Extract Okta user ID from any user object (for cross-provider use)
+  getUserId?: (user: unknown) => string | undefined;
+
+  // Cache configuration
+  cache?: {
+    maxSize?: number; // Max users to cache (default: 1000)
+    ttlMs?: number; // Cache TTL in ms (default: 60000)
+  };
+}
+```
+
+## Role Mapping
+
+The `roleMapping` configuration maps Okta group names to Mastra permission patterns:
+
+```typescript
+roleMapping: {
+  // Users in 'Engineering' group get full access to agents and workflows
+  'Engineering': ['agents:*', 'workflows:*'],
+
+  // Users in 'Product' group get read-only access
+  'Product': ['agents:read', 'workflows:read'],
+
+  // Users in 'Admin' group get full access to everything
+  'Admin': ['*'],
+
+  // Special '_default' key: permissions for users with unmapped groups
+  '_default': [],
+}
+```
+
+### Permission Patterns
+
+- `*` - Full access to all resources
+- `agents:*` - Full access to agents
+- `agents:read` - Read-only access to agents
+- `workflows:create` - Create workflows only
+
+## Cross-Provider Support
+
+When using a different auth provider (Auth0, Clerk, etc.) with Okta RBAC, you need to link users between systems. The `getUserId` option allows you to extract the Okta user ID from any user object:
+
+```typescript
+new MastraRBACOkta({
+  // Extract Okta user ID from Auth0 user's app_metadata
+  getUserId: (user) => {
+    return user.metadata?.oktaUserId || user.email;
+  },
+  roleMapping: { ... },
+})
+```
+
+### Linking Users
+
+To link Auth0 users to Okta:
+
+1. Store the Okta user ID in Auth0's `app_metadata`
+2. Configure `getUserId` to extract it
+3. Mastra will use this ID to fetch groups from Okta
+
+## API
+
+### MastraRBACOkta
+
+| Method                                 | Description                          |
+| -------------------------------------- | ------------------------------------ |
+| `getRoles(user)`                       | Get user's Okta groups               |
+| `hasRole(user, role)`                  | Check if user has a specific group   |
+| `getPermissions(user)`                 | Get resolved permissions from groups |
+| `hasPermission(user, permission)`      | Check if user has a permission       |
+| `hasAllPermissions(user, permissions)` | Check if user has all permissions    |
+| `hasAnyPermission(user, permissions)`  | Check if user has any permission     |
+
+### MastraAuthOkta
+
+| Method                              | Description                 |
+| ----------------------------------- | --------------------------- |
+| `authenticateToken(token, request)` | Verify JWT and return user  |
+| `authorizeUser(user, request)`      | Check if user is authorized |
+
+## Requirements
+
+- Node.js 22.13.0 or later
+- Okta account with:
+  - OAuth application (for authentication)
+  - API token (for RBAC group fetching)

package/dist/auth-provider.d.ts

@@ -0,0 +1,120 @@
+/**
+ * MastraAuthOkta - Okta authentication provider for Mastra with SSO support.
+ *
+ * Supports OAuth 2.0 / OIDC login flow with client_secret and session management.
+ */
+import type { ISSOProvider, ISessionProvider, IUserProvider, Session, SSOCallbackResult, SSOLoginConfig } from '@mastra/core/auth';
+import { MastraAuthProvider } from '@mastra/core/server';
+import type { HonoRequest } from 'hono';
+import type { OktaUser, MastraAuthOktaOptions } from './types.js';
+/**
+ * Mastra authentication provider for Okta with SSO support.
+ *
+ * Implements OAuth 2.0 / OIDC login flow with encrypted session cookies.
+ *
+ * @example Basic usage with SSO
+ * ```typescript
+ * import { MastraAuthOkta } from '@mastra/auth-okta';
+ *
+ * const auth = new MastraAuthOkta({
+ *   domain: 'dev-123456.okta.com',
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   redirectUri: 'http://localhost:4111/api/auth/callback',
+ * });
+ * ```
+ */
+export declare class MastraAuthOkta extends MastraAuthProvider<OktaUser> implements ISSOProvider<OktaUser>, ISessionProvider<Session>, IUserProvider<OktaUser> {
+    protected domain: string;
+    protected clientId: string;
+    protected clientSecret: string;
+    protected issuer: string;
+    protected redirectUri: string;
+    protected scopes: string[];
+    protected cookieName: string;
+    protected cookieMaxAge: number;
+    protected cookiePassword: string;
+    protected secureCookies: boolean;
+    protected apiToken?: string;
+    private jwks;
+    constructor(options?: MastraAuthOktaOptions);
+    /**
+     * Authenticate a token from the request.
+     * First tries to read from session cookie, then falls back to Authorization header.
+     */
+    authenticateToken(token: string, request: HonoRequest | Request): Promise<OktaUser | null>;
+    /**
+     * Authorize a user.
+     */
+    authorizeUser(user: OktaUser, _request: HonoRequest): boolean;
+    /**
+     * Get the current user from the request session.
+     */
+    getCurrentUser(request: Request): Promise<OktaUser | null>;
+    /**
+     * Get a user by ID via the Okta Users API.
+     * Requires an API token (set OKTA_API_TOKEN or pass apiToken in options).
+     * Returns null if no API token is configured or user is not found.
+     */
+    getUser(userId: string): Promise<OktaUser | null>;
+    /**
+     * Get user from session cookie.
+     */
+    private getUserFromSession;
+    /**
+     * Extract the raw ID token from the encrypted session cookie.
+     * Used to provide id_token_hint for Okta logout.
+     */
+    private getIdTokenFromSession;
+    /**
+     * Get the URL to redirect users to for Okta login.
+     * Uses client_secret authentication (no PKCE) since this is a confidential client.
+     */
+    getLoginUrl(redirectUri: string, state: string): string;
+    /**
+     * Handle the OAuth callback from Okta.
+     * Note: The server passes only the stateId (UUID part), not the full state.
+     */
+    handleCallback(code: string, stateId: string): Promise<SSOCallbackResult<OktaUser>>;
+    /**
+     * Get the URL to redirect users to for logout.
+     * Includes id_token_hint from session when available (required by Okta).
+     */
+    getLogoutUrl(redirectUri: string, request?: Request): Promise<string | null>;
+    /**
+     * Get cookies to set during login.
+     */
+    getLoginCookies(_state: string): string[];
+    /**
+     * Get the configuration for rendering the login button.
+     */
+    getLoginButtonConfig(): SSOLoginConfig;
+    createSession(userId: string, metadata?: Record<string, unknown>): Promise<Session>;
+    validateSession(_sessionId: string): Promise<Session | null>;
+    destroySession(_sessionId: string): Promise<void>;
+    refreshSession(_sessionId: string): Promise<Session | null>;
+    getSessionIdFromRequest(_request: Request): string | null;
+    getSessionHeaders(_session: Session): Record<string, string>;
+    getClearSessionHeaders(): Record<string, string>;
+    /**
+     * Build consistent cookie attribute string for set/clear operations.
+     */
+    private cookieFlags;
+    /**
+     * Get the Okta domain.
+     */
+    getDomain(): string;
+    /**
+     * Get the configured client ID.
+     */
+    getClientId(): string;
+    /**
+     * Get the configured redirect URI.
+     */
+    getRedirectUri(): string;
+    /**
+     * Get the issuer URL.
+     */
+    getIssuer(): string;
+}
+//# sourceMappingURL=auth-provider.d.ts.map

package/dist/auth-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-provider.d.ts","sourceRoot":"","sources":["../src/auth-provider.ts"],"names":[],"mappings":"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"}