Join Token Authentication Failure in Teleport Node Agent

Answer

The agent’s log output can tell you whether the failure happened before any authentication exchange (network problem) or after a successful TLS handshake (token problem).

Likely explanation

If the agent cannot reach the Auth/Proxy join endpoint, it logs connection‑level errors such as timeouts or refused connections. If the connection succeeds but the join token is invalid, expired, or lacks the Node role, the agent logs an authentication‑related gRPC error after the TLS handshake.

Confirmed facts

• Teleport Node agents join by presenting a join token to the Auth Server (directly or via the Proxy’s join service).
• Network‑level errors appear as "context deadline exceeded", "i/o timeout", "connection refused", DNS errors, or TLS handshake failures.
• Token‑related errors appear as gRPC messages like "Unauthenticated: access denied", "PermissionDenied", "bad token", or "token expired" after a successful TLS handshake.
• On the Auth Server, a rejected join attempt generates an audit event in the T3xx range (join‑failure) that records the token name, requested roles, and the rejection reason.

Steps to distinguish using agent logs

1. Enable debug logging on the agent (teleport start -d) and reproduce the join attempt.
2. Search the log for the first error that appears after the agent starts:
   • If you see messages like context deadline exceeded, i/o timeout, connection refused, or TLS handshake timeout before any line mentioning "join" or "auth", the problem is network‑level.
   • If you see a successful TLS handshake line (e.g., handshake complete) followed by an error containing Unauthenticated, PermissionDenied, bad token, or token expired, the problem is the join token.
3. If the log is ambiguous (only a reconnection loop), note the exact error string inside each retry cycle and apply the same classification above.

Auth Server audit events for a rejected join

Query the audit log around the timestamp of the agent’s attempt:

tctl get audit --event join --start  --end 

Look for entries with:

• event: join.failure (or similar T3xx code)
• Fields: token_name, requested_roles, reason (e.g., "token expired", "token does not grant node role", "invalid token").
• The presence of this event confirms the agent reached the Auth Server and the token was rejected.

Missing diagnostic detail

Are you joining the Node agent directly to the Auth Server or through the Teleport Proxy? This determines which port (3025 for direct Auth, 443/3080 via Proxy) and which log set to inspect, and it influences the network‑reachability test you should run.