OTP Configuration - CLI Reference

Overview

OTP configuration defines global parameters that control how FreeIPA validates one-time password tokens during authentication. These settings apply to all OTP tokens in the IPA domain and balance security (strict validation) against usability (tolerance for clock skew and counter drift).

FreeIPA maintains separate configuration parameters for TOTP (Time-Based OTP) and HOTP (Counter-Based OTP) tokens, recognizing their different validation requirements. TOTP configuration deals with time synchronization tolerance, while HOTP configuration deals with counter lookahead windows.

Unlike individual token parameters (algorithm, digits, interval) which are set per-token at creation time, OTP configuration settings are global and affect validation of all tokens. Administrators typically configure these settings once during initial IPA deployment and adjust only when experiencing authentication issues related to clock skew or counter drift.

TOTP Configuration

Authentication Window

The TOTP authentication window (--totp-auth-window) defines how much time variance IPA tolerates during normal authentication attempts. This accommodates minor clock skew between user devices and IPA servers.

Default: 300 seconds (5 minutes) Units: Seconds of total time variance (±half the window from current time) Typical range: 180-600 seconds (3-10 minutes)

With the default 300-second window:

IPA checks codes valid from 150 seconds ago to 150 seconds in the future
For 30-second TOTP tokens, this means checking 5 time windows before and 5 after
Tolerates device clocks that are up to 2.5 minutes fast or slow

Security vs usability tradeoff:

Narrower window (e.g., 180 seconds): More secure (shorter validity), but users with clock skew may fail authentication
Wider window (e.g., 600 seconds): More user-friendly (tolerates larger clock differences), but increases replay attack window

Synchronization Window

The TOTP synchronization window (--totp-sync-window) defines the maximum time variance IPA accepts during token synchronization operations. This is used when IPA detects that a token has significant clock drift and attempts to calculate the correct offset.

Default: 86400 seconds (24 hours) Units: Seconds of total time variance Typical range: 3600-172800 seconds (1 hour - 2 days)

The synchronization window is larger than the authentication window because:

Initial token setup may occur on devices with badly misconfigured clocks
Users traveling across time zones may have devices stuck in the wrong timezone
Synchronization is an infrequent operation (typically once at token enrollment)

When synchronization occurs:

User attempts authentication with a code that fails within the auth window
IPA expands the search to the synchronization window
If a valid code is found, IPA calculates and stores the time offset
Future authentications use the learned offset + auth window

Security note: The synchronization window should be wide enough to handle legitimate clock issues but narrow enough to prevent accepting very old or future codes. A 24-hour window is usually sufficient.

HOTP Configuration

Authentication Window

The HOTP authentication window (--hotp-auth-window) defines how many counter values ahead of the expected counter IPA checks during normal authentication.

Default: 10 Units: Number of counter values to check ahead Typical range: 5-20

With the default window of 10:

If IPA expects counter value 50, it checks codes for counter 50, 51, 52, … 59
Tolerates users generating (but not using) up to 9 codes before authenticating
Each successful authentication updates the stored counter to the value used + 1

Why counter drift occurs:

User accidentally presses hardware token button multiple times
User tests the token without authenticating
User generates a code, then waits for a new code before authenticating

Security vs usability tradeoff:

Smaller window (e.g., 5): More secure (less tolerance for reused codes), but users who accidentally generate codes may get locked out
Larger window (e.g., 20): More user-friendly, but allows more old codes to be accepted

Synchronization Window

The HOTP synchronization window (--hotp-sync-window) defines the maximum counter lookahead during token synchronization operations.

Default: 100 Units: Number of counter values to check ahead Typical range: 50-200

The synchronization window is larger than the authentication window because:

Initial token import may have incorrect counter values
Hardware tokens may have been tested extensively by users or vendors before import
Synchronization corrects significant counter drift

When synchronization occurs:

User authentication fails within the auth window
IPA expands the search to the synchronization window
If a valid code is found, IPA updates the stored counter to the matched value + 1
Future authentications use the updated counter + auth window

Security note: Even with a large synchronization window, each code can only be used once due to HOTP’s counter-based design, so the security risk is lower than with TOTP.

Window Size Recommendations

Conservative (High Security)

For environments prioritizing security over convenience:

$ ipa otpconfig-mod \
  --totp-auth-window=180 \
  --totp-sync-window=3600 \
  --hotp-auth-window=5 \
  --hotp-sync-window=50

Tight TOTP windows: 3 minutes auth, 1 hour sync
Tight HOTP windows: 5 codes auth, 50 codes sync
Best for: Highly secure environments with good time synchronization
Risk: Increased authentication failures due to clock issues

Balanced (Default)

Default settings balance security and usability:

$ ipa otpconfig-mod \
  --totp-auth-window=300 \
  --totp-sync-window=86400 \
  --hotp-auth-window=10 \
  --hotp-sync-window=100

Moderate TOTP windows: 5 minutes auth, 24 hours sync
Moderate HOTP windows: 10 codes auth, 100 codes sync
Best for: Most environments
Already configured by default

Permissive (High Usability)

For environments prioritizing user experience:

$ ipa otpconfig-mod \
  --totp-auth-window=600 \
  --totp-sync-window=172800 \
  --hotp-auth-window=20 \
  --hotp-sync-window=200

Wide TOTP windows: 10 minutes auth, 48 hours sync
Wide HOTP windows: 20 codes auth, 200 codes sync
Best for: Environments with poor time synchronization or heavy mobile device usage
Risk: Larger window for replay attacks

Examples

View Current Configuration

# Show OTP configuration (summary)
$ ipa otpconfig-show
  TOTP authentication time variance: 300
  TOTP synchronization time variance: 86400
  HOTP authentication skip-ahead: 10
  HOTP synchronization skip-ahead: 100

View All Configuration Attributes

# Show complete configuration including LDAP attributes
$ ipa otpconfig-show --all
  TOTP authentication time variance: 300
  TOTP synchronization time variance: 86400
  HOTP authentication skip-ahead: 10
  HOTP synchronization skip-ahead: 100
  dn: cn=otp,cn=etc,dc=example,dc=com
  objectclass: top, ipaOTPConfig

