Troubleshooting

Common Issues and Solutions

Login and Authentication Issues

function Test-AuthentikAuthentication
{
    param(
        [Parameter(Mandatory)]
        [string]$AuthentikUrl,
        [Parameter(Mandatory)]
        [string]$Username,
        [Parameter(Mandatory)]
        [SecureString]$Password,
        [string]$FlowSlug = "default-authentication-flow"
    )
    
    Write-Host "Testing authentication for user: $Username" -ForegroundColor Cyan
    
    try
    {
        # Get authentication flow
        $flowResponse = Invoke-RestMethod -Uri "$AuthentikUrl/api/v3/flows/executor/$FlowSlug/"
        
        Write-Host "Flow retrieved successfully" -ForegroundColor Green
        Write-Host "Available stages: $($flowResponse.component)" -ForegroundColor Yellow
        
        # Test identification stage
        $identificationData = @{
            uid_field = $Username
        } | ConvertTo-Json
        
        $identificationResponse = Invoke-RestMethod -Uri "$AuthentikUrl/api/v3/flows/executor/$FlowSlug/" -Method POST -Body $identificationData -ContentType "application/json"
        
        if ($identificationResponse.type -eq "redirect")
        {
            Write-Host "✓ User identification successful" -ForegroundColor Green
        }
        else
        {
            Write-Warning "User identification stage returned: $($identificationResponse.type)"
        }
        
        return @{
            Success = $true
            Flow = $flowResponse
            Stage = $identificationResponse.type
        }
    }
    catch
    {
        Write-Error "Authentication test failed: $($_.Exception.Message)"
        
        # Provide troubleshooting suggestions
        Write-Host "`nTroubleshooting suggestions:" -ForegroundColor Yellow
        Write-Host "1. Verify user exists and is active" -ForegroundColor White
        Write-Host "2. Check authentication flow configuration" -ForegroundColor White
        Write-Host "3. Review authentication logs" -ForegroundColor White
        Write-Host "4. Verify source configuration (LDAP/Internal)" -ForegroundColor White
        
        return @{ Success = $false; Error = $_.Exception.Message }
    }
}

Diagnostic Tools

function Get-AuthentikDiagnostics
{
    param(
        [Parameter(Mandatory)]
        [string]$AuthentikUrl,
        [string]$ApiToken,
        [switch]$IncludeLogs,
        [int]$LogHours = 24
    )
    
    $diagnostics = @{
        timestamp = Get-Date
        system_info = @{}
        health_checks = @{}
        configuration = @{}
        logs = @()
    }
    
    try
    {
        # System information
        Write-Host "Gathering system information..." -ForegroundColor Yellow
        
        $headers = @{ 'Authorization' = "Bearer $ApiToken" }
        
        # Version information
        $versionInfo = Invoke-RestMethod -Uri "$AuthentikUrl/api/v3/admin/version/" -Headers $headers
        $diagnostics.system_info.version = $versionInfo
        
        # System metrics
        $metricsResponse = Invoke-WebRequest -Uri "$AuthentikUrl/-/metrics/" -UseBasicParsing
        $diagnostics.system_info.metrics = $metricsResponse.Content
        
        # Health checks
        Write-Host "Performing health checks..." -ForegroundColor Yellow
        
        $healthChecks = @{
            "live" = "$AuthentikUrl/-/health/live/"
            "ready" = "$AuthentikUrl/-/health/ready/"
        }
        
        foreach ($check in $healthChecks.Keys)
        {
            try
            {
                $response = Invoke-WebRequest -Uri $healthChecks[$check] -UseBasicParsing
                $diagnostics.health_checks[$check] = @{
                    status = $response.StatusCode
                    content = $response.Content
                }
            }
            catch
            {
                $diagnostics.health_checks[$check] = @{
                    status = "error"
                    error = $_.Exception.Message
                }
            }
        }
        
        # Configuration summary
        Write-Host "Gathering configuration summary..." -ForegroundColor Yellow
        
        $configEndpoints = @{
            "applications" = "/api/v3/core/applications/"
            "flows" = "/api/v3/flows/instances/"
            "stages" = "/api/v3/stages/all/"
            "policies" = "/api/v3/policies/all/"
        }
        
        foreach ($endpoint in $configEndpoints.Keys)
        {
            try
            {
                $response = Invoke-RestMethod -Uri "$AuthentikUrl$($configEndpoints[$endpoint])" -Headers $headers
                $diagnostics.configuration[$endpoint] = @{
                    count = $response.pagination.count
                    items = $response.results | Select-Object -First 5 name, pk
                }
            }
            catch
            {
                $diagnostics.configuration[$endpoint] = @{ error = $_.Exception.Message }
            }
        }
        
        # Recent logs (if requested)
        if ($IncludeLogs -and $ApiToken)
        {
            Write-Host "Gathering recent logs..." -ForegroundColor Yellow
            
            $logsResponse = Invoke-RestMethod -Uri "$AuthentikUrl/api/v3/events/events/?ordering=-created&page_size=100" -Headers $headers
            $diagnostics.logs = $logsResponse.results | Where-Object { 
                $_.created -gt (Get-Date).AddHours(-$LogHours) 
            }
        }
        
        Write-Host "Diagnostics completed successfully" -ForegroundColor Green
        return $diagnostics
    }
    catch
    {
        Write-Error "Diagnostics collection failed: $($_.Exception.Message)"
        return $null
    }
}

---

Navigation

◄ Backup and Recovery · Authentik Overview · Best Practices and Automation ►