juanfont/headscale · error · HTTPError

failed to verify id_token

Error message

failed to verify id_token

What it means

Error "failed to verify id_token" thrown in juanfont/headscale.

Source

Thrown at hscontrol/oidc.go:505

	return oauth2Token, nil
}

// extractIDToken extracts the ID token from the oauth2 token.
func (a *AuthProviderOIDC) extractIDToken(
	ctx context.Context,
	oauth2Token *oauth2.Token,
) (*oidc.IDToken, error) {
	rawIDToken, ok := oauth2Token.Extra("id_token").(string)
	if !ok {
		return nil, NewHTTPError(http.StatusBadRequest, "no id_token", errNoOIDCIDToken)
	}

	verifier := a.oidcProvider.Verifier(&oidc.Config{ClientID: a.cfg.ClientID})

	idToken, err := verifier.Verify(ctx, rawIDToken)
	if err != nil {
		return nil, NewHTTPError(http.StatusForbidden, "failed to verify id_token", fmt.Errorf("verifying ID token: %w", err))
	}

	return idToken, nil
}

// validateOIDCAllowedDomains checks that if AllowedDomains is provided,
// that the authenticated principal ends with @<alloweddomain>.
func validateOIDCAllowedDomains(
	allowedDomains []string,
	claims *types.OIDCClaims,
) error {
	if len(allowedDomains) > 0 {
		if at := strings.LastIndex(claims.Email, "@"); at < 0 ||
			!slices.Contains(allowedDomains, claims.Email[at+1:]) {
			return NewHTTPError(http.StatusUnauthorized, "unauthorised domain", errOIDCAllowedDomains)
		}
	}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Inspect the wrapped error for the underlying cause and correct the failing condition (failed to verify id_token); retry the operation after fixing the input, configuration, or environment.

Example fix

Inspect the wrapped error for the underlying cause and correct the failing condition (failed to verify id_token); retry the operation after fixing the input, configuration, or environment.

When it happens

Trigger: Thrown at hscontrol/oidc.go:505 when the library encounters an invalid state.

Common situations: ID token signature or claim verification failed. Check that oidc.issuer matches the provider, clock skew is small, and the provider's signing keys are reachable.

AI-assisted analysis of juanfont/headscale@565fd254d0 (2026-08-15). Data as JSON: /api/errors/37a24abf30ba69cb. Report an issue: GitHub.