Adjust TOTP Authentication Window

# Tighten authentication window for increased security
$ ipa otpconfig-mod --totp-auth-window=180
  TOTP authentication time variance: 180

# Widen authentication window for clock skew tolerance
$ ipa otpconfig-mod --totp-auth-window=600
  TOTP authentication time variance: 600

Adjust TOTP Synchronization Window

# Reduce sync window for tighter security
$ ipa otpconfig-mod --totp-sync-window=3600
  TOTP synchronization time variance: 3600

# Increase sync window for global deployments
$ ipa otpconfig-mod --totp-sync-window=172800
  TOTP synchronization time variance: 172800

Adjust HOTP Authentication Window

# Reduce auth window to minimize counter drift tolerance
$ ipa otpconfig-mod --hotp-auth-window=5
  HOTP authentication skip-ahead: 5

# Increase auth window for users who frequently test tokens
$ ipa otpconfig-mod --hotp-auth-window=20
  HOTP authentication skip-ahead: 20

Adjust HOTP Synchronization Window

# Reduce sync window after initial token deployment stabilizes
$ ipa otpconfig-mod --hotp-sync-window=50
  HOTP synchronization skip-ahead: 50

# Increase sync window during token import phase
$ ipa otpconfig-mod --hotp-sync-window=200
  HOTP synchronization skip-ahead: 200

Configure for Multi-Timezone Deployment

# Accommodate users traveling globally
$ ipa otpconfig-mod \
  --totp-auth-window=600 \
  --totp-sync-window=172800
  TOTP authentication time variance: 600
  TOTP synchronization time variance: 172800

Configure for High-Security Environment

# Minimize windows for maximum security
$ ipa otpconfig-mod \
  --totp-auth-window=180 \
  --totp-sync-window=3600 \
  --hotp-auth-window=5 \
  --hotp-sync-window=50

Configure for Development/Testing

# Very wide windows for testing with unsynchronized clocks
$ ipa otpconfig-mod \
  --totp-auth-window=1800 \
  --totp-sync-window=604800 \
  --hotp-auth-window=50 \
  --hotp-sync-window=500

# Note: Do not use these settings in production!

Reset to Defaults

# Return to default configuration
$ ipa otpconfig-mod \
  --totp-auth-window=300 \
  --totp-sync-window=86400 \
  --hotp-auth-window=10 \
  --hotp-sync-window=100

Best Practices

Initial Configuration

Start with defaults: FreeIPA’s default OTP configuration is well-balanced for most environments. Only adjust if you experience specific authentication issues.

Monitor before adjusting: Before changing windows, review authentication logs to understand the actual clock skew or counter drift in your environment.

Test in non-production: If you must adjust windows, test new values in a development environment first to ensure they don’t cause unexpected authentication failures.

Document changes: Record why you adjusted OTP configuration and the business justification. Future administrators will need this context.

Security Considerations

Minimize authentication windows: Keep TOTP auth window as small as possible while still accommodating legitimate clock variance. Each additional second increases the replay attack window.

Synchronization windows are less critical: Synchronization occurs rarely (typically once per token), so wider sync windows have minimal security impact.

Time synchronization infrastructure: Rather than widening TOTP windows to accommodate clock skew, improve time synchronization (NTP) across your infrastructure. This allows tighter windows with better security.

HOTP is more forgiving: HOTP counter-based design prevents replay attacks even with large windows, so HOTP windows can be more generous without significant security risk.

Regular audits: Periodically review OTP authentication failures to detect systemic issues (many users failing TOTP) vs individual issues (one user with bad clock).

Operational Practices

Gradual adjustments: When tightening windows, do so incrementally (reduce by 60-120 seconds at a time) and monitor authentication failure rates for 24-48 hours before further tightening.

Helpdesk preparation: Brief helpdesk staff before changing OTP windows so they can recognize and address window-related authentication failures.

Communication: Notify users before reducing windows, especially in environments where many users have devices with poor time synchronization.

Rollback plan: Know how to quickly revert to previous window values if a change causes widespread authentication failures.

Coordinate with time changes: When implementing NTP improvements or correcting server time, temporarily widen TOTP windows to accommodate the transition.

Multi-Replica Environments

Configuration replication: OTP configuration changes replicate via LDAP. Allow 1-2 minutes for changes to propagate to all replicas in multi-master environments.

Consistent settings: Ensure all IPA replicas have synchronized clocks (NTP). TOTP authentication relies on consistent time across the domain.

Testing across replicas: After adjusting windows, test authentication against multiple IPA replicas to ensure configuration replication succeeded.

Mobile Device Considerations

Automatic time sync: Educate users to enable automatic time synchronization on mobile devices running authenticator apps. Manual time settings often drift significantly.

Timezone awareness: Users traveling across timezones may have device timezone mismatch. TOTP is based on UTC, so timezone errors shouldn’t matter if absolute time is correct—but some devices handle this poorly.

Offline clock drift: Devices that are frequently offline (tablets, backup phones) may have significant clock drift when powered on. Wider TOTP windows accommodate this.

Hardware Token Considerations

Counter tracking: Hardware HOTP tokens require careful counter management. Users should be trained not to “play with” hardware tokens (pressing the button without authenticating).

Initial counter import: When importing pre-configured hardware tokens from vendors, use the widest practical synchronization window (200+) to account for vendor testing.

Replacement workflow: When replacing hardware tokens, disable old tokens immediately to prevent confusion about which counter value is current.

Integration Points

OTP Tokens

OTP configuration settings apply to all tokens created via otptoken-add. Individual tokens inherit these global windows during validation but cannot override them.

Commands: otptoken-add, otptoken-find, otptoken-show Relationship: Global configuration affects all token validation Note: Token-specific parameters (algorithm, digits, interval) are set per-token; global config controls validation windows only

User Authentication Types

Users must be configured to require OTP authentication for OTP configuration to take effect:

