ZeroTrustKerberosLink Troubleshooting Guide

This comprehensive troubleshooting guide addresses common issues encountered during deployment and operation of ZeroTrustKerberosLink in enterprise environments.

Table of Contents

Authentication Issues

Kerberos Authentication Failures

Issue Symptoms Resolution
Ticket Expired "Ticket expired" or "Ticket not yet valid" errors Verify time synchronization between all servers (KDC, ZTK nodes, client machines); use NTP to maintain accurate time
Keytab Issues "Cannot find key" or "Integrity check failed" errors Regenerate keytab file; verify keytab permissions (should be 0600); ensure correct service principal format
KDC Connectivity "Cannot contact KDC" or timeout errors Check network connectivity to KDC; verify firewall rules allow traffic on ports 88, 464, and 749
Principal Format "Principal unknown" errors Verify principal naming format matches Kerberos realm conventions; check for case sensitivity issues
Clock Skew "Clock skew too great" errors Synchronize clocks between KDC and ZTK servers; adjust max_skew setting in krb5.conf

Diagnostic Steps:

  1. Verify Kerberos configuration: 
    sudo ztk-test kerberos-config
  2. Test KDC connectivity: 
    sudo ztk-test kdc-connectivity
  3. Validate keytab file: 
    sudo klist -kt /etc/ztk/service.keytab
  4. Check time synchronization: 
    sudo timedatectl status

Multi-Factor Authentication Issues

Issue Symptoms Resolution
MFA Provider Unreachable MFA prompts not appearing or timing out Verify network connectivity to MFA provider; check MFA provider status; review API credentials
MFA Configuration "Invalid configuration" errors Verify MFA provider settings in config.yaml; ensure API keys are correctly configured
User Enrollment "User not enrolled" errors Verify user is enrolled in MFA system; check user mapping configuration
Push Notification Failures Push notifications not received Check mobile device connectivity; verify push service configuration; check user device registration

Diagnostic Steps:

  1. Test MFA provider connectivity: 
    sudo ztk-test mfa-connectivity
  2. Verify MFA configuration: 
    sudo ztk-config --validate-mfa
  3. Check MFA logs: 
    sudo journalctl -u ztk-mfa-service -f

AWS Integration Issues

Role Assumption Failures

Issue Symptoms Resolution
Access Denied "AccessDenied" when attempting to assume role Verify trust relationship in IAM role; check principal names in configuration; ensure AWS account IDs match
Missing Permissions "User is not authorized to perform action" errors Review IAM policy attached to role; add required permissions; check for permission boundaries
Invalid External ID "InvalidExternalID" errors Verify external ID in role trust policy matches configuration
Session Duration "Requested DurationSeconds exceeds MaxSessionDuration" Adjust session duration to be less than or equal to the role's maximum session duration