SSH Authentication with Azure Active Directory (AD)

This guide will cover how to configure Microsoft Azure Active Directory to issue SSH credentials to specific groups of users with a SAML Authentication Connector. When used in combination with role based access control (RBAC) it allows SSH administrators to define policies like:

The following steps configure an example SAML authentication connector matching AzureAD groups with security roles. You can choose to configure other options.

Version Warning

This guide requires an Enterprise version of Teleport. The open source edition of Teleport only supports Github as an SSO provider.

Prerequisites:

Before you get started you’ll need:

Configure Azure AD

  1. Select Enterprise Applications from the AzureAD Directory Home Select Enterprise Applications From Manage

  2. Select New application Select New Applications From Manage

  3. Select a Non-gallery application Select Non-gallery application

  4. Enter the display name (Ex: Teleport) Enter application name

5.Select properties under Manage and turn off User assignment required Turn off user assignment

  1. Select Single Sign-on under Manage and choose SAML Select SAML

  2. Select to edit Basic SAML Configuration Edit Basic SAML Configuration

  3. Put in the Entity ID and Reply URL the same proxy url https://teleport.example.com:3080/v1/webapi/saml/acs Put in Entity ID and Reply URL

  4. Edit User Attributes & Claims

    i. Edit the Claim Name. Change the name identifier format to Default. Make sure the source attribute is user.userprincipalname. Confirm Name Identifier

    ii. Add a group Claim to have user security groups available to the connector Put in Security group claim

    iii. Add a Claim to pass the username from transforming the AzureAD User name. Add a transformed username

  5. On the SAML Signing Certificate select to download SAML Download the Federation Metadata XML.
    Download Federation Metadata XML

Important

This is a important document. Treat the Federation Metadata XML file as you would a password.

Create a SAML Connector

Now, create a SAML connector resource. Replace the acs element with your Teleport address, update the group IDs with the actual AzureAD group ID values, and insert the downloaded Federation Metadata XML into the entity_descriptor resource. Write down this template as azure-connector.yaml:

kind: saml
version: v2
metadata:
  # the name of the connector
  name: azure-saml
spec:
  display: "Microsoft"
  # acs is the Assertion Consumer Service URL. This should be the address of
  # the Teleport proxy that your identity provider will communicate with.
  acs: https://teleport.example.com:3080/v1/webapi/saml/acs
  attributes_to_roles:
    - {name: "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups", value: "<group id 930210...>", roles: ["admin"]}
    - {name: "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups", value: "<group id 93b110...>", roles: ["dev"]}
  entity_descriptor: |
    <federationmedata.xml contents>

Create the connector using tctl tool:

$ tctl create azure-connector.yaml

FYI

Teleport will automatically transform the contents of the connector when viewed from the web UI.

Sample Connector Transform

Create Teleport Roles

We are going to create 2 roles:

kind: role
version: v3
metadata:
  name: admin
spec:
  options:
    max_session_ttl: 24h
  allow:
    logins: [root]
    node_labels:
      "*": "*"
    rules:
      - resources: ["*"]
        verbs: ["*"]

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

kind: role
version: v3
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 admin.yaml
$ tctl create dev.yaml

Testing

Update the Teleport settings to use the SAML settings to make this the default.

auth_service:
  authentication:
    type: saml

Login with Microsoft

The Web UI will now contain a new button: "Login with Microsoft". 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

Troubleshooting

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

Example of a user being denied due as the role clusteradmin wasn't setup.

{"code":"T1001W","error":"role clusteradmin is not found","event":"user.login","method":"saml","success":false,"time":"2019-06-15T19:38:07Z","uid":"cd9e45d0-b68c-43c3-87cf-73c4e0ec37e9"}

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 the --debug flag to teleport start command.

Teleport Enterprise

Teleport Enterprise is built around the open-source core, with premium support and additional, enterprise-grade features. It is for organizations that need to secure critical production infrastructure and meet compliance and audit requirements.

Demo Teleport Enterprise

Teleport Community

Teleport Community provides modern SSH best practices out of the box for managing elastic infrastructure. Teleport Community is open-source software that anyone can download and install for free.

Download Teleport Community