# Enable OTP authentication for a user
$ ipa user-mod alice --user-auth-type=otp

# Enable password + OTP (two-factor)
$ ipa user-mod alice --user-auth-type=password,otp

Without appropriate user authentication types configured, OTP tokens won’t be requested during authentication.

Kerberos KDC

The Kerberos KDC uses OTP configuration parameters when validating OTP codes during FAST-protected authentication:

KDC requests OTP via FAST channel
User provides OTP code
KDC validates against tokens using configured windows
TGT issued on successful validation

SSSD Clients

SSSD retrieves OTP configuration from IPA servers and uses it to validate OTP codes during client authentication. Configuration changes propagate to SSSD caches within minutes.

RADIUS Integration

When IPA acts as a RADIUS server (radiusproxy), OTP validation uses the same global configuration windows. RADIUS clients inherit IPA’s OTP policies.

Time Synchronization (NTP)

Accurate time synchronization is critical for TOTP authentication:

IPA servers should sync with reliable NTP sources
Clients should also use NTP (especially mobile devices)
Clock skew between servers and clients directly impacts TOTP success rate

Monitor NTP synchronization status regularly. If time drift exceeds half the TOTP auth window, authentication failures will occur.

Logging and Monitoring

OTP authentication events are logged in IPA server logs (/var/log/krb5kdc.log):

Successful authentications
Failed authentications (with reason: expired code, out of window, etc.)
Synchronization events

Monitor these logs to detect:

Systemic clock issues (many TOTP failures)
Counter drift patterns (many HOTP failures)
Potential token compromise (repeated failures for one user)

Replication

OTP configuration is stored in LDAP and replicates to all IPA servers. Changes to OTP config propagate via normal LDAP replication:

Typically completes within 1-2 minutes in healthy replication topology
Check replication status if OTP behavior differs across servers
Configuration is singular (no per-server OTP settings)

Security Considerations

Replay Attack Window

The TOTP authentication window defines the replay attack window—the time during which a captured OTP code remains valid:

300-second window: Captured code valid for up to 5 minutes
600-second window: Captured code valid for up to 10 minutes

Mitigation: Narrower windows reduce replay risk but increase authentication friction. Balance based on threat model.

Token Synchronization Risks

The TOTP synchronization window is checked only after authentication window fails, so it doesn’t expand the replay window for already-synchronized tokens. However:

Very wide sync windows (>48 hours) may accept codes from tokens with severely misconfigured clocks
An attacker who can capture a code and knows the approximate time offset could potentially use it

Mitigation: Set sync windows wide enough for legitimate use but narrow enough to prevent accepting codes from absurdly wrong times.

Counter Lookahead

HOTP authentication and synchronization windows don’t create replay attack vulnerabilities because each counter value’s code can only be used once. However:

Very wide windows allow old codes to be accepted longer
If an attacker can predict how many codes a user will generate before authenticating, they could pre-generate valid codes

Mitigation: HOTP is generally safer than TOTP regarding window size because counter-based design prevents replay.

Brute Force Considerations

OTP validation windows don’t affect brute force attack resistance—that’s controlled by the number of possible codes (typically 10^6 for 6-digit tokens or 10^8 for 8-digit tokens) and account lockout policies.

Note: FreeIPA includes rate-limiting for OTP authentication attempts, independent of window configuration.

Configuration Modification Permissions

Only users with administrative privileges can modify OTP configuration. In IPA’s default RBAC model, this means members of the admins group. There’s no granular delegation of OTP configuration management separate from general administrative access. This prevents unauthorized users from weakening OTP security by widening validation windows, but also means delegating OTP management requires granting broader admin privileges. Organizations requiring separation of duties may need custom RBAC roles.

Overly Permissive Windows

Configuring extremely wide TOTP authentication windows (e.g., 3600 seconds / 1 hour) to “solve” authentication issues effectively degrades OTP security to the point where it provides minimal advantage over password-only authentication. If a 6-digit TOTP code is valid for an hour, an attacker has significant time to capture and reuse codes. Very wide windows may indicate underlying infrastructure problems (poor time synchronization) that should be addressed rather than worked around. Document business justification for any auth window exceeding 600 seconds (10 minutes) and investigate root causes of authentication failures rather than continuously widening windows.

TOTP Synchronization Abuse

The TOTP synchronization mechanism, while necessary for handling clock drift, can be abused if the synchronization window is extremely wide (e.g., weeks). An attacker who can capture a TOTP code and approximate when it was generated could potentially use old codes within the sync window. While this requires the initial authentication to fail (triggering synchronization), phishing attacks combined with synchronization abuse could enable unauthorized access. Set synchronization windows based on realistic clock drift scenarios (24-48 hours is typically sufficient) rather than “maximum convenience.”

HOTP Counter Exhaustion

Very narrow HOTP authentication windows (e.g., 2-3 codes) combined with user behavior (accidentally pressing hardware token buttons) can lead to rapid counter exhaustion where the user-side counter becomes so far ahead that it exceeds even the synchronization window. This results in permanent authentication failure requiring administrative intervention to reset the token. Educate users on proper hardware token handling and set HOTP windows that balance security with realistic user error tolerance (10-20 for auth window is reasonable).

Configuration Change Impact on Active Sessions

Changes to OTP configuration affect authentication attempts immediately after replication completes. However, active user sessions with already-issued Kerberos TGTs are unaffected. This creates a window where policy change doesn’t apply uniformly. If OTP windows are tightened in response to a security incident, active sessions bypass the new security posture until TGTs expire. Consider forcing TGT expiration or user reauthentication after security-critical OTP configuration changes.

Lack of Per-User or Per-Token Window Customization

OTP configuration is global—all users and all tokens use the same validation windows. Organizations cannot configure stricter windows for high-privilege users (e.g., administrators) while maintaining wider windows for general users. This limits security customization options. Workaround: Use different authentication methods for high-privilege accounts (e.g., hardware security keys via PKINIT, external IdP with stricter MFA) rather than relying solely on OTP with global configuration.

Clock Skew Masking Systemic Issues

