Choosing an Authentication Method for Teleport: Local, OIDC, or SAML

Decision: pick an authentication backend for Teleport

Choose between Teleport’s local user database, an OIDC identity provider (e.g., GitHub, Google, Azure AD), or a SAML IdP (e.g., Okta, JumpCloud) based on security needs, operational overhead, and compliance constraints.

Constraints

• Security: require MFA and centralized user lifecycle.
• Operational overhead: prefer minimal IdP configuration and easy recovery.
• Compliance: may need audit‑ready SSO and role mapping.

Comparison of supported options

Option	Setup complexity	Centralized MFA	User lifecycle	IdP dependency	Minimum Teleport version
Local user database	Low (static file or tctl)	No (MFA must be added per user)	Manual	None	All
OIDC (GitHub, Google, Azure AD)	Medium (register app, set redirect URI)	Yes (via IdP)	Automatic (just‑in‑time provisioning)	Required	4.0
SAML (Okta, JumpCloud)	Higher (XML metadata, attribute mapping)	Yes (via IdP)	Automatic (just‑in‑time)	Required	4.3

Trade‑offs

Local authentication is simplest to deploy but lacks built‑in MFA and centralized user management, making it unsuitable for teams that require audit‑ready SSO. OIDC adds token‑based authentication and pushes MFA responsibility to the IdP, reducing operational effort while still requiring a correctly configured client secret and redirect URI. SAML provides the strongest enterprise SSO guarantees but introduces XML parsing complexity and may need extra attribute mapping to align with Teleport roles.

Concrete implementation: OIDC with GitHub

The following steps illustrate how to enable GitHub OIDC on a Teleport node. Replace placeholders with your own values.

1. Create a GitHub OAuth app – set the Authorization callback URL to https://<teleport‑host>:3080/v1/webapi/oidc/callback. Note the Client ID and Client Secret.
2. Edit Teleport configuration (/etc/teleport.yaml) – add an auth_service section:

auth_service:
  authentication:
    type: oidc
    oidc:
      - name: github
        issuer_url: "https://github.com"
        client_id: "<YOUR_CLIENT_ID>"
        client_secret: "<YOUR_CLIENT_SECRET>"
        redirect_url: "https://<teleport‑host>:3080/v1/webapi/oidc/callback"
        scopes: ["openid", "email", "profile"]
        # optional: map GitHub teams to Teleport roles
        # role_mapping:
        #   - github_organization: "my-org"
        #     github_team: "developers"
        #     teleport_role: "editor"

1. Restart the Teleport service (requires root or teleport user):

sudo systemctl restart teleport

1. Verify the connector is loaded – check the logs for the initialization message:

journalctl -u teleport -f | grep "auth: OIDC connector 'github' initialized"

1. Check the connector definition via tctl:

tctl get auth-connector --name=github

1. Log in using tsh (run from a workstation with tsh installed):

tsh login --auth=github --proxy=<teleport‑host>:3080

After a successful GitHub OAuth flow, Teleport issues a short‑lived certificate. You can verify that a Teleport user object was created and that roles are mapped:

1. Inspect the Teleport user record:

tctl get users --username=<YOUR_GITHUB_LOGIN>

If the user appears with the expected roles, the OIDC integration is working.

Limitations and recovery

• OIDC support requires Teleport ≥ 4.0; SAML requires ≥ 4.3. Older versions will not recognize the oidc or saml blocks.
• Misconfigured redirect URLs or invalid client secrets can lock out administrators. Always keep a break‑glass local user with the admin role (created via tctl users add) and store its credentials offline.
• Role mapping relies on correct IdP claims; test with a non‑privileged GitHub account before granting admin access.

Practical verification checklist

1. Teleport logs show auth: OIDC connector 'github' initialized after restart.
2. tctl get auth-connector --name=github returns the connector with correct client ID and redirect URI.
3. tsh login --auth=github completes the OAuth flow and returns a short‑lived certificate (check with tctl status).
4. tctl get users --username=<github‑login> displays the user and the roles you mapped.