Teleport
API Architecture
- Edge version
- Version 17.x
- Version 16.x
- Version 15.x
- Older Versions
This guide describes the architecture of the Teleport gRPC API, which enables
clients like tctl, the Teleport Terraform provider, and the Teleport
Kubernetes operator to manage dynamic resources in your Teleport cluster. If you
are new to the Teleport gRPC API, read how to Get
Started.
Authentication
The Auth API uses mTLS to authenticate a client-server connection. Therefore, the client must provide TLS certificates signed by the Auth server to access the API. These are easy to create and provide using Credential loaders.
Authorization
The client certificates signed by the Auth server will be associated with a specific user. This user will be used to authorize API requests made by the client.
It is recommended to make a new user and role for each client. This makes it easier to track client actions, as well as carefully control client permissions.
For example, if your client needs to use client.GetRole(), the user must have permission to perform the read
action on the role resource. You should create a user and role with the minimum permissions required.
When running Teleport in production, you should adhere to the following best practices to avoid security incidents:
- Avoid using
sudoin production environments unless it's necessary. - Create new, non-root, users and use test instances for experimenting with Teleport.
- Run Teleport's services as a non-root user unless required. Only the SSH
Service requires root access. Note that you will need root permissions (or
the
CAP_NET_BIND_SERVICEcapability) to make Teleport listen on a port numbered <1024(e.g.443). - Follow the principle of least privilege. Don't give users
permissive roles when more a restrictive role will do.
For example, don't assign users the built-in
access,editorroles, which give them permissions to access and edit all cluster resources. Instead, define roles with the minimum required permissions for each user and configure access requests to provide temporary elevated permissions. - When you enroll Teleport resources—for example, new databases or applications—you
should save the invitation token to a file.
If you enter the token directly on the command line, a malicious user could view
it by running the
historycommand on a compromised system.
You should note that these practices aren't necessarily reflected in the examples used in documentation. Examples in the documentation are primarily intended for demonstration and for development environments.
Copy and Paste the below and run on the Teleport Auth server.
cat > api-role.yaml <<EOFkind: rolemetadata: name: api-rolespec: allow: rules: - resources: ['role'] verbs: ['read'] deny: node_labels: '*': '*'version: v5EOFCreate role
tctl create -f api-role.yamlAdd user and login via web proxy
tctl users add api-user --roles=api-role
See our roles documentation for more details on role based access control.
Credentials
The Teleport Go client requires credentials in order to authenticate with a Teleport cluster.
Credentials are created by using Credential loaders, which gather certificates and data generated by Teleport CLIs.
Since there are several Credential loaders to choose from with distinct benefits, here's a quick breakdown:
- Profile credentials are the easiest to get started with. All you have to do
is log in to your device with
tsh login. Your Teleport proxy address and credentials will automatically be located and used. - Identity File credentials are the most well-rounded in terms of usability,
functionality, and customizability. Identity files can be generated through
tsh login,tctl auth sign, or with Machine ID. - Dynamic Identity File credentials are Identity File credentials with support for reloading credentials from disk. This makes them appropriate for Machine ID integrations, as you can reload the credentials when Machine ID rotates the underlying identity files.
- Key pair credentials have a much simpler implementation than the other Credentials listed and may feel more familiar. These are good for authenticating clients hosted directly on the auth server.
- TLS credentials leave everything up to the client user. This is mostly used internally, but some advanced users may find it useful.
Here are some more specific details to differentiate them by:
| Type | Profile Credentials | Identity Credentials | Key Pair Credentials | TLS Credentials |
|---|---|---|---|---|
| Ease of use | Easy | Easy | Medium | Hard |
| Supports long-lived certificates | Yes, but must be configured on server side | Yes | Yes | Yes |
| Supports SSH connections | Yes | Yes (6.1+) | No | No |
| Automatic Proxy Address discovery | Yes | No | No | No |
| CLI used | tsh | tctl/tsh | tctl | - |
| Available in | 6.1+ | 6.0+ | 6.0+ | 6.0+ |
See the Credentials type on pkg.go.dev for more information and examples for Credentials and Credential Loaders.
Client connection
The API client makes requests through an open connection to the Teleport Auth server.
If the Auth server is isolated behind a Proxy Server, a reverse tunnel connection can be made using SSH certificates signed by the auth server. You can either provide the server's reverse tunnel address directly or provide the web proxy address and have the client automatically retrieve the reverse tunnel address.
While all Credential loaders support mTLS connections, only some support SSH connections (see the chart above).
Take a look at this client constructor example to see what these connection options look like.