Widening TOTP windows to accommodate “clock skew” may mask underlying NTP infrastructure failures, misconfigured time zones, or broken time synchronization. Rather than treating clock-related authentication failures as a window-sizing problem, investigate root causes: Are IPA servers synchronized to reliable NTP sources? Are client devices configured for automatic time sync? Are there network/firewall issues preventing NTP? Addressing infrastructure problems allows tighter, more secure windows.

Audit Logging Gaps for Configuration Changes

OTP configuration modifications are logged in IPA audit logs, but correlating configuration changes with changes in authentication success/failure rates requires manual analysis. An administrator might widen windows without realizing the security impact, or an attacker with compromised admin credentials could widen windows to enable attack scenarios. Implement monitoring that alerts on OTP configuration changes and correlates with authentication metrics: if auth windows doubled and failure rates didn’t decrease, investigate why windows were changed.

Synchronization Window as Attack Surface

TOTP synchronization expands the code validity window beyond the authentication window only when authentication initially fails. However, an attacker who can trigger repeated authentication attempts (causing synchronization checks) may exploit this to use older codes. The synchronization mechanism itself could be an attack vector if an adversary can manipulate device clocks or intercept codes at specific times. This is a sophisticated attack requiring precise timing, but extremely wide sync windows increase feasibility. Limit sync windows to realistic clock correction scenarios.

Test/Development Configuration in Production

Administrators may configure very wide OTP windows in development/testing environments to simplify testing (avoiding time sync issues), then accidentally deploy these permissive settings to production via configuration replication or copy-paste errors. Production systems inherit insecure OTP validation, potentially for extended periods before detection. Implement configuration validation in deployment pipelines: alert if production OTP windows exceed defined thresholds (e.g., auth window >600s, sync window >86400s). Document production vs. non-production OTP configuration standards.

Use Cases

1. Resolving TOTP Authentication Failures Due to Clock Skew

Users report sporadic TOTP authentication failures. Investigation reveals mobile device clocks are slightly out of sync with IPA servers.

# Check current OTP configuration
ipa otpconfig-show
# TOTP authentication time variance: 300 (5 minutes)

# Review authentication failure logs
journalctl -u krb5kdc | grep -i "OTP" | grep -i "fail"
# Multiple failures with "OTP code expired" or "invalid OTP"

# Check time offset between client and server
# On client device:
date
# Wed May 12 14:35:45 UTC 2026

# On IPA server:
date
# Wed May 12 14:32:12 UTC 2026

# Clock skew: ~3.5 minutes (210 seconds)
# Current 300s window should handle ±150s, but device is 210s fast

# Widen TOTP authentication window to accommodate current skew
ipa otpconfig-mod --totp-auth-window=600
# TOTP authentication time variance: 600 (10 minutes, ±300s)

# Test authentication with adjusted window
# User attempts authentication again - succeeds

# Long-term solution: Fix time synchronization
# Enable NTP on mobile devices, verify IPA servers using NTP
# After fixing time sync, tighten window back to 300 or 180

Result: TOTP authentication failures resolved by temporarily widening window. Time synchronization issues addressed as permanent solution, allowing window to be tightened afterward.

2. Configuring for Global Workforce with Mobile Devices

Multinational organization has employees traveling frequently across time zones with mobile authenticator apps that sometimes have clock drift.

# Organization has users in Americas, Europe, Asia-Pacific
# Mobile devices may have timezone misconfiguration or disabled auto-time

# Configure permissive TOTP windows for usability
ipa otpconfig-mod \
  --totp-auth-window=600 \
  --totp-sync-window=172800

# 10-minute auth window (±5 minutes)
# 48-hour sync window for initial setup or severe clock issues

# Document decision
cat > /root/otp-config-rationale.txt <<EOF
OTP Configuration: Permissive (2026-05-12)

Rationale: Global workforce with heavy mobile device usage.
Frequent travel across timezones creates device clock sync issues.

Settings:
- TOTP auth window: 600s (10 min) - accommodates ±5 min clock drift
- TOTP sync window: 172800s (48 hrs) - handles severely misconfigured devices

Trade-off: Wider replay attack window accepted for user experience.
Mitigation: Strong password policy + OTP (2FA) + account lockout.

Review quarterly: If NTP adoption increases, tighten windows.
EOF

# Communicate to helpdesk
# Prepare staff for occasional sync events with very wrong device clocks

Result: OTP configuration optimized for mobile-heavy, globally distributed workforce. Acceptable security/usability balance documented.

3. Tightening Windows for High-Security Environment

Financial services organization needs to tighten OTP configuration for compliance with security frameworks requiring minimal MFA code validity.

# Current configuration (defaults)
ipa otpconfig-show
# TOTP authentication time variance: 300
# TOTP synchronization time variance: 86400
# HOTP authentication skip-ahead: 10
# HOTP synchronization skip-ahead: 100

# Security team requires <3 minute OTP code validity
# Implement conservative configuration
ipa otpconfig-mod \
  --totp-auth-window=180 \
  --totp-sync-window=3600 \
  --hotp-auth-window=5 \
  --hotp-sync-window=50

# Verify changes
ipa otpconfig-show
# TOTP authentication time variance: 180 (3 minutes)
# TOTP synchronization time variance: 3600 (1 hour)
# HOTP authentication skip-ahead: 5
# HOTP synchronization skip-ahead: 50

# Test authentication with tightened windows
# Perform pilot with small user group before full deployment

# Monitor authentication failure rates
# If failures spike >5%, investigate time sync before widening windows

# Document for compliance audit
echo "OTP configuration tightened to meet PCI-DSS 3-minute MFA validity requirement" >> /var/log/compliance-changes.log

Result: OTP configuration meets compliance requirements for minimal code validity period. Gradual rollout with monitoring prevents disruption.

4. Troubleshooting HOTP Counter Drift

User with hardware HOTP token unable to authenticate. Counter has drifted beyond authentication window.

# User reports HOTP token not working
# Check current HOTP configuration
ipa otpconfig-show
# HOTP authentication skip-ahead: 10
# HOTP synchronization skip-ahead: 100

