Julia Ogris
2a05d3edfe
* types: Add minimal role v9 with app default-deny
Add role resource version v9. A v9 role denies all access to HTTP apps
by default: when it grants an app via `app_labels` or
`app_labels_expression`, every HTTP request is denied unless an
allow-side `app_resources` rule permits it (RFD 0303).
Add `app_resources` to a role's `spec.allow` (not `spec.deny`), rules
controlling access to an app's resources on each HTTP request. For now
a rule holds one field, `allow_all`, which grants unrestricted access,
equivalent to v8, and must be the only rule. Reserve field numbers for
the fine-grained fields (`paths`, `methods`, `where`, audit codes) so
later releases add them without renumbering. Bump the role version in
an N.0.0 release: the breaking default-deny aims to ship in Teleport
v19.0.0.
Reject at write time any `app_resources` use on pre-v9 roles, under
deny, in a rule that does not set `allow_all`, or in a rule next to
another rule.
Serve v9 roles to clients older than 19.0.0 as v8 copies: the auth
server strips `app_resources` and marks the copy with the
`teleport.internal/downgraded` label. The stored role stays v9; only
what goes over the wire changes. The downgrade fails closed: unless a
rule sets `allow_all` (exactly v8 access, lossless), the copy also
loses its allow `app_labels` and `app_labels_expression`, so an older
agent denies the app entirely instead of serving it unrestricted.
Enforce the default-deny in the app agent's plain-HTTP path; TCP, MCP,
cloud, and LLM apps are excluded. When v8 and v9 roles grant the same
app, drop the v8 roles from the decision so they cannot re-open
unrestricted access, and log a warning once.
Bundle the Terraform provider update so v9 roles can be managed as
code starting with v19.0.0. The operator v9 CRD kind follows
separately.
Generated changes:
make grpc/host
make derive
make -C integrations/terraform docs
make -C integrations/operator generate
* auth: Downgrade roles from GetCurrentUserRoles
Run every role streamed by GetCurrentUserRoles through
maybeDowngradeRole before sending, matching GetRole, GetRoles,
ListRoles, and the watch stream. Without it, a pre-19 client asking a
remote cluster for its mapped roles receives a v9 role with allow
app_labels intact and no app_resources enforcement it understands, so
client-side access checks treat a default-deny role as granting full
app access. The change also applies the pre-existing v8-to-v7
downgrade on this surface, which previously served v8 roles to v17
clients unchanged.
* terraform: Exclude deny-side app_resources from schema
Drop `app_resources` from the Terraform role schema's deny block, as
the server rejects any deny-side `app_resources` at write time and
RFD 0303 keeps the rules allow-only so that they fail closed. With the
field gone from the schema, Terraform rejects a deny-side rule at plan
time instead of leaving it to the server's write-time check. Follow the
existing `RoleV6.Spec.Deny.Namespaces` exclusion.
Generated changes:
make -C integrations/terraform docs
* docs: Split role versions into per-version headings
Break the Role versions section into one H4 per role version so
readers can jump straight to the version they care about. Move the
SAML IdP note under the v8 heading, since it describes a v8 change,
and keep the kubernetes_resources defaults table as its own H4 at
the end. Fix a mismatched backtick around `v5` in the moved
session-joining paragraph.
* app: Warn when version skew denies a v9 request
When the minimal v9 check denies a request because the user's roles
carry `app_resources` rules or role versions this Teleport version
does not implement, the app agent previously answered 403 without any
log line. In a mixed-version cluster an operator saw denied requests
with no explanation that the deny came from a version mismatch rather
than from an intended default-deny role.
Track the condition as `versionSkew` on `minimalV9Decision`:
deny-side rules, allow rules beyond a single pure `allow_all`, or a
role version above v9. When such a deny fires, log one warning per
user and app through the existing `v9WarnOnce` mechanism, telling the
operator to upgrade the app agent. An intended default-deny, a v9 role
without app rules, stays quiet. A follow-up PR adds a minimal audit
event for the same denials.
* app: Deny apps a downgraded v9 role restricted
A v9 role that restricts app access downgrades to v8 for a pre-v19 agent
that cannot enforce the restriction. Clearing the role's allow app labels
alone would only stop that role granting the apps; another v8 role the user
holds could still grant them, so the restriction would not hold on the old
agent. Move the role's allow app selector to the deny side instead, so no
other role grants the apps this role restricted. The deny is at least as
strict as the v9 restriction and never grants more.
If the role already denies apps by label, there is no room to merge a
second label map, so fall back to a wildcard deny and log it rather than
drop the existing deny.
* docs: Correct v9 downgrade mixed-version guidance
Describe the deny-side downgrade the code actually performs. Without
`allow_all`, the v8 copy moves the allow app selector to the deny side
rather than dropping it, so deny rules override allow rules across a user's
roles and a separate v8-or-older role can no longer reopen the app on
pre-v19 agents. Note that the moved selector denies conservatively and can
block more apps than the v9 role allowed in a mixed-version cluster.
* role: Deny v9 app access for unknown JSON fields
Empty any v9 allow app_resources rule whose stored JSON carried a field
this version does not recognize, so a rule written by a newer version cannot
read as more permissive than intended. An unrecognized field already denies
on the other surfaces: proto reads keep it in XXX_unrecognized so
IsAllowAllOnly rejects it, and writes reject it at validation. JSON unmarshal
drops unknown fields silently, so this re-scans the raw bytes on read. The
known field set is derived from the AppResource message, so a new proto field
extends it automatically. The result is a single rule across every surface,
an unrecognized field grants nothing, worst case over-deny.
* app: Deny app access from roles newer than v9
A role from a version above v9 may carry restrictions this agent cannot
evaluate, so treat it as deny even when its known fields form a plain
allow_all. Previously such a role set both versionSkew and allowed, and
enforceMinimalV9 returns early on allowed, so the request was forwarded and
the skew warning never fired.
* auth: Explain the greedy deny in the v9 downgrade
The downgrade moves a v9 role's allow app selector to the deny side, which
looks like it could clobber an existing deny expression. Record why it
cannot, since deny matches on either selector, and why label maps fall back
to a wildcard where expressions compose with an or.
* api: Guard the AppResource field set with a test
IsAllowAllOnly decides whether a rule is unrestricted by checking that
allow_all is set and no unknown bytes arrived over the wire. A field added
in tree, once one of the reserved numbers is unreserved, would restrict the
rule without making that check return false. Pin the field set so such an
addition fails the test, and name the checks to re-evaluate next to the
reserved numbers in the proto.
* app: Bound the v9 warning deduplication cache
The v9 enforcement warnings fire once per warning kind, user, and app, and
the sync.Map holding those keys never dropped an entry, so a long-running
app agent serving many users and apps grew it for the life of the process.
Hold the keys in a fixed-size LRU instead. Evicting the least recently
warned entry repeats its warning, which is the better failure mode.
* role: Address review feedback
Reword the checkAppResources godoc so the api module does not reference
lib/services. Move the unknown-field check for allow app_resources rules
from integrations/lib/tctl into lib/services next to the other role
unmarshal handling, and derive its known field set from the AppResource
message instead of hardcoding allow_all, so unreserving a proto field
extends it without a second edit. Replace the package-level
preV9RoleVersions slice with roleVersionPredatesV9, a function with a
switch, so nothing mutable sits at package scope.
* role: Address agent review feedback
Reword the `decideMinimalV9` godoc so only a v9 role can allow; a
version above v9 always denies. Drop the `AppResource` message summary
sentence that misstated the reserved field numbers as path, method, and
where rules; fields 6 to 9 hold the audit and deny-hint fields. Reword
the `TestAppResourceFields` comment so the api module does not point
at `lib/services`. Give `v10Grants` an `allow_all` rule so the
above-v9 test case fails if a newer-version role with a plain
`allow_all` rule ever allows again. Add a downgrade subtest for the
deny-expression OR-merge, which no test executed, and a `lib/services`
table test for `CheckAppResourcesKnownFields`, which was only
exercised from the integrations module after its move.
* role: Compact review-feedback additions
Tighten the previous commit's additions, partly to keep the PR under
5,000 added lines. Compact the `CheckAppResourcesKnownFields` table
test into direct assertions, flatten the allowed branch in
`decideMinimalV9`, iterate the `AppResource` fields with
`reflect.TypeFor`, drop the slice alias in
`denyAppAccessForUnknownFields`, and shorten two test comments and a
wrapped constructor call. No behavior change.
* role: Reuse access checking for v9 app decisions
The v9 default-deny check needs to know which individual role grants an
app. `roleGrantsApp` answered that by repeating the namespace and label
stages of `RoleSet` access checking inside `lib/srv/app`, where a second
implementation can drift from the original. Replace it with
`services.RoleGrantsResource`, which delegates to `RoleSet.checkAccess`
and follows the existing single-role idiom in
`lib/services/access_checker.go`.
Delegating changes one case. `resourceRequiresLabelMatching` exempts the
Identity Center app subkind from app label matching, so `checkAccess`
treats every role as granting such an app and v9 denies requests that
`roleGrantsApp` allowed. Add `isPlainHTTPApp` to skip enforcement for
that subkind alongside the cloud and LLM types, which is the scope v9 is
documented to cover, and log once per user and app when an app reaches
the check that should have been routed elsewhere. Drop the unused error
return from `decideMinimalV9`.
Remove `CheckAppResourcesKnownFields`. The property it enforced, that a
role never stores an `app_resources` rule with a field this version does
not understand, already holds on the write path, where `UnmarshalRole`
empties such a rule and `validateAppResources` then rejects it for no
longer setting `allow_all` alone. Its only caller was a test helper for
the access plugins, so assert the write path directly instead.
Describe `validateAppResources` by the property it guarantees rather than
by each check it runs, so the godoc does not drift as the checks change.
Explain why the role stream downgrades per client version, and say
explicitly that both versions in the `maybeDowngradeRole` ordering
comment are the client's, which read ambiguously as the server's. Cut the
role v9 reference section to the field it introduces and a link, and move
the rules, the mixed-version role behavior, and the agent upgrade it
requires to a new Application Resources reference page.
* docs: Use a defined tag on the app resources page
The application-access tag is not in the docs tags vocabulary, so the
docs build rejected the new page. Use privileged-access, which the
sibling roles reference page already carries.
* terraform: Regenerate the schema with protoc-gen-terraform v4
Master upgraded the generator to v4.0.0, which marks list-nested
attributes computed and preserves unknown elements by index. Regenerate
so the app_resources attributes match what the pinned generator emits.
Teleport provides connectivity, authentication, access controls and audit for infrastructure.
You might use Teleport to:
- Set up single sign-on (SSO) for all of your cloud and on-prem infrastructure.
- Protect access to servers, Kubernetes clusters, databases, Windows desktops, web applications, and cloud APIs without long-lived keys or passwords.
- Establish secure tunnels to reach resources behind NATs and firewalls without VPNs or bastion hosts.
- Record and audit activity across SSH, Kubernetes, database, RDP, and web sessions.
- Apply consistent Role-Based and Attribute-Based Access Control (RBAC/ABAC) across users, machines, workloads, and resource types.
- Enforce least privilege and Just-in-Time (JIT) access requests for elevated roles or sensitive systems.
- Maintain a single identity and access layer for both human users and workloads.
Teleport works with SSH, Kubernetes, databases, RDP, cloud consoles, internal web services, Git repositories, and Model Context Protocol (MCP) servers.
More Information
Teleport Getting Started
Teleport Architecture
Reference Guides
FAQ
Table of Contents
- Introduction
- Why We Built Teleport
- Supporting and Contributing
- Installing and Running
- Docker
- Building Teleport
- License
- FAQ
Introduction
Teleport includes an identity-aware access proxy, a CA that issues short-lived certificates, a unified access control system, and a tunneling system to access resources behind the firewall.
Teleport is a single Go binary that integrates with multiple protocols and cloud services, including
- SSH nodes
- Kubernetes clusters
- PostgreSQL, MongoDB, CockroachDB and MySQL databases
- Model Context Protocol
- Internal Web apps
- Windows Hosts
- Networked servers
You can set up Teleport as a Linux daemon or a Kubernetes deployment.
Teleport focuses on best practices for infrastructure security, including:
- No shared secrets such as SSH keys or Kubernetes tokens; Teleport uses certificate-based auth with automatic expiration for all protocols.
- Multi-factor authentication (MFA) for everything.
- Single sign-on (SSO) for everything via GitHub Auth, OpenID Connect, or SAML with endpoints like Okta or Microsoft Entra ID.
- Session sharing for collaborative troubleshooting for issues.
- Infrastructure introspection to view the status of every SSH node, database instance, Kubernetes cluster, or internal web app through the Teleport CLI or Web UI.
Teleport uses Go crypto. It is
fully compatible with OpenSSH, sshd servers, and ssh clients,
Kubernetes clusters and more.
| Project Links | Description |
|---|---|
| Teleport Website | The official website of the project. |
| Documentation | Admin guide, user manual and more. |
| Features | Explore the complete list of Teleport capabilities. |
| Blog | Our blog where we publish Teleport news and helpful articles. |
| Forum | Ask us a setup question or post tutorials, feedback, or ideas. |
| Developer Tools | Dozens of free browser-based tools for code processing, cryptography, data transformation, and more. |
| Teleport Academy | How-to guides, best practices, and deep dives into topics like SSH, Kubernetes, MCP, and more. |
| Slack | Need help with your setup? Ping us in our Slack channel. |
| Cloud & Self-Hosted | Teleport Enterprise is a cloud-hosted option for teams that require easy and secure access to their computing environments. |
Why We Built Teleport
While working together at Rackspace, the creators of Teleport noticed that most cloud users struggle with setting up and configuring infrastructure security. Many popular tools designed for this are complex to understand and expensive to maintain across modern, distributed computing infrastructure.
We decided to build a solution that's easy to use, understand, and scale. A real-time representation of all your servers in the same room as you, as if they were magically teleported. And thus, Teleport was born!
Today, Teleport is trusted by everyone from hobbyists to hyperscalers to simplify security across cloud CLIs and consoles, Kubernetes clusters, SSH servers, databases, internal web apps, and Model Context Protocol (MCP) used by AI agents.
Learn more about Teleport and our history
Supporting and Contributing
We aim to make Teleport easy to adopt and contribute to, starting with clear and comprehensive documentation.
If you have questions, are exploring ideas, or want to sanity-check something, please start with a GitHub Discussion. Discussions help us answer questions, explore use cases, and decide together whether something should become a bug report or feature request.
-
Start a conversation in Teleport Discussions
This is the best place to ask questions, share ideas, and get help. Our engineers actively participate there, and discussions can be promoted to issues when there is a clear, actionable next step. -
Issues are for confirmed bugs and well-defined feature requests
If something has already been validated as a bug or an enhancement, feel free to open an issue. When in doubt, start a discussion and we will help guide it. -
Enterprise and POC support
If you are evaluating Teleport Enterprise or need more responsive support during a POC, we can set up a dedicated Slack channel. You can reach out to us through our website to get started.
Installing and Running
To set up a single-instance Teleport cluster, follow our getting started guide. You can then register your servers, Kubernetes clusters, and other infrastructure with your Teleport cluster.
You can also get started with Teleport Enterprise Cloud, a managed Teleport deployment that makes it easier to enable secure access to your infrastructure.
Sign up for a free trial of Teleport Enterprise Cloud, and follow this guide to register your first server.
Docker
Deploy Teleport
If you wish to deploy Teleport inside a Docker container see the installation guide.
For Local Testing and Development
To run a full test suite locally, see the test dependencies list
Building Teleport
The teleport repository contains the Teleport daemon binary (written in Go)
and a web UI written in TypeScript.
If your intention is to build and deploy for use in a production infrastructure
a released tag should be used. The default branch, master, is the current
development branch for an upcoming major version. Get the latest release tags
listed at https://goteleport.com/download/ and then use that tag in the git clone. For example git clone https://github.com/gravitational/teleport.git -b v18.5.0 gets release
v18.5.0.
Dockerized Build
It is often easiest to build with Docker, which ensures that all required tooling is available for the build. To execute a dockerized build, ensure that docker is installed and running, and execute:
make -C build.assets build-binaries
This command will build Linux binaries matching the host architecture. It is not possible to cross-compile to a different target architecture.
Local Build
Dependencies
The following dependencies are required to build Teleport from source. For
maximum compatibility, install the versions of these dependencies using the
versions listed in build.assets/versions.mk:
For an example of dev environment setup on macOS, see these instructions.
Perform a build
Important
- The Go compiler is somewhat sensitive to the amount of memory: you will need at least 1GB of virtual memory to compile Teleport. A 512MB instance without swap will not work.
- This will build the latest version of Teleport.
Get the source
git clone https://github.com/gravitational/teleport.git
cd teleport
To perform a build
make full
tsh dynamically links against libfido2 by default, to support development
environments, as long as the library itself can be found:
$ brew install libfido2 pkg-config # Replace with your package manager of choice
$ make build/tsh
> libfido2 found, setting FIDO2=dynamic
> (...)
Release binaries are linked statically against libfido2. You may switch the linking mode using the FIDO2 variable:
make build/tsh FIDO2=dynamic # dynamic linking
make build/tsh FIDO2=static # static linking, for an easy setup use `make enter`
# or `build.assets/macos/build-fido2-macos.sh`.
make build/tsh FIDO2=off # doesn't link libfido2 in any way
tsh builds with Touch ID support require access to an Apple Developer
account. If you are a Teleport maintainer, ask the team for access.
Build output and run locally
If the build succeeds, the installer will place the binaries in the build
directory.
Before starting, create default data directories:
sudo mkdir -p -m0700 /var/lib/teleport
sudo chown $USER /var/lib/teleport
Running Teleport in a hot reload mode
To speed up your development process, you can run Teleport using
CompileDaemon. This will
build and run the Teleport binary, and then rebuild and restart it whenever
any Go source files change.
-
Install CompileDaemon:
go install github.com/githubnemo/CompileDaemon@latestNote that we use
go installinstead of the suggestedgo get, because we don't want CompileDaemon to become a dependency of the project. -
Build and run the Teleport binary:
make teleport-hot-reloadBy default, this runs a
teleport startcommand. If you want to customize the command, for example by providing a custom config file location, you can use theTELEPORT_ARGSparameter:make teleport-hot-reload TELEPORT_ARGS='start --config=/path/to/config.yaml'
Note that you still need to run make grpc if you
modify any Protocol Buffers files to regenerate the generated Go sources;
regenerating these sources should in turn cause the CompileDaemon to rebuild
and restart Teleport.
Web UI
The Teleport Web UI resides in the web directory.
Rebuilding Web UI for development
To rebuild the Teleport UI package, run the following command:
make docker-ui
Then you can replace Teleport Web UI files with the files from the
newly-generated /dist folder.
To enable speedy iterations on the Web UI, you can run a local web-dev server.
You can also tell Teleport to load the Web UI assets from the source
directory. To enable this behavior, set the environment variable DEBUG=1
and rebuild with the default target:
# Run Teleport as a single-node cluster in development mode:
DEBUG=1 ./build/teleport start -d
Keep the server running in this mode, and make your UI changes in /dist
directory. For instructions about how to update the Web UI, read the web
README.
Managing dependencies
All dependencies are managed using Go modules. Here are the instructions for some common tasks:
Add a new dependency
Latest version:
go get github.com/new/dependency
and update the source to use this dependency.
To get a specific version, use go get github.com/new/dependency@version instead.
Set dependency to a specific version
go get github.com/new/dependency@version
Update dependency to the latest version
go get -u github.com/new/dependency
Update all dependencies
go get -u all
Debugging dependencies
Why is a specific package imported?
go mod why $pkgname
Why is a specific module imported?
go mod why -m $modname
Why is a specific version of a module imported?
go mod graph | grep $modname
License
Teleport is distributed in multiple forms with different licensing implications.
The Teleport API module (all code in this repository under /api) is
available under the Apache 2.0 license.
The remainder of the source code in this repository is available under the GNU Affero General Public License. Users compiling Teleport from source must comply with the terms of this license.
Teleport Community Edition builds distributed on http://goteleport.com/download are available under a modified Apache 2.0 license.
FAQ
Is Teleport production-ready?
Yes, Teleport is production-ready and used to protect and facilitate access to the most precious and mission-critical applications at many of today's leading companies. You can learn more about the companies using Teleport in production on our website.
Is Teleport secure?
Yes, Teleport has completed several security audits from nationally and internationally recognized technology security companies. We publicize audit results, our security philosophy, and related information on our trust page.
What resources does Teleport support?
Teleport secures access to a broad set of infrastructure resources, including Linux servers, Windows desktops, Kubernetes clusters, databases, internal web applications, cloud provider APIs and consoles (such as AWS, Azure, and GCP), and Model Context Protocol (MCP) servers used by AI agents.
How is Teleport deployed?
Teleport can be deployed to fit most environments, either as a self-hosted cluster on Linux or Kubernetes or using Teleport Enterprise Cloud. In all cases, Teleport agents run close to your resources and connect through an Auth Service and Proxy Service that enforces identity, access control, and audit.
Is Teleport an identity provider (IdP)?
Teleport uses existing IdPs (Okta, Google Workspace, Microsoft Entra ID, or GitHub) to issue short-lived certificates and apply access policies. Teleport can also be configured to act as a SAML IdP to authenticate users into applications when needed.
Does Teleport require credential handling or secrets management?
Teleport eliminates long-lived passwords, SSH keys, database credentials, credential rotations, and vault processes by issuing short-lived, auto-expiring mTLS and SSH certificates bound to human or non-human identity.
Is Teleport a Privileged Access Management (PAM) solution?
Teleport provides modern PAM software capabilities like strong authentication, session recording, policy-based access, and JIT elevation without secrets, credential rotation, or vault dependencies. This enables controlled, audited access to servers, Kubernetes, databases, cloud consoles, and other privileged environments using short-lived certificates and role-based policies.
Is Teleport a Just-in-Time (JIT) access solution?
Teleport enables JIT access through time-bound Access Requests. Users request the roles or resources they temporarily need, policies decide whether approval is required, and privileges automatically expire. This approach maintains least privilege while keeping access workflows efficient and predictable.
Does Teleport secure access to Kubernetes?
Teleport can proxy and secure Kubernetes access with identity-based authentication, role-based access controls, and detailed auditing of kubectl activity.
Does Teleport support SPIFFE?
Teleport supports SPIFFE-compatible identities for workloads, allowing it to participate in SPIFFE ecosystems and federation. Teleport issues short-lived SVIDs and can integrate with external PKI hierarchies.
Is Teleport an alternative for VPNs or bastion hosts?
Yes. Teleport is frequently used as an alternative to traditional VPNs and bastion hosts, enabling direct, identity-based access to resources instead of broad network access.
Does Teleport secure the Model Context Protocol (MCP) and AI agents?
Teleport secures MCP connections by placing identity-aware policy enforcement between MCP clients and servers. This ensures all tool invocations are authenticated, authorized, and audited without custom authorization code and that sensitive systems are protected from overly broad access.