Teleport

SSH Authentication with OneLogin

Enterprise
Cloud

This guide will explain how to configure OneLogin to issue SSH credentials to specific groups of users. When used in combination with role based access control (RBAC) it allows SSH administrators to define policies like:

Only members of "DBA" group can SSH into machines running PostgreSQL.
Developers must never SSH into production servers.
... and many others.

Prerequisites

One Login account with admin access and users assigned to at least two groups.
Teleport role with access to maintaining saml resources. This is available in the default editor role.

A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.
The tctl admin tool and tsh client tool version >= 10.1.2, which you can download by visiting the customer portal.
```
tctl version
Teleport v10.1.2 go1.18
tsh version
Teleport v10.1.2 go1.18
```

A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.
The tctl admin tool and tsh client tool version >= 9.3.10. To download these tools, visit the Downloads page.
```
tctl version
Teleport v9.3.10 go1.18
tsh version
Teleport v9.3.10 go1.18
```

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=teleport.example.com [email protected]
tctl status
Cluster  teleport.example.com
Version  10.1.2
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 status
Cluster  myinstance.teleport.sh
Version  9.3.10
CA pin   sha256:sha-hash-here

You must run subsequent tctl commands in this guide on your local machine.

Enable default SAML authentication

Configure Teleport to use SAML 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: saml

Create a file called cap.yaml:

kind: cluster_auth_preference
metadata:
  name: cluster-auth-preference
spec:
  authentication:
    type: saml
version: v2

Create a resource:

tctl create -f cap.yaml

Configure Application

Using OneLogin control panel, create a SAML 2.0 Web App in SAML configuration section:

Download Icons

Important

Make sure to pick SAML Test Connector (SP) and not SAML Test Connector (IdP), because teleport only supports SP - service provider initiated SAML flows.

Set Audience, Recipient and ACS (Consumer) URL Validator to the same value:

https://teleport.example.com:3080/v1/webapi/saml/acs where teleport.example.com is the public name of the teleport web proxy service:

Teleport needs to assign groups to users. Configure the application with some parameters exposed as SAML attribute statements:

Important

Make sure to check Include in SAML assertion checkbox.

Add users to the application:

Download SAML XML Metadata

Once the application is set up, download SAML Metadata.

Create a SAML Connector

Now, create a SAML connector resource. Write down this template as onelogin-connector.yaml:

kind: saml
version: v2
metadata:
  name: OneLogin
spec:
  acs: https://<cluster-url>/v1/webapi/saml/acs
  attributes_to_roles:
    - {name: "groups", value: "admin", roles: ["editor"]}
    - {name: "groups", value: "dev", roles: ["access"]}
  display: OneLogin
  issuer: https://app.onelogin.com/saml/metadata/123456
  sso: https://mycompany.onelogin.com/trust/saml2/http-redirect/sso/123456
  entity_descriptor: |
    # Paste in downloaded content from OneLogin Dashboard.
    <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://www.example.com/00000000000000000000">
      <md:IDPSSODescriptor WantAuthnRequestsSigned="false"

To fill in the fields, open SSO tab:

acs - is the name of the teleport web proxy, e.g. https://teleport.example.com/v1/webapi/saml/acs
issuer - use value from Issuer URL field, e.g. https://app.onelogin.com/saml/metadata/123456
sso - use the value from the value from field SAML 2.0 Endpoint (HTTP) but replace http-post with http-redirect, e.g. https://mycompany.onelogin.com/trust/saml2/http-redirect/sso/123456

Important

Make sure to replace http-post with http-redirect.

cert - download certificate, by clicking "view details link" and add to cert section

Create the connector using tctl tool:

tctl create onelogin-connector.yaml

Create a new Teleport Role

We are going to create a new that'll use external username data from OneLogin to map to a host linux login.

In the below role, Devs are only allowed to login to nodes labelled with access: relaxed Teleport label. Developers can log in as either ubuntu to a username that arrives in their assertions. Developers also do not have any rules needed to obtain admin access to Teleport.

kind: role
version: v5
metadata:
  name: dev
spec:
  options:
    max_session_ttl: "24h"
  allow:
    logins: [ "{{external.username}}", ubuntu ]
    node_labels:
      access: relaxed

Notice: Replace ubuntu with linux login available on your servers!

tctl create dev.yaml

Testing

The Web UI will now contain a new button: "Login with OneLogin". The CLI is the same as before:

tsh --proxy=proxy.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 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 SAML 2.0. 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.
None of the user's roles contain a deny rule that matches the user's login.
At least one of the user's roles contains an allow rule that matches the Node's labels.
At least one of the user's roles contains an allow rule that matches the user's login.

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

Have a suggestion or can’t find something?

IMPROVE THE DOCS