# User may have accidentally pressed token button multiple times
# Or tested token without authenticating

# Temporarily widen HOTP synchronization window for this user's recovery
ipa otpconfig-mod --hotp-sync-window=200
# HOTP synchronization skip-ahead: 200

# Ask user to generate new code and attempt authentication
# IPA will search up to 200 counter values ahead
# If found, counter resyncs automatically

# Authentication succeeds - counter resynchronized

# Return HOTP sync window to normal
ipa otpconfig-mod --hotp-sync-window=100

# Educate user: Don't press hardware token button unless authenticating
# Each press increments counter even if code not used

# Alternative: Reset token counter manually if sync fails
# ipa otptoken-mod <token-uuid> --setattr=ipatokenhotpcounter=0

Result: HOTP counter drift resolved via temporary synchronization window expansion. User educated on proper hardware token usage.

5. Initial Token Deployment with Wide Synchronization Windows

Organization deploying 500 hardware HOTP tokens to employees. Tokens from vendor may have been tested, causing unknown counter offsets.

# Before token distribution, widen HOTP synchronization window
ipa otpconfig-mod --hotp-sync-window=200
# HOTP synchronization skip-ahead: 200

# Allows tokens to sync even if vendor tested them (counter drift)

# Distribute tokens to users with instructions
# "First authentication will synchronize token counter"

# Monitor initial authentication attempts
journalctl -u krb5kdc | grep -i "HOTP.*sync"
# Look for successful synchronization events

# After 90% of users have successfully authenticated (2-4 weeks)
# Review counter drift patterns
# Most tokens synchronized within 50-100 counter values

# Tighten synchronization window to operational value
ipa otpconfig-mod --hotp-sync-window=100
# Returns to standard configuration

# Document token deployment process for future procurements

Result: Successful hardware token deployment with initial wide sync window to handle vendor testing. Window reduced to normal after deployment phase complete.

6. Reverting Overly Permissive Configuration

Security audit discovers OTP windows were inadvertently configured far too wide during troubleshooting and never corrected.

# Security audit review
ipa otpconfig-show --all
# TOTP authentication time variance: 1800 (30 minutes!)
# TOTP synchronization time variance: 604800 (1 week!)
# HOTP authentication skip-ahead: 50
# HOTP synchronization skip-ahead: 500

# Extremely permissive - degrades OTP security significantly
# Check change history
ipa-audit | grep otpconfig-mod
# Modified 6 months ago during incident, never reverted

# Return to secure defaults
ipa otpconfig-mod \
  --totp-auth-window=300 \
  --totp-sync-window=86400 \
  --hotp-auth-window=10 \
  --hotp-sync-window=100

# Notify users of upcoming change
# "OTP authentication policies being tightened for security compliance"

# Monitor authentication failure rates for 48 hours after change
# Investigate any spike in failures

# No significant increase in failures - users' devices well synchronized
# Overly wide windows were unnecessary

# Document remediation
echo "$(date): OTP configuration corrected from overly permissive settings found in security audit" >> /var/log/security-remediation.log

Result: Overly permissive OTP configuration identified and corrected. Security posture improved without impacting user authentication success.

7. Configuring for Development Environment

Development environment needs very permissive OTP configuration to simplify testing without requiring precise time synchronization.

# Development IPA server
# Developers testing OTP integration without NTP

# Configure maximum tolerance
ipa otpconfig-mod \
  --totp-auth-window=3600 \
  --totp-sync-window=604800 \
  --hotp-auth-window=100 \
  --hotp-sync-window=1000

# TOTP: 1-hour auth window, 1-week sync window
# HOTP: 100 codes auth, 1000 codes sync

# Add warning banner to prevent accidental production deployment
cat > /etc/motd <<EOF
================================================
WARNING: DEVELOPMENT ENVIRONMENT
OTP Configuration: INSECURE (wide windows)
DO NOT use this configuration in production!
================================================
EOF

# Document that this is dev-only
echo "# DEV-ONLY CONFIGURATION - NOT FOR PRODUCTION" >> /etc/ipa/default.conf

# Create script to reset to production-safe defaults
cat > /root/reset-otp-to-production.sh <<'EOF'
#!/bin/bash
ipa otpconfig-mod \
  --totp-auth-window=300 \
  --totp-sync-window=86400 \
  --hotp-auth-window=10 \
  --hotp-sync-window=100
echo "OTP configuration reset to production defaults"
EOF

chmod +x /root/reset-otp-to-production.sh

Result: Development environment configured with permissive OTP settings for testing convenience. Clear warnings prevent accidental production use.

8. Monitoring OTP Authentication Patterns

Administrator proactively monitors OTP authentication to detect issues before users report problems.

# Create monitoring script for OTP authentication patterns
cat > /root/monitor-otp-auth.sh <<'EOF'
#!/bin/bash

# Analyze last 24 hours of OTP authentication
LOG_FILE="/var/log/krb5kdc.log"

echo "OTP Authentication Analysis - Last 24 Hours"
echo "==========================================="

# Count successful OTP authentications
SUCCESS=$(grep -c "OTP.*success" "$LOG_FILE")
echo "Successful OTP authentications: $SUCCESS"

# Count failed OTP authentications
FAILED=$(grep -c "OTP.*fail" "$LOG_FILE")
echo "Failed OTP authentications: $FAILED"

# Calculate failure rate
if [ $((SUCCESS + FAILED)) -gt 0 ]; then
  FAILURE_RATE=$(awk "BEGIN {printf \"%.2f\", ($FAILED / ($SUCCESS + $FAILED)) * 100}")
  echo "Failure rate: ${FAILURE_RATE}%"

  # Alert if failure rate exceeds threshold
  if (( $(echo "$FAILURE_RATE > 10.0" | bc -l) )); then
    echo "WARNING: OTP failure rate exceeds 10% threshold!"
    echo "Investigate time synchronization or consider widening auth window"
  fi
fi

