@kustodian/plugin-authentik 1.0.0

package/README.md

@@ -0,0 +1,290 @@
+# @kustodian/plugin-authentik
+
+Authentik authentication provider plugin for Kustodian. This plugin enables integration with Authentik for authentication and authorization in your Kubernetes applications.
+
+## Features
+
+- 🔐 **OAuth2/OIDC Provider** - Configure OAuth2 and OIDC clients for modern applications
+- 🛡️ **SAML Provider** - Support for legacy applications using SAML authentication
+- 🔀 **Proxy/Forward Auth** - Protect applications with forward authentication
+- 📝 **Blueprint Generation** - Generate Authentik blueprints for GitOps workflows
+- 🔑 **Secret Management** - Automatically generate secure client secrets
+- ✅ **Validation** - Validate Authentik blueprint configurations
+
+## Installation
+
+```bash
+pnpm add @kustodian/plugin-authentik
+```
+
+## Prerequisites
+
+Optional: For enhanced functionality, install the Authentik CLI:
+
+```bash
+# Installation instructions available at:
+# https://goauthentik.io/docs/installation/
+```
+
+## Usage
+
+### Basic Plugin Setup
+
+```typescript
+import { create_authentik_plugin } from '@kustodian/plugin-authentik';
+
+const authentik_plugin = create_authentik_plugin({
+  domain: 'auth.example.com',
+  default_authorization_flow: 'implicit-consent',
+  outpost_name: 'default-outpost',
+  auto_generate_secrets: true,
+  output_dir: './authentik-blueprints',
+});
+```
+
+### CLI Commands
+
+The plugin provides several CLI commands:
+
+```bash
+# Check Authentik CLI availability
+kustodian authentik check
+
+# Generate a random secret for OAuth2 clients
+kustodian authentik generate-secret [length]
+
+# Generate Authentik blueprint
+kustodian authentik generate-blueprint <app-name> <provider-type> <config-json>
+
+# Validate blueprint file
+kustodian authentik validate-blueprint <blueprint-path>
+```
+
+### Programmatic Usage
+
+#### Generate OAuth2 Provider
+
+```typescript
+import { generate_oauth2_provider } from '@kustodian/plugin-authentik';
+
+const auth_config = {
+  provider: 'oauth2' as const,
+  app_name: 'grafana',
+  app_display_name: 'Grafana',
+  app_launch_url: 'https://grafana.example.com',
+  oauth2: {
+    client_id: 'grafana',
+    client_type: 'confidential' as const,
+    redirect_uris: ['https://grafana.example.com/login/generic_oauth'],
+  },
+};
+
+const options = {
+  domain: 'auth.example.com',
+  default_authorization_flow: 'implicit-consent' as const,
+  outpost_name: 'default-outpost',
+  auto_generate_secrets: true,
+  output_dir: './authentik-blueprints',
+  blueprint_version: 1,
+};
+
+const result = generate_oauth2_provider(auth_config, options);
+
+if (result.success) {
+  console.log('Generated OAuth2 provider:', result.value);
+}
+```
+
+#### Generate SAML Provider
+
+```typescript
+import { generate_saml_provider } from '@kustodian/plugin-authentik';
+
+const auth_config = {
+  provider: 'saml' as const,
+  app_name: 'legacy-app',
+  saml: {
+    acs_url: 'https://app.example.com/saml/acs',
+    issuer: 'https://app.example.com',
+    sp_binding: 'post' as const,
+  },
+};
+
+const result = generate_saml_provider(auth_config, options);
+```
+
+#### Generate Proxy Provider
+
+```typescript
+import { generate_proxy_provider } from '@kustodian/plugin-authentik';
+
+const auth_config = {
+  provider: 'proxy' as const,
+  app_name: 'qbittorrent',
+  proxy: {
+    external_host: 'https://qbittorrent.example.com',
+    internal_host: 'http://qbittorrent.media.svc:8080',
+    mode: 'forward_single' as const,
+  },
+};
+
+const result = generate_proxy_provider(auth_config, options);
+```
+
+#### Generate Complete Blueprint
+
+```typescript
+import { generate_authentik_blueprint, blueprint_to_yaml } from '@kustodian/plugin-authentik';
+
+const auth_config = {
+  provider: 'oauth2' as const,
+  app_name: 'grafana',
+  app_display_name: 'Grafana',
+  app_description: 'Monitoring and observability platform',
+  app_icon: 'https://grafana.com/static/img/menu/grafana2.svg',
+  app_group: 'Monitoring',
+  app_launch_url: 'https://grafana.example.com',
+  oauth2: {
+    client_id: 'grafana',
+    redirect_uris: ['https://grafana.example.com/login/generic_oauth'],
+  },
+};
+
+const blueprint_result = generate_authentik_blueprint(auth_config, options);
+
+if (blueprint_result.success) {
+  // Export as YAML
+  const yaml_content = blueprint_to_yaml(blueprint_result.value);
+  console.log(yaml_content);
+}
+```
+
+## Provider Types
+
+### OAuth2/OIDC
+
+Suitable for modern applications that support OpenID Connect:
+
+```typescript
+{
+  provider: 'oauth2',
+  oauth2: {
+    client_id: 'my-app',
+    client_type: 'confidential', // or 'public'
+    redirect_uris: ['https://app.example.com/callback'],
+    // Optional configuration
+    authorization_flow: 'implicit-consent',
+    signing_key: 'certificate-slug',
+    include_claims_in_id_token: true,
+    access_token_validity: 'minutes=10',
+    refresh_token_validity: 'days=30',
+  }
+}
+```
+
+### SAML
+
+For legacy enterprise applications:
+
+```typescript
+{
+  provider: 'saml',
+  saml: {
+    acs_url: 'https://app.example.com/saml/acs',
+    issuer: 'https://app.example.com',
+    sp_binding: 'post', // or 'redirect'
+    // Optional configuration
+    name_id_policy: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
+    signing_kp: 'certificate-slug',
+  }
+}
+```
+
+### Proxy (Forward Auth)
+
+For applications that don't natively support SSO:
+
+```typescript
+{
+  provider: 'proxy',
+  proxy: {
+    external_host: 'https://app.example.com',
+    internal_host: 'http://app.svc:8080',
+    mode: 'forward_single', // 'proxy', 'forward_domain'
+    // Optional configuration
+    skip_path_regex: '/api/health|/public/.*',
+    intercept_header_auth: true,
+  }
+}
+```
+
+## Blueprint Structure
+
+Generated blueprints follow the Authentik Blueprint format:
+
+```yaml
+version: 1
+metadata:
+  name: app-name-blueprint
+  labels:
+    app.kubernetes.io/name: app-name
+    app.kubernetes.io/managed-by: kustodian
+entries:
+  - model: authentik_providers_oauth2.oauth2provider
+    identifiers:
+      name: app-name-oauth2
+    attrs:
+      # Provider configuration
+  - model: authentik_core.application
+    identifiers:
+      slug: app-name
+    attrs:
+      # Application configuration
+```
+
+## Template Integration
+
+Use in Kustodian templates:
+
+```yaml
+apiVersion: kustodian.io/v1
+kind: Template
+metadata:
+  name: monitoring
+spec:
+  kustomizations:
+    - name: grafana
+      path: grafana
+      auth:
+        provider: oauth2
+        app_name: grafana
+        app_display_name: Grafana
+        app_icon: https://grafana.com/static/img/menu/grafana2.svg
+        app_group: Monitoring
+        app_launch_url: https://grafana.${cluster_domain}
+        oauth2:
+          client_id: grafana
+          redirect_uris:
+            - https://grafana.${cluster_domain}/login/generic_oauth
+```
+
+## API Reference
+
+See [TypeScript definitions](./src/types.ts) for complete type information.
+
+### Main Functions
+
+- `create_authentik_plugin(options)` - Create plugin instance
+- `generate_oauth2_provider(config, options)` - Generate OAuth2 provider
+- `generate_saml_provider(config, options)` - Generate SAML provider
+- `generate_proxy_provider(config, options)` - Generate Proxy provider
+- `generate_authentik_blueprint(config, options)` - Generate complete blueprint
+- `blueprint_to_yaml(blueprint)` - Convert blueprint to YAML
+- `yaml_to_blueprint(yaml)` - Parse YAML to blueprint
+- `check_authentik_available()` - Check CLI availability
+- `validate_blueprint(path)` - Validate blueprint file
+- `generate_random_secret(length)` - Generate secure random secret
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@kustodian/plugin-authentik",
+  "version": "1.0.0",
+  "description": "Authentik authentication provider plugin for Kustodian",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": ["src"],
+  "scripts": {
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "typecheck": "bun run tsc --noEmit"
+  },
+  "keywords": [
+    "kustodian",
+    "plugin",
+    "authentik",
+    "authentication",
+    "oauth2",
+    "saml",
+    "proxy",
+    "kubernetes"
+  ],
+  "author": "Luca Silverentand <luca@onezero.company>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lucasilverentand/kustodian.git",
+    "directory": "plugins/authentik"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
+  "dependencies": {
+    "@kustodian/core": "^1.1.0",
+    "@kustodian/plugins": "^1.0.1",
+    "@kustodian/schema": "^1.2.0",
+    "js-yaml": "^4.1.1",
+    "zod": "^4.3.5"
+  },
+  "packageManager": "pnpm@10.19.0",
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9"
+  }
+}

