corrad-af-2024/docs/AUTHENTIK_INTEGRATION_IMPLEMENTATION.md

Authentik Native Integration Implementation Guide

Overview

This document outlines the complete implementation of native integration between our RBAC application and Authentik, designed as a frontend interface directly connected to Authentik's data layer. Major Update: The system has been redesigned to eliminate manual synchronization in favor of native integration patterns.

✅ Native Integration Architecture

Design Philosophy

• No Manual Sync: System operates as native Authentik frontend
• Direct API Integration: Real-time communication with Authentik backend
• Simplified UX: User interface focuses on functionality, not sync management
• Data Consistency: Single source of truth through direct integration

Integration Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   RBAC App      │◄──►│   Direct API    │◄──►│   Authentik     │
│   (Frontend)    │    │   Integration   │    │   (Backend)     │
│                 │    │                 │    │                 │
│ • User Mgmt     │    │ • REST Client   │    │ • Users         │
│ • Groups/Roles  │    │ • Real-time     │    │ • Groups        │
│ • Applications  │    │ • Error Handle  │    │ • Applications  │
│ • Resources     │    │ • Validation    │    │ • Permissions   │
└─────────────────┘    └─────────────────┘    └─────────────────┘

✅ Implemented Features

1. Native Form Integration

Standardized FormKit Implementation

// All forms now use consistent pattern
<FormKit 
  type="form" 
  @submit="handleSubmit"
  :actions="false"
>
  <!-- Form fields -->
</FormKit>

<!-- Custom action buttons -->
<div class="flex space-x-3">
  <rs-button @click="resetForm" variant="primary-outline">
    Reset Form
  </rs-button>
  <rs-button @click="submitToAuthentik" :disabled="!isFormValid">
    Create User
  </rs-button>
</div>

Direct API Submission Pattern

// composables/useAuthentikDirectAPI.js
export const useAuthentikDirectAPI = () => {
  const createUser = async (userData) => {
    // Direct API call to Authentik
    const response = await $fetch('/api/authentik/users', {
      method: 'POST',
      body: {
        username: userData.username,
        email: userData.email,
        name: `${userData.firstName} ${userData.lastName}`,
        attributes: {
          firstName: userData.firstName,
          lastName: userData.lastName,
          phone: userData.phone,
          department: userData.department,
          jobTitle: userData.jobTitle,
          employeeId: userData.employeeId
        },
        is_active: userData.isActive,
        groups: userData.groups
      }
    })
    return response
  }

  const createGroup = async (groupData) => {
    return await $fetch('/api/authentik/groups', {
      method: 'POST',
      body: {
        name: groupData.name,
        attributes: {
          description: groupData.description,
          department: groupData.department,
          parentGroup: groupData.parentGroup
        }
      }
    })
  }

  return { createUser, createGroup }
}

2. Resource Management Integration ✅ NEW

Resource API Client

// composables/useResourceAPI.js
export const useResourceAPI = () => {
  const createResource = async (type, data, applicationId) => {
    // Auto-generate key from name
    const key = data.name
      .toLowerCase()
      .replace(/[^a-z0-9]/g, '-')
      .replace(/-+/g, '-')
      .replace(/^-|-$/g, '')
    
    // Direct integration with Authentik permission system
    return await $fetch('/api/authentik/resources', {
      method: 'POST',
      body: {
        ...data,
        key,
        type,
        applicationId,
        authentikMetadata: {
          resourceType: type,
          generatedKey: key,
          applicationContext: applicationId
        }
      }
    })
  }

  const getResources = async (applicationId, type) => {
    return await $fetch(`/api/authentik/resources?app=${applicationId}&type=${type}`)
  }

  const deleteResource = async (resourceId) => {
    return await $fetch(`/api/authentik/resources/${resourceId}`, {
      method: 'DELETE'
    })
  }

  return { createResource, getResources, deleteResource }
}

Resource Data Structure

const resourceSchema = {
  // Menu Resources
  menus: [{
    id: String,
    name: String,           // Display name
    key: String,            // Auto-generated: "user-management"
    path: String,           // "/users"
    applicationId: String,  // "corradaf"
    authentikPermissionId: String, // Direct Authentik permission ID
    createdAt: Date
  }],
  
  // Component Resources  
  components: [{
    id: String,
    name: String,           // "User Profile Actions"
    key: String,            // Auto-generated: "user-profile-actions"
    description: String,    // "Edit, delete user profiles"
    applicationId: String,  // "corradaf"
    authentikPermissionId: String, // Direct Authentik permission ID
    actions: [String],      // ["view", "edit", "delete"]
    createdAt: Date
  }],
  
  // Feature Resources
  features: [{
    id: String,
    name: String,           // "Data Export"
    key: String,            // Auto-generated: "data-export"
    description: String,    // "Export data to CSV/Excel"
    applicationId: String,  // "corradaf"
    authentikPermissionId: String, // Direct Authentik permission ID
    createdAt: Date
  }]
}