# Check for synchronization events (clock drift corrections)
SYNC_EVENTS=$(grep -c "OTP.*synchronization" "$LOG_FILE")
echo "Synchronization events: $SYNC_EVENTS"

if [ "$SYNC_EVENTS" -gt 100 ]; then
  echo "WARNING: High number of sync events suggests systemic clock issues"
fi

# Show current OTP configuration
echo ""
echo "Current OTP Configuration:"
ipa otpconfig-show
EOF

chmod +x /root/monitor-otp-auth.sh

# Run monitoring script
/root/monitor-otp-auth.sh

# Schedule daily monitoring
echo "0 9 * * * /root/monitor-otp-auth.sh | mail -s 'Daily OTP Authentication Report' admin@example.com" | crontab -

Result: Proactive monitoring detects OTP authentication issues before widespread user impact. Data-driven decisions for window adjustments.

9. Coordinating OTP Configuration with NTP Deployment

Organization deploying NTP infrastructure can tighten OTP windows after time synchronization improves.

# Before NTP deployment - current state
ipa otpconfig-show
# TOTP authentication time variance: 600 (permissive due to poor time sync)

# Monitor current clock skew across infrastructure
for server in ipa01 ipa02 ipa03; do
  echo "$server: $(ssh $server date)"
done
# Shows 2-4 minute variance between servers

# Deploy NTP configuration
# Configure all IPA servers and clients to sync from reliable NTP

# Wait 1 week for NTP to stabilize
# Monitor clock synchronization
for server in ipa01 ipa02 ipa03; do
  ssh $server "ntpq -p | head -5"
done
# All servers now synchronized within <1 second

# With improved time sync, tighten TOTP authentication window
ipa otpconfig-mod --totp-auth-window=180
# TOTP authentication time variance: 180 (3 minutes)

# Monitor authentication failure rates
# If failures don't increase, time sync improvement successful

# Update documentation
echo "NTP deployment complete. OTP auth window tightened from 600s to 180s based on improved time synchronization." >> /root/infrastructure-changes.log

Result: Infrastructure improvement (NTP) enables tighter OTP security posture. Gradual approach prevents disruption.

10. Troubleshooting Cross-Replica OTP Behavior Differences

Users authenticating to different IPA replicas experience different OTP authentication behavior.

# Users report: OTP works against ipa01, fails against ipa02

# Check OTP configuration on both replicas
ssh ipa01 "ipa otpconfig-show"
# TOTP authentication time variance: 300

ssh ipa02 "ipa otpconfig-show"
# TOTP authentication time variance: 300
# Same configuration - not a config sync issue

# Check server clocks
ssh ipa01 date
# Wed May 12 14:30:15 UTC 2026

ssh ipa02 date
# Wed May 12 14:27:45 UTC 2026

# ipa02 clock is 2.5 minutes slow!
# TOTP validation depends on accurate server time

# Fix ipa02 time synchronization
ssh ipa02 "systemctl restart chronyd && chronyc makestep"

# Verify time now synchronized
ssh ipa02 date
# Wed May 12 14:30:22 UTC 2026
# Now within ~7 seconds of ipa01

# Test OTP authentication against ipa02 - now works

# Implement monitoring for server time drift
# Alert if any IPA server drifts >30 seconds from authoritative time

Result: Cross-replica OTP behavior differences resolved by fixing server clock synchronization. OTP configuration was correct; server time was wrong.

Troubleshooting

TOTP Authentication Fails Despite Correct Code

Symptoms: User enters correct TOTP code (verified by comparing with multiple authenticator apps), but authentication fails with “Invalid OTP” error.

Diagnosis:

# Check current OTP configuration
ipa otpconfig-show
# TOTP authentication time variance: 300

# Check server clock
date
# Time appears correct

# Check time synchronization status
chronyc tracking
# System time may be offset from NTP

# Check KDC logs for specific failure reason
journalctl -u krb5kdc | grep OTP | tail -20
# May show "OTP expired" or "OTP not yet valid"

# Test time offset calculation
# If code should be valid at 14:30:00 but server thinks it's 14:35:00
# 5-minute offset exceeds half of 300s window (±150s)

Resolution: Most common cause is clock skew exceeding half the authentication window. Verify server time is accurate: chronyc sources. If server time is wrong, fix NTP configuration and restart chronyd. If server time is correct but user device is wrong, educate user to enable automatic time sync on device. Temporarily widen auth window if immediate access needed: ipa otpconfig-mod --totp-auth-window=600.

HOTP Token Counter Permanently Out of Sync

Symptoms: HOTP hardware token fails authentication even after multiple attempts. Synchronization not occurring.

Diagnosis:

# Check HOTP configuration
ipa otpconfig-show
# HOTP authentication skip-ahead: 10
# HOTP synchronization skip-ahead: 100

# User may have pressed token button >100 times
# Counter drift exceeds even sync window

# Check token counter status
ipa otptoken-find --user=alice --type=hotp
# Find token UUID

ipa otptoken-show <token-uuid> --all | grep counter
# ipatokenhotpcounter: 1523 (server-side counter)

# Ask user to note current code displayed on hardware token
# That code corresponds to counter value ~1650
# Drift: 1650 - 1523 = 127 (exceeds sync window of 100)

Resolution: Counter drift exceeds synchronization window. Options: (1) Temporarily widen sync window: ipa otpconfig-mod --hotp-sync-window=200, ask user to authenticate (triggers resync), then reduce window back. (2) Manually reset token counter: ipa otptoken-mod <uuid> --setattr=ipatokenhotpcounter=1650 (use estimated counter value). (3) Delete and re-add token with fresh counter. Educate user not to press hardware token button unnecessarily.

OTP Configuration Changes Not Taking Effect

Symptoms: Modified OTP configuration with otpconfig-mod, but authentication behavior unchanged.

Diagnosis:

# Verify configuration change applied
ipa otpconfig-show
# Shows new values

# Check if replication completed to all replicas
for server in ipa01 ipa02 ipa03; do
  echo "=== $server ==="
  ssh $server "ipa otpconfig-show"
