
How to use GitLab as a single sign-on (SSO) provider with Teleport
This guide will cover how to configure GitLab to issue SSH credentials to specific groups of users. When used in combination with role based access control (RBAC), it allows administrators to define policies like:
- Only members of "DBA" group can SSH into machines running PostgreSQL.
- Only members of "ProductionKubernetes" can access production Kubernetes clusters
- Developers must never SSH into production servers.
Prerequisites
- At least two groups in GitLab with users assigned.
- Teleport role with access to maintaining
oidc
resources. This is available in the defaulteditor
role.
-
A running Teleport cluster, including the Auth Service and Proxy Service. For details on how to set this up, see our Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 12.1.1, which you can download by visiting the customer portal.tctl versionTeleport Enterprise v12.1.1 go1.19
tsh versionTeleport v12.1.1 go1.19
Please use the latest version of Teleport Enterprise documentation.
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=teleport.example.com [email protected]tctl statusCluster teleport.example.com
Version 12.1.1
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
You can run subsequent tctl
commands in this guide on your local machine.
For full privileges, you can also run tctl
commands on your Auth Service host.
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=myinstance.teleport.sh [email protected]tctl statusCluster myinstance.teleport.sh
Version 12.1.1
CA pin sha256:sha-hash-here
You must run subsequent tctl
commands in this guide on your local machine.
Enable default OIDC authentication
Configure Teleport to use OIDC authentication as the default instead of the local user database.
You can either edit your Teleport configuration file or create a dynamic resource.
Update /etc/teleport.yaml
in the auth_service
section and restart the teleport
daemon.
auth_service:
authentication:
type: oidc
Please use the latest version of Teleport Enterprise documentation.
Configure GitLab
You should have at least one group configured in GitLab to map to Teleport roles. In this example we use the names gitlab-dev
and gitlab-admin
. Assign users to each of these groups.
- Create a Application in one of your Groups that will allow using GitLab as a OAuth provider to Teleport.
Settings
- Redirect URL
https://<proxy url>/v1/webapi/oidc/callback
such ashttps://teleport.example.com:3080/v1/webapi/oidc/callback
- Check
Confidential
,openid
,profile
, andemail
.

- Collect the
Application ID
andSecret
in the Application
These will be used in the Teleport OIDC Auth Connector.

- Confirm the GitLab Issuer Address
For GitLab cloud that is https://gitlab.com
. That allows accessing the Open-ID configuration at https://gitlab.com/.well-known/openid-configuration
.
If you are self hosting that is likely another local address.
Configure Teleport
Create a OIDC Connector
Create a OIDC connector resource: Replace the Application ID and the Secret with the values from GitLab.
kind: oidc
metadata:
name: gitlab
spec:
claims_to_roles:
- claim: groups
roles:
- admin
value: gitlab-admin
- claim: groups
roles:
- dev
value: gitlab-dev
client_id: Application_ID
client_secret: Secret
display: GitLab
issuer_url: https://gitlab.com
prompt: "none"
redirect_url: https://teleport.example.com:3080/v1/webapi/oidc/callback
scope:
- email
version: v2
The prompt
value must be none
. Setting to none
means Teleport will not send this as a parameter sending the select_account
parameter will result in an error from GitLab.
Create the connector using tctl
tool:
tctl create oidc-connector.yaml
Create Teleport Roles
We are going to create 2 roles, privileged role admin who is able to login as root and is capable of administrating the cluster and non-privileged dev.
kind: role
version: v5
metadata:
name: admin
spec:
options:
max_session_ttl: 24h
allow:
logins: [root]
node_labels:
"*": "*"
rules:
- resources: ["*"]
verbs: ["*"]
The developer role:
kind: role
version: v5
metadata:
name: dev
spec:
options:
max_session_ttl: 24h
allow:
logins: [ "{{email.local(external.email)}}", ubuntu ]
node_labels:
access: relaxed
- Devs are only allowed to login to nodes labelled with
access: relaxed
label. - Developers can log in as
ubuntu
user - Notice
{{external.email}}
login. It configures Teleport to look at "email" GitLab claim and use that field as an allowed login for each user. Theemail.local(external.trait)
function will remove the@domain
and just have the username prefix. - Developers also do not have any "allow rules" i.e. they will not be able to see/replay past sessions or re-configure the Teleport cluster.
Create both roles on the auth server:
tctl create admin.yamltctl create dev.yaml
Testing
The Web UI will now contain a new button: "Login with GitLab". The CLI is the same as before:
tsh --proxy=teleport.example.com login
This command will print the SSO login URL (and will try to open it automatically in a browser).
Teleport can use multiple OIDC/SAML connectors. In this case a connector name
can be passed via tsh login --auth=connector_name
Teleport only supports sending party initiated flows for OIDC Connect. This means you can not initiate login from your identity provider, you have to initiate login from either the Teleport Web UI or CLI.
Troubleshooting
Troubleshooting SSO configuration can be challenging. Usually a Teleport administrator must be able to:
- Ensure that HTTP/TLS certificates are configured properly for both Teleport proxy and the SSO provider.
- Be able to see what SAML/OIDC claims and values are getting exported and passed by the SSO provider to Teleport.
- Be able to see how Teleport maps the received claims to role mappings as defined in the connector.
If something is not working, we recommend to:
- Double-check the host names, tokens and TCP ports in a connector definition.
Using the Web UI
If you get "access denied" or other login errors, the number one place to check is the Audit Log. You can access it in the Activity tab of the Teleport Web UI.

Example of a user being denied because the role clusteradmin
wasn't set up:
{
"code": "T1001W",
"error": "role clusteradmin is not found",
"event": "user.login",
"method": "oidc",
"success": false,
"time": "2019-06-15T19:38:07Z",
"uid": "cd9e45d0-b68c-43c3-87cf-73c4e0ec37e9"
}
Teleport does not show the expected Nodes
When Teleport's Auth Service receives a request to list Teleport Nodes (e.g., to
display Nodes in the Web UI or via tsh ls
), it only returns the Nodes that the
current user is authorized to view.
For each Node in the user's Teleport cluster, the Auth Service applies the following checks in order and, if one check fails, hides the Node from the user:
- None of the user's roles contain a
deny
rule that matches the Node's labels. - At least one of the user's roles contains an
allow
rule that matches the Node's labels.
If you are not seeing Nodes when expected, make sure that your user's roles
include the appropriate allow
and deny
rules as documented in the
Teleport Access Controls Reference.
When configuring SSO, ensure that the identity provider is populating each user's
traits correctly. For a user to see a Node in Teleport, the result of populating a
template variable in a role's allow.logins
must match at least one of a user's
traits.logins
.
In this example a user will have usernames ubuntu
, debian
and usernames from the SSO trait logins
for Nodes that have a env: dev
label. If the SSO trait username is bob
then the usernames would include ubuntu
, debian
, and bob
.
kind: role
metadata:
name: example-role
spec:
allow:
logins: ['{{external.logins}}', ubuntu, debian]
node_labels:
'env': 'dev'
version: v5