3. Enhanced Role Templates System ✅ NEW

Template Management API

// composables/useRoleTemplates.js
export const useRoleTemplates = () => {
  const createTemplate = async (templateData) => {
    return await $fetch('/api/authentik/role-templates', {
      method: 'POST',
      body: {
        name: templateData.name,
        description: templateData.description,
        permissions: {
          menus: templateData.selectedMenus,
          components: templateData.selectedComponents,
          features: templateData.selectedFeatures
        },
        authentikRoleId: null, // Will be populated when template is used
        permissionCount: calculatePermissionCount(templateData)
      }
    })
  }

  const cloneTemplate = async (templateId, newName) => {
    const template = await getTemplate(templateId)
    return await createTemplate({
      ...template,
      name: newName,
      id: undefined // Remove ID for new template
    })
  }

  return { createTemplate, cloneTemplate }
}

Template-to-Role Conversion

const applyTemplateToRole = async (templateId, roleData) => {
  const template = await getTemplate(templateId)
  
  // Create role in Authentik with template permissions
  const authentikRole = await $fetch('/api/authentik/roles', {
    method: 'POST',
    body: {
      name: roleData.name,
      description: roleData.description,
      application: roleData.application,
      permissions: template.permissions,
      templateId: templateId,
      isGlobal: roleData.isGlobal,
      priority: roleData.priority
    }
  })
  
  return authentikRole
}

4. Application Quick Setup Integration ✅ Enhanced

Setup Type Handler

const applySetupType = async (setupType, applicationData) => {
  const setupConfigs = {
    'web-app': {
      providerType: 'oauth2',
      defaultScopes: ['openid', 'profile', 'email'],
      flowBindings: ['default-authentication-flow', 'default-authorization-flow'],
      policyEngine: 'any'
    },
    'api-service': {
      providerType: 'oauth2',
      defaultScopes: ['api:read', 'api:write'],
      flowBindings: ['api-authentication-flow'],
      policyEngine: 'all'
    },
    'enterprise-app': {
      providerType: 'saml',
      ssoConfiguration: 'enterprise-sso',
      flowBindings: ['enterprise-authentication-flow'],
      policyEngine: 'all'
    }
  }

  const config = setupConfigs[setupType]
  
  // Create application in Authentik with smart defaults
  return await $fetch('/api/authentik/applications', {
    method: 'POST',
    body: {
      ...applicationData,
      provider: {
        type: config.providerType,
        ...generateProviderConfig(config, applicationData)
      },
      policyEngineMode: config.policyEngine,
      flowBindings: config.flowBindings
    }
  })
}

🚀 Technical Implementation Patterns

Form Submission Pattern

// Standardized form submission across all pages
const handleFormSubmit = async (formData) => {
  isLoading.value = true
  
  try {
    // Direct API call - no sync logic needed
    const result = await authentikAPI.createEntity(formData)
    
    // Success handling
    await navigateTo('/success-page')
    
  } catch (error) {
    // Error handling
    console.error('Operation failed:', error)
    showErrorNotification(error.message)
  } finally {
    isLoading.value = false
  }
}

Real-time Data Pattern

// Real-time data fetching without sync concerns
const { data: users, refresh } = await useFetch('/api/authentik/users', {
  key: 'users-list',
  transform: (data) => data.map(transformAuthentikUser)
})

// Reactive data updates
watch(() => searchQuery.value, () => {
  refresh()
})

Progressive Disclosure Pattern

// Template-first approach with advanced options
const showAdvancedOptions = ref(false)
const useTemplate = ref(true)

const toggleAdvanced = () => {
  showAdvancedOptions.value = !showAdvancedOptions.value
  if (showAdvancedOptions.value) {
    useTemplate.value = false
  }
}

📱 User Interface Integration

Removed Sync Elements ✅ Major Update

• No Sync Buttons: Removed all manual sync triggers
• No Sync Status: Removed sync status indicators and badges
• No Sync Sections: Removed "Integration" sections from forms
• No Sync Stats: Removed "Synced to Authentik" statistics

Enhanced Navigation ✅ NEW

// Hierarchical navigation structure
const navigation = [
  {
    name: 'Roles',
    icon: 'ph:shield',
    children: [
      { name: 'Role List', path: '/roles' },
      { name: 'Templates', path: '/roles/templates' }
    ]
  },
  {
    name: 'Applications',
    icon: 'ph:app-window',
    children: [
      { name: 'Application List', path: '/applications' },
      { name: 'Resources', path: '/applications/resources' }
    ]
  }
]

Template-First Role Creation ✅ Enhanced

