# Teleport

The Veza integration for the Teleport access platform enables discovery of users and their assigned roles, providing visibility into which users can take privileged actions in Teleport such as accessing cluster resources, administering trusted devices, or reviewing access requests.

The integration supports both Teleport cloud and self-managed Teleport clusters, including discovery of SAML group to Teleport role mappings when SAML authentication is configured.

## Configuring Teleport

The Teleport connector authenticates using a Teleport identity file generated for a user with the required privileges. Veza recommends creating a dedicated role and user to grant permissions. The time to live (TTL) for the identity file should be long-lasting, to prevent the credentials from expiring during the integration's lifespan.

To enable the Teleport integration, you will need to:

1. Create a discovery role
2. Create a user and assign the user to the role
3. Generate an identity file for the user

### Veza Discovery Role

Create a new role for the Veza integration user. Allow the following privileges in the `spec` section:

```yaml
  allow:
    logins:
    - '{{internal.logins}}'
    rules:
    - resources:
      - event
      verbs:
      - list
      - read
    - resources:
      - session
      verbs:
      - read
      - list
      where: contains(session.participants, user.metadata.name)
    - resources:
      - user
      verbs:
      - list
      - read
    - resources:
      - role
      verbs:
      - list
      - read
    - resources:
      - auth_connector
      verbs:
      - read
      - list
```

> **Important**: The `auth_connector` permissions are required for discovering SAML group to Teleport role mappings when SAML authentication is configured. Without these permissions, SAML group mappings will not appear in your Veza tenant.

The Veza agent will use a generated identity file to authenticate. Teleport generates all identity files with an expiration date (TTL). The identity file must be regenerated once the maximum session TTL is reached to maintain integration functionality. Add a section under the `options:` block to enable a longer TTL. This example sets the value to one year (8,766 hours):

```yaml
max_session_ttl: 8766h0m0s
```

The full role should look like:

**Example Role**

```yaml
kind: role
metadata:
  id: 1717977207671936805
  name: discovery
  revision: f9e9d006-34c1-42b7-bae3-0c1dbd4251e8
spec:
  allow:
    logins:
    - '{{internal.logins}}'
    rules:
    - resources:
      - event
      verbs:
      - list
      - read
    - resources:
      - session
      verbs:
      - read
      - list
      where: contains(session.participants, user.metadata.name)
    - resources:
      - user
      verbs:
      - list
      - read
    - resources:
      - role
      verbs:
      - list
      - read
    - resources:
      - auth_connector
      verbs:
      - read
      - list
  deny:
    logins:
    - guest
  options:
    cert_format: standard
    create_db_user: false
    create_desktop_user: false
    desktop_clipboard: true
    desktop_directory_sharing: true
    enhanced_recording:
    - command
    - network
    forward_agent: false
    idp:
      saml:
        enabled: true
    max_session_ttl: 8766h0m0s
    pin_source_ip: false
    port_forwarding: true
    record_session:
      default: best_effort
      desktop: true
    ssh_file_copy: true
version: v7
```

### Generate an Identity File

From a host configured to work with the Teleport environment, use the `tsh` command to login as the integration user, and generate an identity file for the integration. Use this file when configuring the Teleport integration on Veza.

```shell
tsh login --user=veza_discovery@exampl.com --out=veza-identity-file --ttl=525960
```

* If using Teleport Proxy Service, specify the login URL, for example `--proxy=hostname.teleport.sh`.
* The TTL value sets the duration the credentials are valid, in seconds. For example, `--ttl=525960` will enable the integration for 1 year, after which you will need to regenerate credentials.
* If the user name is an email, enclose it in quotes `(--user="veza@hostname.com"`).

> Note: TTL is in minutes, use a value corresponding to the `max_session_ttl` configured for the Teleport Role.

## Configuring Teleport Integration on Veza Platform

1. On the Veza **Integrations** page, click **Add Integration** and locate the Teleport tile.
2. Configure the integration with the following fields:
   1. **Name** - Name for the integration
   2. **URL** - URL for the Teleport instance to connect to
   3. **Identity File** - Upload the identity file generated for the user

## SAML Group Mappings

When Teleport is configured with SAML authentication, Veza can discover and model the relationships between SAML groups and Teleport roles. To enable this functionality:

1. The discovery role must include `auth_connector` read and list permissions (as shown in the example above)
2. Your Teleport cluster must be configured with a SAML connector
3. The SAML connector should include attribute mappings that map SAML groups to Teleport roles

Veza supports SAML connectors using various attribute names for group mappings, including:

* **Okta SAML**: Standard attribute names in the `attributes_to_roles` mapping
* **Active Directory SAML**: Uses `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` in the `attributes_to_roles` mapping

If using a different identity provider, ensure your SAML connector configuration includes the appropriate attribute mapping for your IDP's group claim format.

## Notes and Supported Entities

### Teleport User

* `id`
* `name`
* `description`
* `user_type`
* `created_by`
* `is_locked`
* `locked_message`
* `locked_time`
* `lock_expires`

### Teleport Role

* `id`
* `name`
* `description`

### Teleport Group (SAML)

When SAML authentication is configured, Veza models SAML groups as LocalGroup entities with the naming convention: `group + "::saml::" + provider`

> The current connector does not support discovery of detailed role configurations beyond basic metadata.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/integrations/integrations/teleport.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.