done
# All servers should show same configuration

# Check which replica user is authenticating against
# User may be hitting un-replicated replica

# Check replication status
ipa-replica-manage list
# Shows replication agreements

ipa topologysuffix-verify domain
# Checks replication health

Resolution: Wait 1-2 minutes for LDAP replication to propagate changes to all replicas. Verify replication is healthy: ipa-replica-manage list-clean-ruv. If specific replica isn’t updating, check replication agreements and initiate manual sync: ipa-replica-manage force-sync --from=ipa01. After replication completes, configuration takes effect immediately for new authentication attempts (no service restart needed).

Authentication Window Too Narrow Causes Frequent Failures

Symptoms: After tightening TOTP authentication window, authentication failure rate increased from 2% to 25%.

Diagnosis:

# Check current configuration
ipa otpconfig-show
# TOTP authentication time variance: 120 (2 minutes)
# Very narrow window

# Review failure logs
journalctl -u krb5kdc | grep "OTP.*fail" | tail -50
# Many failures with "expired" or "not yet valid"

# Check time synchronization quality across infrastructure
for server in ipa01 ipa02 ipa03; do
  ssh $server "chronyc tracking | grep offset"
done
# Shows several servers with 90-120 second offsets

# Window too narrow for current time sync quality

Resolution: Narrow window (120s = ±60s) requires excellent time synchronization. With 90-120s server offsets, codes frequently outside window. Options: (1) Improve time synchronization infrastructure first, then re-attempt narrow window. (2) Widen window to accommodate current sync quality: ipa otpconfig-mod --totp-auth-window=300. Balance security requirements with infrastructure reality. For high-security with imperfect time sync, consider hardware security keys (PKINIT) instead of TOTP.

Synchronization Window Not Wide Enough for Initial Setup

Symptoms: New users enrolling OTP tokens fail initial authentication even with correct codes. Synchronization fails.

Diagnosis:

# Check sync window
ipa otpconfig-show
# TOTP synchronization time variance: 3600 (1 hour)

# User enrolled token on device with severely wrong clock
# Device clock shows 2026-05-10 (2 days in past)
# Actual date: 2026-05-12

# Time offset: 48 hours (172,800 seconds)
# Exceeds 1-hour sync window

# Check KDC logs
journalctl -u krb5kdc | grep "OTP.*sync.*fail"
# "Synchronization failed: code not found in window"

Resolution: Initial token enrollment on devices with severely misconfigured clocks requires wider sync window. Temporarily widen: ipa otpconfig-mod --totp-sync-window=172800 (48 hours). Have user attempt authentication again—synchronization succeeds. After initial sync completes, future authentications use learned offset. After 24-48 hours (most users enrolled), return to narrower sync window: ipa otpconfig-mod --totp-sync-window=86400. Educate users to enable automatic time sync before enrolling tokens.

Permission Denied Modifying OTP Configuration

Symptoms: User receives “Insufficient access” error when attempting to modify OTP configuration.

Diagnosis:

# Attempt to modify configuration
ipa otpconfig-mod --totp-auth-window=600
# ipa: ERROR: Insufficient access: Insufficient 'write' privilege

# Check user's group membership
ipa user-show currentuser | grep memberof
# Member of groups: ipausers (not admins)

# Check OTP configuration permissions
ipa permission-find --name="*otp*config*"
# Permissions require admin privileges

Resolution: OTP configuration modification requires administrative privileges. Add user to admins group: ipa group-add-member admins --users=user. Alternatively, create custom role with OTP configuration permissions and assign to user. OTP config management cannot be delegated separately from general admin access in default IPA RBAC.

HOTP Synchronization Window Set to Zero

Symptoms: HOTP tokens fail to authenticate if counter drifts even slightly.

Diagnosis:

# Check HOTP configuration
ipa otpconfig-show
# HOTP authentication skip-ahead: 10
# HOTP synchronization skip-ahead: 0 (misconfigured!)

# Synchronization disabled
# If auth window fails, no recovery possible

# Check how configuration became 0
ipa-audit | grep otpconfig-mod
# Modified with --hotp-sync-window=0 (mistake)

Resolution: Synchronization window of 0 disables HOTP counter resynchronization. Restore to reasonable value: ipa otpconfig-mod --hotp-sync-window=100. Test HOTP authentication with intentional counter drift to verify synchronization works. Zero sync window may have been set accidentally or due to misunderstanding of parameter meaning. Document correct parameter ranges to prevent recurrence.

OTP Authentication Slow After Window Widening

Symptoms: After widening TOTP authentication window to 1800s (30 minutes), OTP authentication takes 5-10 seconds instead of <1 second.

Diagnosis:

# Check current window
ipa otpconfig-show
# TOTP authentication time variance: 1800

# With 30-second TOTP intervals, 1800s window = 60 time slots to check
# IPA must generate and compare 60 potential codes per authentication

# Review KDC logs with timing
journalctl -u krb5kdc | grep "OTP.*duration"
# Shows 8-12 second authentication times

# Wide window creates computational overhead

Resolution: Extremely wide windows require checking many time slots, increasing validation time. Each 30s interval in window requires code generation and comparison. Reduce window to reasonable value: ipa otpconfig-mod --totp-auth-window=600 (20 time slots). Balance security, usability, and performance. For environments requiring very wide windows due to poor time sync, consider improving time infrastructure instead.

Different OTP Behavior Between Kinit and Web UI

Symptoms: OTP authentication succeeds via kinit but fails via IPA Web UI, or vice versa.

Diagnosis:

# Both use same OTP configuration
ipa otpconfig-show
# Configuration is global

# Check if different servers being accessed
# Web UI:
curl -I https://ipa.example.com/ipa/ui
# Resolves to ipa01.example.com

# Kinit:
klist -v | grep "KDC"
# Using ipa02.example.com

# Check if server clocks differ
ssh ipa01 date
ssh ipa02 date
# Clock skew between servers causes different TOTP validation results