<!-- Role templates as primary method -->
<div class="role-templates">
  <div v-for="template in roleTemplates" :key="template.id">
    <div class="template-card" @click="selectTemplate(template.id)">
      <h4>{{ template.name }}</h4>
      <p>{{ template.description }}</p>
      <span>{{ template.permissionCount }} permissions</span>
    </div>
  </div>
</div>

<!-- Advanced permissions hidden by default -->
<rs-card v-if="showAdvancedPermissions">
  <template #header>
    <Icon name="ph:gear" class="text-orange-600" />
    <h3>Advanced Permissions</h3>
    <rs-badge variant="warning">Expert Mode</rs-badge>
  </template>
  <!-- Detailed permission configuration -->
</rs-card>

🔧 Configuration & Environment

Environment Configuration

// nuxt.config.ts
export default {
  runtimeConfig: {
    // Private keys (server-side only)
    authentikApiUrl: process.env.AUTHENTIK_API_URL,
    authentikApiToken: process.env.AUTHENTIK_API_TOKEN,
    
    // Public keys (client-side accessible)
    public: {
      authentikDomain: process.env.AUTHENTIK_DOMAIN,
      appName: process.env.APP_NAME || 'CorradAF RBAC'
    }
  }
}

API Proxy Configuration

// server/api/authentik/[...].js
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig()
  const path = getRouterParam(event, 'path')
  
  // Proxy requests to Authentik API
  return await $fetch(`${config.authentikApiUrl}/${path}`, {
    method: getMethod(event),
    headers: {
      'Authorization': `Bearer ${config.authentikApiToken}`,
      'Content-Type': 'application/json'
    },
    body: await readBody(event)
  })
})

📊 Implementation Status

Completed Integrations ✅

Component	Native Integration	Form Standards	UX Enhancement
User Management	✅ Complete	✅ :actions="false"	✅ Simplified
Group Management	✅ Complete	✅ :actions="false"	✅ Simplified
Role Management	✅ Complete	✅ :actions="false"	✅ Templates
Application Management	✅ Complete	✅ :actions="false"	✅ Quick Setup
Resource Management	✅ Complete	✅ :actions="false"	✅ Centralized

Removed Sync Elements ✅

Page	Sync Buttons	Sync Status	Integration Sections
/users	✅ Removed	✅ Removed	✅ Removed
/users/create	✅ Removed	✅ Removed	✅ Simplified
/groups	✅ Removed	✅ Removed	✅ Removed
/groups/create	✅ Removed	✅ Removed	✅ Simplified
/roles/create	✅ Removed	✅ Removed	✅ Simplified
/applications	✅ Removed	✅ Removed	✅ Removed
/applications/create	✅ Removed	✅ Removed	✅ Simplified
/rbac-permission	✅ Removed	✅ Removed	✅ Updated

Enhanced Features ✅ NEW

Feature	Status	Description
Role Templates	✅ Complete	Pre-configured role templates with permission sets
Application Resources	✅ Complete	Centralized resource management (menus, components, features)
Quick Setup Types	✅ Complete	Template-based application configuration
Progressive Disclosure	✅ Complete	Advanced options hidden by default
Hierarchical Navigation	✅ Complete	Organized menu structure with sub-items

🎯 Integration Benefits

User Experience Benefits

• Simplified Interface: No confusing sync options or status displays
• Faster Workflows: Direct action without sync delays
• Reduced Errors: No sync-related errors or failures
• Consistent Behavior: Predictable responses to user actions

Technical Benefits

• Real-time Updates: Immediate data consistency
• Reduced Complexity: No sync state management needed
• Better Performance: Direct API calls without sync overhead
• Cleaner Code: Simplified business logic without sync concerns

Administrative Benefits

• Template-First Approach: Common tasks simplified with smart defaults
• Centralized Management: Single interface for all resource types
• Progressive Disclosure: Expert features available when needed
• Consistent Patterns: Same interaction patterns across all modules

🚧 Next Implementation Phase

Backend API Development (Priority 1)

• Authentik API Proxy: Server-side API proxy for secure communication
• Data Validation: Request/response validation middleware
• Error Handling: Comprehensive error handling and logging
• Authentication: Proper authentication flow implementation

Advanced Features (Priority 2)

• Real-time Updates: WebSocket integration for live data updates
• Bulk Operations: Efficient batch processing for large operations
• Audit Logging: Comprehensive activity tracking
• Advanced Search: Cross-entity search and filtering

Performance Optimization (Priority 3)

• Caching Strategies: Intelligent caching for frequently accessed data
• Lazy Loading: Optimized loading for large datasets
• Request Optimization: Batch API calls and request optimization

---

Status: Native Authentik integration approach implemented with simplified UX, comprehensive resource management, and enhanced template systems. Manual sync functionality completely removed. Ready for backend API integration.