mirror of
https://github.com/gravitational/teleport.git
synced 2026-11-04 19:12:46 +08:00
Paul Gottschling
91c89b6126
* Organize docs guide sections chronologically This change aims to make docs navigation easier by organizing some docs sections according to the sequence of steps a user would take to set up Teleport. The current docs organization uses a variety of categories and schemes to organize the docs. For example, there is a "Home" section that includes the Changelog, Installation page, and Getting Started guides; a "Setup" section that includes references and admin guides; and edition-specific sections (Enterprise, Cloud). For a user who is setting up Teleport--or who has already done some setup work and wants more advanced instructions--it's difficult to know where in the docs to find the right information. This change organizes our how-to guides into the following categories that describe the process of setting up Teleport: - Try out Teleport - Deploy a Cluster (including choosing an edition) - Configure Access (including SSO, RBAC, and Access Requests) - Manage your Cluster (admin guides, operations, etc.) - Use Teleport (this section already exists) I moved the Reference section after this chronology, since users can access the reference guides anywhere in the setup process. As part of the change, I have also moved the content from the "Enterprise" and "Cloud" sections into "Deploy a Cluster", since this content has to do with how to deploy a specific edition of Teleport. Note that this change does _not_ attempt to reorganize our protocol-specific sections. While adding resources is part of the Teleport setup process, we have a lot of content in our protocol-specific sections, and moving it all into a single section related to adding resources to a cluster would (a) exceed the maximum depth for subsections in the nav bar and (b) cause more confusion than it alleviates. * Respond to PR feedback - Create a "Compliance Frameworks" section of "Configure Access" with the FedRAMP and SOC 2 guides - Rename "Use Teleport" to "Connect your Client" - Move the database GUI client guide into "Connect your Client" * Add redirects * Fix linter issues
95 lines
4.1 KiB
Plaintext
95 lines
4.1 KiB
Plaintext
---
|
|
title: API Architecture
|
|
description: Architectural overview of the Teleport gRPC API.
|
|
---
|
|
|
|
## 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](#credentials).
|
|
|
|
## 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.
|
|
|
|
(!docs/pages/includes/permission-warning.mdx!)
|
|
|
|
```code
|
|
# Copy and Paste the below and run on the Teleport Auth server.
|
|
cat > api-role.yaml <<EOF
|
|
kind: role
|
|
metadata:
|
|
name: api-role
|
|
spec:
|
|
allow:
|
|
rules:
|
|
- resources: ['role']
|
|
verbs: ['read']
|
|
deny:
|
|
node_labels:
|
|
'*': '*'
|
|
version: v5
|
|
EOF
|
|
# Create role
|
|
tctl create -f api-role.yaml
|
|
# Add user and login via web proxy
|
|
tctl users add api-user --roles=api-role
|
|
```
|
|
|
|
See our [roles](../access-controls/reference.mdx#roles) documentation for more details
|
|
on role based access control.
|
|
|
|
## Credentials
|
|
|
|
The Teleport Go client uses Credentials to gather and hold TLS certificates, connect
|
|
to proxy servers over SSH, and perform some other actions.
|
|
|
|
Credentials are created by using Credential loaders, which gather certificates and data
|
|
generated by [Teleport CLIs](../reference/cli.mdx).
|
|
|
|
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.
|
|
- IdentityFile Credentials are the most well-rounded in terms of usability, functionality,
|
|
and customizability. Identity files can be generated through `tsh login` or `tctl auth sign`,
|
|
making them ideal for both long-lived proxy and auth server connections.
|
|
- Key Pair Credentials have a much simpler implementation than the first two 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](https://pkg.go.dev/github.com/gravitational/teleport/api/client#Credentials)
|
|
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](../architecture/proxy.mdx), 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.
|
|
|
|
<Admonition type="note">
|
|
While all Credential loaders support mTLS connections, only some support SSH connections (see the chart above).
|
|
</Admonition>
|
|
|
|
Take a look at this client constructor [example](https://pkg.go.dev/github.com/gravitational/teleport/api/client#example-New)
|
|
to see what these connection options look like.
|