Resolution: Different TOTP behavior between authentication methods usually indicates server clock differences. Synchronize clocks across all IPA replicas. OTP configuration is identical across all authentication methods (kinit, Web UI, SSH). If behavior truly differs with same server and same time, check for application-level issues (browser caching old OTP codes, kinit caching credentials).

Unable to Set OTP Window to Desired Value

Symptoms: Attempting to set very large or very small OTP window values fails or gets rejected.

Diagnosis:

# Attempt to set very small window
ipa otpconfig-mod --totp-auth-window=5
# May succeed but create usability issues

# Attempt to set negative or zero window
ipa otpconfig-mod --totp-auth-window=0
# ipa: ERROR: Invalid value (must be positive)

# Attempt to set extremely large window
ipa otpconfig-mod --totp-auth-window=999999999
# May succeed but degrades security significantly

Resolution: OTP window parameters must be positive integers. IPA validates basic parameter constraints but doesn’t enforce sensible ranges. Recommended ranges: TOTP auth window 180-600s, TOTP sync window 3600-172800s, HOTP auth window 5-20, HOTP sync window 50-200. Setting values far outside these ranges indicates misconfiguration or misunderstanding of parameter meaning. Review OTP window concepts before configuring extreme values.

OTP Configuration Shows Different Values Than Expected

Symptoms: otpconfig-show displays different values than what was recently configured with otpconfig-mod.

Diagnosis:

# Set new configuration
ipa otpconfig-mod --totp-auth-window=600
# Command succeeds

# Immediately check configuration
ipa otpconfig-show
# TOTP authentication time variance: 300 (old value)

# Check if modification actually applied
ipa otpconfig-show --all --raw
# Shows LDAP attributes directly

# Check for replication delays
# May be reading from different replica than modified

Resolution: If changes aren’t reflected immediately, check replication status. In multi-master environments, otpconfig-mod modifies one server; reads may come from un-replicated replica. Wait 30-60 seconds for replication. Force specific server for read: ipa -s ipa01.example.com otpconfig-show. If values revert unexpectedly, check for conflicting automation or scripts modifying OTP config.

TOTP Codes Valid for Wrong Duration

Symptoms: TOTP codes appear to remain valid longer than authentication window suggests.

Diagnosis:

# Check authentication window
ipa otpconfig-show
# TOTP authentication time variance: 300 (5 minutes)

# User generates code, waits 6 minutes, code still works

# This is expected behavior due to ±window
# 300s window = ±150s from current time
# Total validity = token interval + window

# For 30s TOTP tokens with 300s window:
# Code valid for up to 30s + 300s = 330s (5.5 minutes)

# Not a configuration issue - misunderstanding of window semantics

Resolution: Authentication window is ±half the configured value around the current time, not total code validity. For 30-second TOTP tokens with 300s window: code remains valid for its 30s generation period plus ±150s (total ~330s maximum). This is expected behavior. To reduce actual code validity, reduce auth window: ipa otpconfig-mod --totp-auth-window=180 (3 min window = ~210s max validity).

OTP Synchronization Events Occurring Too Frequently

Symptoms: KDC logs show hundreds of OTP synchronization events daily, indicating systemic issues.

Diagnosis:

# Review synchronization event frequency
journalctl -u krb5kdc | grep "OTP synchronization" | wc -l
# 450 events in last 24 hours

# Check which users/tokens experiencing frequent sync
journalctl -u krb5kdc | grep "OTP synchronization" | \
  awk '{print $NF}' | sort | uniq -c | sort -rn | head
# Shows specific users with recurring sync events

# Indicates device clocks constantly drifting
# Or users repeatedly re-enrolling tokens

Resolution: Frequent synchronization indicates poor time synchronization infrastructure. Investigate common factors among affected users: specific device types, mobile carriers, geographic regions. Enable automatic time sync on user devices. For devices that cannot maintain accurate time (offline frequently), consider switching to HOTP (counter-based) instead of TOTP (time-based). Document users requiring special handling.

Audit Compliance Requires Shorter OTP Window

Symptoms: Security audit requires OTP codes valid for maximum 90 seconds (1.5 minutes) for compliance, but current window is 300s.

Diagnosis:

# Current configuration
ipa otpconfig-show
# TOTP authentication time variance: 300

# Audit requirement: 90-second validity
# 90s window = ±45s around current time

# For 30s TOTP tokens: 30s + 90s window = 120s max validity
# Still exceeds 90s requirement

# Need 60s window for 90s max validity with 30s tokens
# 30s (token interval) + 60s (±30s window) = 90s

Resolution: Configure very narrow window to meet compliance: ipa otpconfig-mod --totp-auth-window=60. This requires excellent time synchronization (±30 seconds tolerance). Test thoroughly before production deployment. If time sync quality insufficient for 60s window, consider: (1) Improving NTP infrastructure first, or (2) Using hardware security keys (PKINIT) or external IdP with compliant MFA instead of TOTP. Document compliance requirement and implementation approach.

Commands

otpconfig-mod

Usage: ipa [global-options] otpconfig-mod [options]

Modify OTP configuration options.

Options

Option	Description
`--totp-auth-window TOTP-AUTH-WINDOW`	TOTP authentication time variance (seconds)
`--totp-sync-window TOTP-SYNC-WINDOW`	TOTP synchronization time variance (seconds)
`--hotp-auth-window HOTP-AUTH-WINDOW`	HOTP authentication skip-ahead
`--hotp-sync-window HOTP-SYNC-WINDOW`	HOTP synchronization skip-ahead
`--setattr SETATTR`	Set an attribute to a name/value pair. Format is attr=value.
`--addattr ADDATTR`	Add an attribute/value pair. Format is attr=value. The attribute
`--delattr DELATTR`	Delete an attribute/value pair. The option will be evaluated
`--rights`	Display the access rights of this entry (requires —all). See ipa man page for details.
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.

otpconfig-show

Usage: ipa [global-options] otpconfig-show [options]

Show the current OTP configuration.

Options

Option	Description
`--rights`	Display the access rights of this entry (requires —all). See ipa man page for details.
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.