Documentation Index
Fetch the complete documentation index at: https://mintlify.com/gravitational/teleport/llms.txt
Use this file to discover all available pages before exploring further.
Teleport supports single sign-on (SSO) so your team can authenticate to infrastructure using the same identity provider they use for every other application. When a user signs in through your IdP, Teleport issues short-lived SSH and TLS certificates scoped to the roles mapped from that user’s IdP groups — no long-lived credentials, no separate Teleport password required.
Supported connectors
Teleport supports three connector types:
| Connector | Supported providers |
|---|
| GitHub | GitHub Cloud, GitHub Enterprise Server |
| OIDC | Google Workspace, Okta, Keycloak, GitLab, Ping Federate, and any OpenID Connect–compliant IdP |
| SAML | Okta, Microsoft Entra ID (Azure AD), ADFS, OneLogin, and any SAML 2.0–compliant IdP |
GitHub connectors are available in all Teleport editions. OIDC and SAML connectors require Teleport Enterprise or Teleport Enterprise Cloud.
How SSO works in Teleport
When a user runs tsh login --proxy=example.teleport.sh, Teleport opens a browser and redirects to your IdP. After the IdP authenticates the user, it sends back a response (OAuth token, OIDC ID token, or SAML assertion) to Teleport’s callback URL. Teleport then:
- Reads the user’s group membership or claims from the IdP response.
- Applies the role mapping defined in your connector to determine which Teleport roles to assign.
- Issues short-lived certificates embedding those roles and creates a temporary
user resource (expires in up to 30 hours).
Step 1: Create a GitHub OAuth app
In your GitHub organization, create an OAuth App with the following callback URL:https://<proxy-address>/v1/webapi/github/callback
read:org scope so Teleport can read team membership.Step 2: Create the connector resource
Save the following as github.yaml, replacing placeholder values with your OAuth app credentials and organization details:kind: github
version: v3
metadata:
name: github
spec:
client_id: <github-oauth-client-id>
client_secret: <github-oauth-client-secret>
display: GitHub
redirect_url: https://<proxy-address>/v1/webapi/github/callback
teams_to_roles:
- organization: my-org
team: admins
roles:
- editor
- auditor
- organization: my-org
team: engineers
roles:
- access
- organization: my-org
team: contractors
roles:
- contractor
Step 3: Apply and activate
$ tctl create github.yaml
# Set GitHub as the default connector
$ tctl edit cap
cluster_auth_preference resource, set:Step 4: Test the login
$ tsh login --proxy=example.teleport.sh --auth=github
Step 1: Register Teleport with your OIDC provider
Register a new application in your IdP (Okta, Google, Keycloak, etc.) and collect the client_id and client_secret. Set the redirect URI to:https://<proxy-address>/v1/webapi/oidc/callback
Step 2: Create the connector resource
The following example configures an OIDC connector for Okta. The claims_to_roles block maps an OIDC claim called groups to Teleport roles.kind: oidc
version: v3
metadata:
name: okta-oidc
spec:
issuer_url: https://dev-123456.okta.com
client_id: <client-id>
client_secret: <client-secret>
redirect_url: https://example.teleport.sh/v1/webapi/oidc/callback
display: Okta
scope:
- groups
claims_to_roles:
- claim: groups
value: admins
roles:
- editor
- auditor
- claim: groups
value: devs
roles:
- access
Step 3: Apply and activate
$ tctl create okta-oidc.yaml
# Set OIDC as the default connector
$ tctl edit cap
cluster_auth_preference resource, set:Step 4: Test the connector before applying
$ cat okta-oidc.yaml | tctl sso test
Register Teleport as a SAML service provider. Use the following URLs:
- SSO URL / ACS URL:
https://<proxy-address>/v1/webapi/saml/acs/<connector-name>
- Audience URI (SP Entity ID):
https://<proxy-address>/v1/webapi/saml/acs/<connector-name>
Configure the IdP to include a groups attribute statement containing the user’s group memberships.Step 2: Create the connector resource
The following example configures a SAML connector for Okta using its metadata URL:kind: saml
version: v2
metadata:
name: okta
spec:
display: Okta
entity_descriptor_url: https://dev-123456.okta.com/app/abc123/sso/saml/metadata
acs: https://example.teleport.sh/v1/webapi/saml/acs/okta
attributes_to_roles:
- name: groups
value: admins
roles:
- editor
- auditor
- name: groups
value: devs
roles:
- access
Step 3: Apply and activate
$ tctl create okta-saml.yaml
# Set SAML as the default connector
$ tctl edit cap
cluster_auth_preference resource, set:Step 4: Test before applying to live traffic
$ cat okta-saml.yaml | tctl sso test
Role mapping
Role mapping is the heart of Teleport SSO integration. It translates identity data from your IdP (team membership, group claims, or SAML attributes) into Teleport roles.
For GitHub connectors, mappings are defined with teams_to_roles:
teams_to_roles:
- organization: my-org
team: platform-team
roles:
- access
- db-admin
claims_to_roles:
claims_to_roles:
- claim: groups
value: platform-team
roles:
- access
- db-admin
attributes_to_roles:
attributes_to_roles:
- name: groups
value: platform-team
roles:
- access
- db-admin
claims_to_roles:
- claim: groups
value: '*'
roles:
- access
Setting the default connector
If you have only one SSO connector, set it as the cluster default so users don’t need to pass --auth:
kind: cluster_auth_preference
version: v2
metadata:
name: cluster-auth-preference
spec:
type: github # or: oidc, saml
$ tsh login --proxy=example.teleport.sh
Working with multiple providers
If you have several connectors, users specify which one to use at login time:
# Use the Okta SAML connector
$ tsh login --proxy=example.teleport.sh --auth=okta
# Use local Teleport accounts
$ tsh login --proxy=example.teleport.sh --auth=local --user=admin
$ tctl get connectors
$ tctl rm github/github
Next steps
RBAC
Define Teleport roles and label-based access policies.
MFA
Require MFA at login or per session, even for SSO users.
Access Requests
Let users request temporary elevated privileges with approval.
Device Trust
Enforce that only registered devices can authenticate.
