Fork me on GitHub
Teleport

Teleport SSO Authentication with GitLab

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.
Version Warning
This guide requires a commercial edition of Teleport.

Enable OIDC Authentication

First, configure Teleport auth server to use OIDC authentication instead of the local user database. Update /etc/teleport.yaml as shown below and restart the teleport daemon.

auth_service:
    authentication:
        type: oidc

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.

  1. Create a Application in one of your Groups that will allow using GitLab as a OAuh provider to Teleport.

Settings

  • Redirect URL https://<proxy url>/v1/webapi/oidc/callback such as https://teleport.example.com:3080/v1/webapi/oidc/callback
  • Check Confidential, openid, profile, and email.
Create App
  1. Collect the Application ID and Secret in the Application

These will be used in the Teleport OIDC Auth Connector.

Collection Information
  1. 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
IMPORTANT
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: v4
metadata:
  name: admin
spec:
  options:
    max_session_ttl: 24h
  allow:
    logins: [root]
    node_labels:
      "*": "*"
    rules:
      - resources: ["*"]
        verbs: ["*"]

The developer role:

kind: role
version: v4
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. The email.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.yaml
$ tctl 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).

Tip
Teleport can use multiple OIDC/SAML connectors. In this case a connector name can be passed via tsh login --auth=connector_name
IMPORTANT
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

If you get "access denied errors" the number one place to check is the events in the audit log on the Teleport auth server. The audit events log is located in /var/lib/teleport/log/events.log by default and it will contain the detailed reason why a user's login was denied.

Some errors (like filesystem permissions or misconfigured network) can be diagnosed using Teleport's stderr log, which is usually available via:

$ sudo journalctl -fu teleport

If you wish to increase the verbosity of Teleport's syslog, you can pass --debug flag to teleport start command.

Have a suggestion or can’t find something?
IMPROVE THE DOCS