Clock Synchronization

Why Clock Synchronization Matters

SAML assertions may contain time-related attributes or conditions such as:

If participating systems have substantially different clocks, otherwise legitimate authentication requests or assertions may fail validation.

Running the Clock Check

1. Open ShibbDebugger.
2. Select Check For Client Clock Skew.
3. Leave the URL and file fields empty.
4. Click Execute Command.
5. Review the synchronization report.

No XML file is required.

What the Tool Measures

Despite the name "Client Clock Skew," the supplied implementation measures the ShibbDebugger application server's clock, not the clock of the user's browser or computer.

The command retrieves the server's current UTC time and compares it with two external services.

External Time Sources

NTP Check

The tool requests time from:

time.google.com

using NTP version 3.

It compares the returned timestamp with the application server's UTC clock.

HTTP Check

The tool also requests:

https://timeapi.io/api/Time/current/zone?timeZone=UTC

It parses the returned UTC timestamp and compares it with the server's clock.

Clock Skew Calculation

The reported skew is the absolute difference between two timestamps.

Conceptually:

Clock Skew = |Server UTC Time - Reference UTC Time|

The result is expressed in seconds.

Classification Threshold

The five-second threshold is the diagnostic threshold implemented by ShibbDebugger.

It is not a universal SAML federation requirement.

Different systems and federation policies can permit different clock tolerances.

Example Output

Result of: CheckClockSkewCommand

NTP Source: time.google.com
System UTC Time: 2026-10-16 18:30:00
NTP UTC Time:    2026-10-16 18:30:01
NTP Skew:        1.00 seconds — ✓ Synchronized

A second section reports the HTTP time comparison if successful.

The timestamps above are illustrative.

Understanding Results

Synchronized

The detected absolute difference is below the tool's five-second threshold.

Skew Detected

The detected absolute difference is five seconds or greater.

The server clock may require investigation.

NTP Check Failed

The application could not obtain or process a response from the NTP service.

Possible causes include blocked UDP traffic, network restrictions, or service errors.

HTTP Check Failed

The HTTP time service was unavailable or returned an unexpected response.

The tool's HTTP parser expects a particular timestamp representation, so changes in the provider's response format can also cause failures.

Important Measurement Limitations

This Is a Server-Side Check

The result describes the server hosting ShibbDebugger.

It does not directly measure:

• Your browser's clock
• Your workstation clock
• Your Identity Provider's clock
• Your Service Provider's clock

Network Delay

Network latency and timing of individual requests may affect the reported differences.

The implementation does not perform a comprehensive clock synchronization measurement with latency compensation.

External Service Availability

Either reference service can fail independently.

A failed reference request does not automatically mean the server clock is incorrect.

Troubleshooting SAML Time Errors

If you suspect SAML time synchronization problems:

1. Check time synchronization on the actual Identity Provider.
2. Check time synchronization on the actual Service Provider.
3. Confirm both systems use reliable time sources.
4. Inspect assertion validity conditions.
5. Check application logs for time-related rejection messages.
6. Compare clock skew tolerance settings.
7. Retest the authentication flow.

Common Symptoms

Time synchronization problems may contribute to messages involving:

• Assertions not yet valid
• Expired assertions
• Message timestamps outside acceptable windows
• Authentication failures involving issue or validity times

These errors can also occur for reasons unrelated to incorrect system clocks.

Recommended Practices

Use a reliable NTP or equivalent time synchronization service on all federation participants.

Monitor the actual systems participating in authentication, not only an external diagnostic server.

Important: ShibbDebugger's Clock Skew diagnostic checks its own hosting server against external time sources. It is not a remote time synchronization test of an arbitrary Shibboleth deployment.