package/src/executor.ts

@@ -0,0 +1,119 @@
+import { exec } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { promisify } from 'node:util';
+
+import { type ResultType, create_error, success } from '@kustodian/core';
+import type { KustodianErrorType } from '@kustodian/core';
+
+import { yaml_to_blueprint } from './generator.js';
+
+const exec_async = promisify(exec);
+
+/**
+ * Check if Authentik CLI is available.
+ */
+export async function check_authentik_available(): Promise<ResultType<string, KustodianErrorType>> {
+  try {
+    const { stdout } = await exec_async('ak --version', { timeout: 5000 });
+    const version = stdout.trim();
+    return success(version);
+  } catch (error) {
+    return {
+      success: false,
+      error: create_error(
+        'AUTHENTIK_CLI_NOT_FOUND',
+        'Authentik CLI not found. Install from: https://goauthentik.io/docs/installation/',
+        error,
+      ),
+    };
+  }
+}
+
+/**
+ * Validate Authentik blueprint file.
+ */
+export async function validate_blueprint(
+  blueprint_path: string,
+): Promise<ResultType<void, KustodianErrorType>> {
+  try {
+    // Read the blueprint file
+    const blueprint_content = readFileSync(blueprint_path, 'utf-8');
+
+    // Parse YAML to validate structure
+    const parse_result = yaml_to_blueprint(blueprint_content);
+    if (!parse_result.success) {
+      return parse_result;
+    }
+
+    const blueprint = parse_result.value;
+
+    // Basic validation
+    if (!blueprint.version || !blueprint.metadata || !blueprint.entries) {
+      return {
+        success: false,
+        error: create_error(
+          'INVALID_BLUEPRINT',
+          'Blueprint must have version, metadata, and entries',
+        ),
+      };
+    }
+
+    if (blueprint.entries.length === 0) {
+      return {
+        success: false,
+        error: create_error('INVALID_BLUEPRINT', 'Blueprint must have at least one entry'),
+      };
+    }
+
+    // Validate each entry has required fields
+    for (const entry of blueprint.entries) {
+      if (!entry.model || !entry.identifiers) {
+        return {
+          success: false,
+          error: create_error(
+            'INVALID_BLUEPRINT',
+            'Each blueprint entry must have model and identifiers',
+          ),
+        };
+      }
+    }
+
+    return success(undefined);
+  } catch (error) {
+    return {
+      success: false,
+      error: create_error(
+        'VALIDATION_ERROR',
+        `Failed to validate blueprint: ${error instanceof Error ? error.message : String(error)}`,
+        error,
+      ),
+    };
+  }
+}
+
+/**
+ * Generate random secret (for OAuth2 clients).
+ */
+export async function generate_random_secret(
+  length = 64,
+): Promise<ResultType<string, KustodianErrorType>> {
+  try {
+    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+    let result = '';
+    const randomArray = new Uint8Array(length);
+    crypto.getRandomValues(randomArray);
+    for (const value of randomArray) {
+      result += chars[value % chars.length];
+    }
+    return success(result);
+  } catch (error) {
+    return {
+      success: false,
+      error: create_error(
+        'GENERATION_ERROR',
+        `Failed to generate secret: ${error instanceof Error ? error.message : String(error)}`,
+        error,
+      ),
+    };
+  }
+}

