Teleport

Overview

Opal natively supports an integration with Teleport. This integration enables organizations to manage access to groups within Teleport

Use cases:

• Give specific roles via birthright access
• Grant just-in-time short-lived access to roles
• Audit who has access specific roles and why
• Review roles in user access reviews

Setup

In Teleport, you will need to set up a service account for Opal to perform operations.

1. Create an opal-service role

In the Teleport Dashboard, navigate to Team -> Roles and Create New Role. Use the following YAML:

kind: role
metadata:
  name: opal-service
spec:
  allow:
    db_labels:
      "*": "*"
    app_labels:
      "*": "*"
    rules:
      - resources:
          - role
          - user
        verbs: ["list", "create", "read", "update", "delete"]
  options:
    max_session_ttl: 8760h
version: v5

The opal-service role will be used by Opal to make changes to your system. Note that we use a max session TTL of 8760 hours (1 year). The credentials you will generate in a subsequent step will be bound by this TTL and you will need to reissue the credentials at this interval. You may want to set this value higher to avoid needing to reissue the credentials.

2. Next, create an opal-impersonator role on the same page. Use the following YAML:

kind: role
version: v5
metadata:
  name: opal-impersonator
spec:
  # SSH options used for user sessions
  options:
    # max_session_ttl defines the TTL (time to live) of SSH certificates
    # issued to the users with this role.
    max_session_ttl: 10h

  # The allow section declares a list of resource/verb combinations that are
  # allowed for the users of this role. By default, nothing is allowed.
  allow:
    impersonate:
      users: ["opal-service"]
      roles: ["opal-service"]

  # The deny section uses the identical format as the 'allow' section.
  # Deny rules always override allow rules.
  deny:
    node_labels:
      "*": "*"

This role will allow you to sign a credential on behalf of the opal-service service user.

3. Attach this role to yourself in the Teleport dashboard by finding your user and going to Options -> Edit, and adding opal-impersonator to your User Roles.

4. Create the opal-service service user. Go to Team -> Users -> Create New User. Use opal-service as the name and add the opal-service role.

5. In your terminal, use tsh login to login to your account (not the opal service account). If you were already logged in, you must tsh logout and login again to pick up the new opal-impersonator role.

tsh login --proxy=myorg.teleport.sh [email protected]

6. Sign a new credential for the opal-service service account

tctl auth sign --user=opal-service --out=opal-service.pem --ttl=8760h

Note that this step is possible because we attached the opal-impersonator role to our Teleport user. The TTL in this step should match the value you configured in step 1.

7. In the Opal dashboard, Navigate to Catalog, click on the + App icon, and select the Teleport App. Fill out the details for the integration, using the contents of opal-service.pem generated in the previous step as the Opal service account credentials file.

Linking Teleport users to Opal users

Teleport does not expose user emails. Therefore, Opal is not able to associate Teleport users with Opal users by default. In order to be able to use the integration, you need to import the mapping via a custom attribute from your IDP.

1. Make sure that users in your IDP have a field with their teleport username.

2. In Opal, make sure that you have connected your IDP (see docs

3. In Opal, go to Settings and under IDP & HR Integrations click on the Importing X custom user attributes link on your IDP tile.

4. Enter the attribute name from your IDP that has the teleport username, select Teleport username as the Use as value from the dropdown and click Add attribute.

5. The mappings from Opal user to Teleport username will now be imported from your IDP and you should be ready to start using the integration.