# 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** ```javascript // All forms now use consistent pattern
Reset Form Create User
``` #### **Direct API Submission Pattern** ```javascript // 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** ```javascript // 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** ```javascript 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** ```javascript // 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** ```javascript 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** ```javascript 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** ```javascript // 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** ```javascript // 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** ```javascript // 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** ```javascript // 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** ```vue

{{ template.name }}

{{ template.description }}

{{ template.permissionCount }} permissions
``` ## 🔧 **Configuration & Environment** ### **Environment Configuration** ```javascript // 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** ```javascript // 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.