package/src/generator.ts

@@ -0,0 +1,319 @@
+import { type ResultType, failure, success } from '@kustodian/core';
+import type { KustodianErrorType } from '@kustodian/core';
+import * as yaml from 'js-yaml';
+
+import type {
+  AuthConfigType,
+  AuthentikApplicationType,
+  AuthentikBlueprintType,
+  AuthentikOAuth2ProviderType,
+  AuthentikPluginOptionsType,
+  AuthentikProxyProviderType,
+  AuthentikSAMLProviderType,
+} from './types.js';
+
+/**
+ * Generate a random secret for OAuth2 clients.
+ */
+export function generate_client_secret(length = 64): string {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+  let result = '';
+  const randomArray = new Uint8Array(length);
+  crypto.getRandomValues(randomArray);
+  for (const value of randomArray) {
+    result += chars[value % chars.length];
+  }
+  return result;
+}
+
+/**
+ * Generate OAuth2 provider blueprint entry.
+ */
+export function generate_oauth2_provider(
+  auth_config: AuthConfigType,
+  options: AuthentikPluginOptionsType,
+): ResultType<AuthentikOAuth2ProviderType, KustodianErrorType> {
+  if (auth_config.provider !== 'oauth2') {
+    return failure({
+      code: 'INVALID_CONFIG',
+      message: 'Auth config provider must be "oauth2"',
+    });
+  }
+
+  const oauth2_config = auth_config.oauth2 ?? {};
+  const provider_name = `${auth_config.app_name}-oauth2`;
+
+  const provider: AuthentikOAuth2ProviderType = {
+    identifiers: {
+      name: provider_name,
+    },
+    model: 'authentik_providers_oauth2.oauth2provider',
+    attrs: {
+      name: provider_name,
+      client_id: oauth2_config.client_id ?? auth_config.app_name,
+      client_type: oauth2_config.client_type ?? 'confidential',
+      redirect_uris: oauth2_config.redirect_uris?.join('\n') ?? '',
+      authorization_flow: oauth2_config.authorization_flow ?? options.default_authorization_flow,
+      include_claims_in_id_token: oauth2_config.include_claims_in_id_token ?? true,
+      access_token_validity: oauth2_config.access_token_validity ?? 'minutes=10',
+      refresh_token_validity: oauth2_config.refresh_token_validity ?? 'days=30',
+      sub_mode: oauth2_config.sub_mode ?? 'hashed_user_identifier',
+      issue_refresh_tokens: oauth2_config.issue_refresh_tokens ?? true,
+    },
+  };
+
+  // Add client secret if confidential and auto-generate is enabled
+  if (
+    provider.attrs.client_type === 'confidential' &&
+    options.auto_generate_secrets &&
+    !oauth2_config.client_secret
+  ) {
+    provider.attrs.client_secret = generate_client_secret();
+  } else if (oauth2_config.client_secret) {
+    provider.attrs.client_secret = oauth2_config.client_secret;
+  }
+
+  // Add optional signing key
+  if (oauth2_config.signing_key) {
+    provider.attrs.signing_key = oauth2_config.signing_key;
+  }
+
+  return success(provider);
+}
+
+/**
+ * Generate SAML provider blueprint entry.
+ */
+export function generate_saml_provider(
+  auth_config: AuthConfigType,
+  options: AuthentikPluginOptionsType,
+): ResultType<AuthentikSAMLProviderType, KustodianErrorType> {
+  if (auth_config.provider !== 'saml') {
+    return failure({
+      code: 'INVALID_CONFIG',
+      message: 'Auth config provider must be "saml"',
+    });
+  }
+
+  const saml_config = auth_config.saml;
+  if (!saml_config?.acs_url || !saml_config?.issuer) {
+    return failure({
+      code: 'INVALID_CONFIG',
+      message: 'SAML provider requires acs_url and issuer',
+    });
+  }
+
+  const provider_name = `${auth_config.app_name}-saml`;
+
+  const provider: AuthentikSAMLProviderType = {
+    identifiers: {
+      name: provider_name,
+    },
+    model: 'authentik_providers_saml.samlprovider',
+    attrs: {
+      name: provider_name,
+      acs_url: saml_config.acs_url,
+      issuer: saml_config.issuer,
+      sp_binding: saml_config.sp_binding ?? 'post',
+      authorization_flow: saml_config.authorization_flow ?? options.default_authorization_flow,
+      assertion_valid_not_before: saml_config.assertion_valid_not_before ?? 'minutes=5',
+      assertion_valid_not_on_or_after: saml_config.assertion_valid_not_on_or_after ?? 'minutes=5',
+      session_valid_not_on_or_after: saml_config.session_valid_not_on_or_after ?? 'minutes=86400',
+    },
+  };
+
+  // Add optional fields
+  if (saml_config.audience) {
+    provider.attrs.audience = saml_config.audience;
+  }
+  if (saml_config.signing_kp) {
+    provider.attrs.signing_kp = saml_config.signing_kp;
+  }
+
+  return success(provider);
+}
+
+/**
+ * Generate Proxy provider blueprint entry.
+ */
+export function generate_proxy_provider(
+  auth_config: AuthConfigType,
+  options: AuthentikPluginOptionsType,
+): ResultType<AuthentikProxyProviderType, KustodianErrorType> {
+  if (auth_config.provider !== 'proxy') {
+    return failure({
+      code: 'INVALID_CONFIG',
+      message: 'Auth config provider must be "proxy"',
+    });
+  }
+
+  const proxy_config = auth_config.proxy;
+  if (!proxy_config?.external_host) {
+    return failure({
+      code: 'INVALID_CONFIG',
+      message: 'Proxy provider requires external_host',
+    });
+  }
+
+  const provider_name = `${auth_config.app_name}-proxy`;
+
+  const provider: AuthentikProxyProviderType = {
+    identifiers: {
+      name: provider_name,
+    },
+    model: 'authentik_providers_proxy.proxyprovider',
+    attrs: {
+      name: provider_name,
+      external_host: proxy_config.external_host,
+      internal_host_ssl_validation: proxy_config.internal_host_ssl_validation ?? true,
+      basic_auth_enabled: proxy_config.basic_auth_enabled ?? false,
+      mode: proxy_config.mode ?? 'forward_single',
+      authorization_flow: proxy_config.authorization_flow ?? options.default_authorization_flow,
+      access_token_validity: proxy_config.access_token_validity ?? 'minutes=10',
+      intercept_header_auth: proxy_config.intercept_header_auth ?? true,
+    },
+  };
+
+  // Add optional fields
+  if (proxy_config.internal_host) {
+    provider.attrs.internal_host = proxy_config.internal_host;
+  }
+  if (proxy_config.certificate) {
+    provider.attrs.certificate = proxy_config.certificate;
+  }
+  if (proxy_config.skip_path_regex) {
+    provider.attrs.skip_path_regex = proxy_config.skip_path_regex;
+  }
+  if (proxy_config.basic_auth_password_attribute) {
+    provider.attrs.basic_auth_password_attribute = proxy_config.basic_auth_password_attribute;
+  }
+  if (proxy_config.basic_auth_user_attribute) {
+    provider.attrs.basic_auth_user_attribute = proxy_config.basic_auth_user_attribute;
+  }
+
+  return success(provider);
+}
+
+/**
+ * Generate application blueprint entry.
+ */
+export function generate_application(
+  auth_config: AuthConfigType,
+  provider_name: string,
+): AuthentikApplicationType {
+  const attrs: AuthentikApplicationType['attrs'] = {
+    name: auth_config.app_display_name ?? auth_config.app_name,
+    slug: auth_config.app_name,
+    provider: provider_name,
+    policy_engine_mode: 'any',
+  };
+
+  // Add optional fields only if defined
+  if (auth_config.app_description) {
+    attrs.meta_description = auth_config.app_description;
+  }
+  if (auth_config.app_icon) {
+    attrs.meta_icon = auth_config.app_icon;
+  }
+  if (auth_config.app_group) {
+    attrs.group = auth_config.app_group;
+  }
+  if (auth_config.app_launch_url) {
+    attrs.meta_launch_url = auth_config.app_launch_url;
+  }
+
+  return {
+    identifiers: {
+      slug: auth_config.app_name,
+    },
+    model: 'authentik_core.application',
+    attrs,
+  };
+}
+
+/**
+ * Generate complete Authentik blueprint from auth configuration.
+ */
+export function generate_authentik_blueprint(
+  auth_config: AuthConfigType,
+  options: AuthentikPluginOptionsType,
+): ResultType<AuthentikBlueprintType, KustodianErrorType> {
+  const entries: AuthentikBlueprintType['entries'] = [];
+
+  // Generate provider based on type
+  let provider_result:
+    | ResultType<AuthentikOAuth2ProviderType, KustodianErrorType>
+    | ResultType<AuthentikSAMLProviderType, KustodianErrorType>
+    | ResultType<AuthentikProxyProviderType, KustodianErrorType>;
+
+  switch (auth_config.provider) {
+    case 'oauth2':
+      provider_result = generate_oauth2_provider(auth_config, options);
+      break;
+    case 'saml':
+      provider_result = generate_saml_provider(auth_config, options);
+      break;
+    case 'proxy':
+      provider_result = generate_proxy_provider(auth_config, options);
+      break;
+    default:
+      return failure({
+        code: 'INVALID_CONFIG',
+        message: `Unknown provider type: ${auth_config.provider}`,
+      });
+  }
+
+  if (!provider_result.success) {
+    return provider_result;
+  }
+
+  const provider = provider_result.value;
+  entries.push(provider);
+
+  // Generate application
+  const application = generate_application(auth_config, provider.identifiers.name);
+  entries.push(application);
+
+  const blueprint: AuthentikBlueprintType = {
+    version: options.blueprint_version,
+    metadata: {
+      name: `${auth_config.app_name}-blueprint`,
+      labels: {
+        'app.kubernetes.io/name': auth_config.app_name,
+        'app.kubernetes.io/managed-by': 'kustodian',
+      },
+    },
+    entries,
+  };
+
+  return success(blueprint);
+}
+
+/**
+ * Convert blueprint to YAML string.
+ */
+export function blueprint_to_yaml(blueprint: AuthentikBlueprintType): string {
+  return yaml.dump(blueprint, {
+    indent: 2,
+    lineWidth: -1,
+    noRefs: true,
+    sortKeys: false,
+  });
+}
+
+/**
+ * Parse YAML string to blueprint.
+ */
+export function yaml_to_blueprint(
+  yaml_string: string,
+): ResultType<AuthentikBlueprintType, KustodianErrorType> {
+  try {
+    const blueprint = yaml.load(yaml_string) as AuthentikBlueprintType;
+    return success(blueprint);
+  } catch (error) {
+    return failure({
+      code: 'PARSE_ERROR',
+      message: `Failed to parse YAML: ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Authentik authentication provider plugin for Kustodian
+ *
+ * This plugin enables integration with Authentik for authentication and authorization.
+ * It can generate OAuth2, SAML, and Proxy provider configurations, create Authentik
+ * blueprints, and manage authentication requirements for deployed applications.
+ *
+ * @packageDocumentation
+ */
+
+export { create_authentik_plugin, plugin as default } from './plugin.js';
+export type {
+  AuthConfigType,
+  AuthProviderType,
+  AuthentikPluginOptionsType,
+  OAuth2ProviderConfigType,
+  SAMLProviderConfigType,
+  ProxyProviderConfigType,
+  AuthentikBlueprintType,
+  AuthentikApplicationType,
+  AuthentikOAuth2ProviderType,
+  AuthentikSAMLProviderType,
+  AuthentikProxyProviderType,
+  ClientTypeType,
+  ProxyModeType,
+  SAMLBindingType,
+  SAMLNameIDPolicyType,
+  AuthentikFlowType,
+} from './types.js';
+export {
+  generate_authentik_blueprint,
+  generate_oauth2_provider,
+  generate_saml_provider,
+  generate_proxy_provider,
+  generate_application,
+  generate_client_secret,
+  blueprint_to_yaml,
+  yaml_to_blueprint,
+} from './generator.js';
+export {
+  check_authentik_available,
+  validate_blueprint,
+  generate_random_secret,
+} from './executor.js';

package/src/plugin.ts

@@ -0,0 +1,238 @@
+import { success } from '@kustodian/core';
+import type {
+  CommandType,
+  HookContextType,
+  HookEventType,
+  KustodianPluginType,
+  PluginCommandContributionType,
+  PluginHookContributionType,
+  PluginManifestType,
+} from '@kustodian/plugins';
+
+import {
+  check_authentik_available,
+  generate_random_secret,
+  validate_blueprint,
+} from './executor.js';
+import { blueprint_to_yaml, generate_authentik_blueprint } from './generator.js';
+import type { AuthConfigType } from './types.js';
+import { authentik_plugin_options_schema } from './types.js';
+
+/**
+ * Authentik plugin manifest.
+ */
+const manifest: PluginManifestType = {
+  name: '@kustodian/plugin-authentik',
+  version: '1.0.0',
+  description: 'Authentik authentication provider plugin for Kustodian',
+  capabilities: ['commands', 'hooks'],
+};
+
+/**
+ * Creates the Authentik plugin.
+ */
+export function create_authentik_plugin(
+  options: Record<string, unknown> = {},
+): KustodianPluginType {
+  // Parse options through schema to apply defaults
+  const plugin_options = authentik_plugin_options_schema.parse(options);
+
+  return {
+    manifest,
+
+    async activate() {
+      // Verify CLI availability on activation (warning only)
+      const check_result = await check_authentik_available();
+      if (!check_result.success) {
+        console.warn('Authentik CLI not found - some features may be unavailable');
+        console.warn('Install from: https://goauthentik.io/docs/installation/');
+      }
+      return success(undefined);
+    },
+
+    async deactivate() {
+      return success(undefined);
+    },
+
+    get_commands(): PluginCommandContributionType[] {
+      const authentik_command: CommandType = {
+        name: 'authentik',
+        description: 'Authentik authentication provider commands',
+        subcommands: [
+          {
+            name: 'check',
+            description: 'Check Authentik CLI availability',
+            handler: async () => {
+              const result = await check_authentik_available();
+              if (result.success) {
+                console.log(`Authentik CLI: ${result.value}`);
+                return success(undefined);
+              }
+              console.error('Authentik CLI not available');
+              return result;
+            },
+          },
+          {
+            name: 'generate-secret',
+            description: 'Generate random secret for OAuth2 client',
+            arguments: [
+              {
+                name: 'length',
+                description: 'Secret length (default: 64)',
+                required: false,
+              },
+            ],
+            handler: async (ctx: {
+              args: string[];
+              options: Record<string, unknown>;
+              data: Record<string, unknown>;
+            }) => {
+              const length = ctx.args[0] ? Number.parseInt(ctx.args[0], 10) : 64;
+
+              const result = await generate_random_secret(length);
+              if (result.success) {
+                console.log('Generated secret:');
+                console.log(result.value);
+                return success(undefined);
+              }
+
+              console.error(`Failed to generate secret: ${result.error.message}`);
+              return result;
+            },
+          },
+          {
+            name: 'generate-blueprint',
+            description: 'Generate Authentik blueprint from auth configuration',
+            arguments: [
+              {
+                name: 'app-name',
+                description: 'Application name',
+                required: true,
+              },
+              {
+                name: 'provider',
+                description: 'Provider type (oauth2, saml, proxy)',
+                required: true,
+              },
+              {
+                name: 'config-json',
+                description: 'JSON configuration for the provider',
+                required: true,
+              },
+            ],
+            handler: async (ctx: {
+              args: string[];
+              options: Record<string, unknown>;
+              data: Record<string, unknown>;
+            }) => {
+              const app_name = ctx.args[0];
+              const provider = ctx.args[1] as 'oauth2' | 'saml' | 'proxy';
+              const config_json = ctx.args[2];
+
+              if (!app_name || !provider || !config_json) {
+                console.error('App name, provider, and config JSON are required');
+                return success(undefined);
+              }
+
+              try {
+                const provider_config = JSON.parse(config_json);
+                const auth_config: AuthConfigType = {
+                  provider,
+                  app_name,
+                  [provider]: provider_config,
+                };
+
+                const result = generate_authentik_blueprint(auth_config, plugin_options);
+                if (result.success) {
+                  console.log('Generated blueprint:');
+                  console.log(blueprint_to_yaml(result.value));
+                  return success(undefined);
+                }
+
+                console.error(`Failed to generate blueprint: ${result.error.message}`);
+                return result;
+              } catch (error) {
+                console.error(
+                  `Failed to parse config JSON: ${error instanceof Error ? error.message : String(error)}`,
+                );
+                return success(undefined);
+              }
+            },
+          },
+          {
+            name: 'validate-blueprint',
+            description: 'Validate Authentik blueprint file',
+            arguments: [
+              {
+                name: 'blueprint-path',
+                description: 'Path to blueprint file',
+                required: true,
+              },
+            ],
+            handler: async (ctx: {
+              args: string[];
+              options: Record<string, unknown>;
+              data: Record<string, unknown>;
+            }) => {
+              const blueprint_path = ctx.args[0];
+
+              if (!blueprint_path) {
+                console.error('Blueprint path is required');
+                return success(undefined);
+              }
+
+              const result = await validate_blueprint(blueprint_path);
+              if (result.success) {
+                console.log('✓ Blueprint is valid');
+                return success(undefined);
+              }
+
+              console.error(`✗ Blueprint validation failed: ${result.error.message}`);
+              return result;
+            },
+          },
+        ],
+      };
+      return [{ command: authentik_command }];
+    },
+
+    get_hooks(): PluginHookContributionType[] {
+      return [
+        {
+          event: 'generator:after_resolve',
+          priority: 40, // Run before secret providers to allow auth configs to be processed
+          handler: async (_event: HookEventType, ctx: HookContextType) => {
+            // TODO: Implement auth config extraction from templates
+            // This will:
+            // 1. Extract auth configs from kustomizations
+            // 2. Generate Authentik blueprints
+            // 3. Write blueprints to output directory
+            // 4. Generate Kubernetes ConfigMaps with blueprints
+
+            // For now, just pass through
+            return success(ctx);
+          },
+        },
+        {
+          event: 'generator:before',
+          priority: 50,
+          handler: async (_event: HookEventType, ctx: HookContextType) => {
+            // TODO: This hook could be used to:
+            // 1. Inject generated Authentik blueprints as ConfigMaps
+            // 2. Generate documentation for configured applications
+            // 3. Validate auth configuration consistency
+
+            return success(ctx);
+          },
+        },
+      ];
+    },
+  };
+}
+
+/**
+ * Default plugin export.
+ */
+export const plugin = create_authentik_plugin();
+
+export default plugin;

package/src/types.ts

@@ -0,0 +1,296 @@
+import { z } from 'zod';
+
+/**
+ * Authentik authorization flow types
+ */
+export const authentik_flow_schema = z.enum([
+  'implicit-consent',
+  'explicit-consent',
+  'default-provider-authorization-implicit-consent',
+  'default-provider-authorization-explicit-consent',
+]);
+export type AuthentikFlowType = z.infer<typeof authentik_flow_schema>;
+
+/**
+ * Authentik provider types
+ */
+export const auth_provider_schema = z.enum(['oauth2', 'saml', 'proxy']);
+export type AuthProviderType = z.infer<typeof auth_provider_schema>;
+
+/**
+ * OAuth2/OIDC client types
+ */
+export const client_type_schema = z.enum(['confidential', 'public']);
+export type ClientTypeType = z.infer<typeof client_type_schema>;
+
+/**
+ * Authentik proxy mode types
+ */
+export const proxy_mode_schema = z.enum(['proxy', 'forward_single', 'forward_domain']);
+export type ProxyModeType = z.infer<typeof proxy_mode_schema>;
+
+/**
+ * SAML SP binding types
+ */
+export const saml_binding_schema = z.enum(['post', 'redirect']);
+export type SAMLBindingType = z.infer<typeof saml_binding_schema>;
+
+/**
+ * SAML NameID policy types
+ */
+export const saml_nameid_policy_schema = z.enum([
+  'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
+  'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
+  'urn:oasis:names:tc:SAML:2.0:nameid-format:transient',
+  'urn:oasis:names:tc:SAML:2.0:nameid-format:WindowsDomainQualifiedName',
+]);
+export type SAMLNameIDPolicyType = z.infer<typeof saml_nameid_policy_schema>;
+
+/**
+ * OAuth2/OIDC provider configuration for Authentik
+ */
+export const oauth2_provider_config_schema = z.object({
+  /** Unique client identifier */
+  client_id: z.string(),
+  /** Client type (confidential or public) */
+  client_type: client_type_schema.default('confidential'),
+  /** Client secret (will be generated if not provided) */
+  client_secret: z.string().optional(),
+  /** Redirect URIs for OAuth callbacks */
+  redirect_uris: z.array(z.string()),
+  /** Authorization flow slug */
+  authorization_flow: authentik_flow_schema.optional(),
+  /** Signing key (optional, for JWT signing) */
+  signing_key: z.string().optional(),
+  /** Include claims in ID token */
+  include_claims_in_id_token: z.boolean().default(true),
+  /** Additional scopes beyond openid */
+  additional_scopes: z.array(z.string()).optional(),
+  /** Access token validity in seconds */
+  access_token_validity: z.string().default('minutes=10'),
+  /** Refresh token validity in seconds */
+  refresh_token_validity: z.string().default('days=30'),
+  /** Subject mode: based_on_username, based_on_user_email, based_on_user_uuid, based_on_hashed_user_identifier */
+  sub_mode: z.string().default('hashed_user_identifier'),
+  /** Issue refresh tokens */
+  issue_refresh_tokens: z.boolean().default(true),
+});
+export type OAuth2ProviderConfigType = z.infer<typeof oauth2_provider_config_schema>;
+
+/**
+ * SAML provider configuration for Authentik
+ */
+export const saml_provider_config_schema = z.object({
+  /** ACS (Assertion Consumer Service) URL */
+  acs_url: z.string().url(),
+  /** Entity ID / Issuer */
+  issuer: z.string(),
+  /** SP (Service Provider) binding method */
+  sp_binding: saml_binding_schema.default('post'),
+  /** Audience for SAML assertions */
+  audience: z.string().optional(),
+  /** Authorization flow slug */
+  authorization_flow: authentik_flow_schema.optional(),
+  /** Signing certificate */
+  signing_kp: z.string().optional(),
+  /** NameID policy */
+  name_id_policy: saml_nameid_policy_schema.default(
+    'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
+  ),
+  /** Assertion validity (not before) in seconds */
+  assertion_valid_not_before: z.string().default('minutes=5'),
+  /** Assertion validity (not on or after) in seconds */
+  assertion_valid_not_on_or_after: z.string().default('minutes=5'),
+  /** Session validity (not on or after) in seconds */
+  session_valid_not_on_or_after: z.string().default('minutes=86400'),
+});
+export type SAMLProviderConfigType = z.infer<typeof saml_provider_config_schema>;
+
+/**
+ * Proxy provider configuration for Authentik
+ */
+export const proxy_provider_config_schema = z.object({
+  /** External host (public URL) */
+  external_host: z.string().url(),
+  /** Internal host (backend service URL) */
+  internal_host: z.string().url().optional(),
+  /** Internal host (SSL validation) */
+  internal_host_ssl_validation: z.boolean().default(true),
+  /** Certificate for internal SSL */
+  certificate: z.string().optional(),
+  /** Skip path regex (paths to skip authentication) */
+  skip_path_regex: z.string().optional(),
+  /** Basic auth enabled */
+  basic_auth_enabled: z.boolean().default(false),
+  /** Basic auth password attribute */
+  basic_auth_password_attribute: z.string().optional(),
+  /** Basic auth user attribute */
+  basic_auth_user_attribute: z.string().optional(),
+  /** Mode: proxy, forward_single, or forward_domain */
+  mode: proxy_mode_schema.default('forward_single'),
+  /** Authorization flow slug */
+  authorization_flow: authentik_flow_schema.optional(),
+  /** Access token validity in seconds */
+  access_token_validity: z.string().default('minutes=10'),
+  /** Intercept header auth */
+  intercept_header_auth: z.boolean().default(true),
+});
+export type ProxyProviderConfigType = z.infer<typeof proxy_provider_config_schema>;
+
+/**
+ * Authentication configuration in template kustomizations
+ */
+export const auth_config_schema = z.object({
+  /** Authentication provider type */
+  provider: auth_provider_schema,
+  /** Application name (used as identifier) */
+  app_name: z.string(),
+  /** Display name for the application */
+  app_display_name: z.string().optional(),
+  /** Application description */
+  app_description: z.string().optional(),
+  /** Application icon URL */
+  app_icon: z.string().optional(),
+  /** Application group/category */
+  app_group: z.string().optional(),
+  /** Application launch URL */
+  app_launch_url: z.string().optional(),
+  /** OAuth2/OIDC-specific configuration */
+  oauth2: oauth2_provider_config_schema.partial().optional(),
+  /** SAML-specific configuration */
+  saml: saml_provider_config_schema.partial().optional(),
+  /** Proxy-specific configuration */
+  proxy: proxy_provider_config_schema.partial().optional(),
+});
+export type AuthConfigType = z.infer<typeof auth_config_schema>;
+
+/**
+ * Authentik plugin options
+ */
+export const authentik_plugin_options_schema = z.object({
+  /** Authentik domain (e.g., authentik.example.com) */
+  domain: z.string().optional(),
+  /** Default authorization flow */
+  default_authorization_flow: authentik_flow_schema.default('implicit-consent'),
+  /** Default proxy outpost name */
+  outpost_name: z.string().default('default-outpost'),
+  /** Whether to generate client secrets automatically */
+  auto_generate_secrets: z.boolean().default(true),
+  /** Output directory for generated blueprints */
+  output_dir: z.string().default('./authentik-blueprints'),
+  /** Blueprint version */
+  blueprint_version: z.number().default(1),
+});
+export type AuthentikPluginOptionsType = z.infer<typeof authentik_plugin_options_schema>;
+
+/**
+ * Authentik application blueprint
+ */
+export interface AuthentikApplicationType {
+  identifiers: {
+    slug: string;
+  };
+  model: 'authentik_core.application';
+  attrs: {
+    name: string;
+    slug: string;
+    provider?: string;
+    meta_description?: string;
+    meta_icon?: string;
+    group?: string;
+    meta_launch_url?: string;
+    policy_engine_mode?: string;
+  };
+}
+
+/**
+ * Authentik provider blueprint (OAuth2)
+ */
+export interface AuthentikOAuth2ProviderType {
+  identifiers: {
+    name: string;
+  };
+  model: 'authentik_providers_oauth2.oauth2provider';
+  attrs: {
+    name: string;
+    client_id: string;
+    client_type: string;
+    client_secret?: string;
+    redirect_uris: string;
+    authorization_flow?: string;
+    signing_key?: string;
+    include_claims_in_id_token: boolean;
+    access_token_validity: string;
+    refresh_token_validity: string;
+    sub_mode: string;
+    issue_refresh_tokens: boolean;
+    property_mappings?: string[];
+  };
+}
+
+/**
+ * Authentik provider blueprint (SAML)
+ */
+export interface AuthentikSAMLProviderType {
+  identifiers: {
+    name: string;
+  };
+  model: 'authentik_providers_saml.samlprovider';
+  attrs: {
+    name: string;
+    acs_url: string;
+    issuer: string;
+    sp_binding: string;
+    audience?: string;
+    authorization_flow?: string;
+    signing_kp?: string;
+    name_id_mapping?: string;
+    assertion_valid_not_before: string;
+    assertion_valid_not_on_or_after: string;
+    session_valid_not_on_or_after: string;
+    property_mappings?: string[];
+  };
+}
+
+/**
+ * Authentik provider blueprint (Proxy)
+ */
+export interface AuthentikProxyProviderType {
+  identifiers: {
+    name: string;
+  };
+  model: 'authentik_providers_proxy.proxyprovider';
+  attrs: {
+    name: string;
+    external_host: string;
+    internal_host?: string;
+    internal_host_ssl_validation: boolean;
+    certificate?: string;
+    skip_path_regex?: string;
+    basic_auth_enabled: boolean;
+    basic_auth_password_attribute?: string;
+    basic_auth_user_attribute?: string;
+    mode: string;
+    authorization_flow?: string;
+    access_token_validity: string;
+    intercept_header_auth: boolean;
+    property_mappings?: string[];
+  };
+}
+
+/**
+ * Authentik blueprint structure
+ */
+export interface AuthentikBlueprintType {
+  version: number;
+  metadata: {
+    name: string;
+    labels?: Record<string, string>;
+  };
+  entries: Array<
+    | AuthentikApplicationType
+    | AuthentikOAuth2ProviderType
+    | AuthentikSAMLProviderType
+    | AuthentikProxyProviderType
+  >;
+}