Teleport 2FA: how to set up an authenticator app

Teleport is the access platform companies use to reach their servers, Kubernetes clusters, databases and apps. Your Teleport user lives on your organization's cluster, and that cluster's settings decide which two-factor authentication (2FA) methods you can use. Teleport supports one-time codes from an authenticator app (it calls them OTP or TOTP) and security keys or passkeys (WebAuthn). On a self-hosted cluster, authenticator codes are the default. On Teleport Enterprise Cloud, the default is WebAuthn only, so an authenticator app only works there if an admin has allowed it (Teleport).

This guide uses Authenticator App - Novaz on iPhone. Any authenticator app works the same way, and Teleport's own docs say you can use "Google Authenticator, Authy or any other TOTP client" (Teleport).

How we checked this guide: the Teleport steps come from Teleport's own documentation (version 18.x), linked below, which we read on October 21, 2026. We haven't tested them on a Teleport cluster, so a label may differ slightly. The Novaz steps are checked against the app, version 1.0.5.

Is 2FA required?

It depends on your admin. With the setting on, every local user must register at least one MFA device; with optional, adding one is up to you, but once you do, Teleport asks for it at sign-in; off turns MFA off (Teleport). On self-hosted clusters, MFA is enforced by default (Teleport).

If you sign in through single sign-on (GitHub, or a SAML or OIDC provider such as Okta), Teleport doesn't ask for its own code at sign-in. Your identity provider handles that, so this guide is mostly for local Teleport users.

Set up an authenticator app when you're invited

New local users get an invite link from an admin, in the form https://<your cluster>/web/invite/<token>. The link is valid for one hour. On that page you choose a password and set up multi-factor authentication (Teleport).

1. Open the invite link before it expires and choose a password.
2. Teleport shows a QR code on its welcome screen for an authenticator app (Teleport). In Novaz, tap +, then Scan QR code, and point the camera at it.
3. If you opened the link on your iPhone, take a screenshot, tap +, then Choose a photo. See scanning a QR code on the same iPhone.
4. Type the code Novaz shows into Teleport to finish.

The docs don't say whether a text key is also shown, or how many digits the codes have. Scan the QR code if you can: it carries the code settings, while a key typed with Enter key manually always gets 6 digits every 30 seconds. If the link has expired, ask your admin for a new one.

Add an authenticator app later with tsh

To add an authenticator to an existing user, use Teleport's command-line tool (Teleport):

1. Sign in with tsh login --proxy=<your cluster>.
2. Run tsh mfa add --type=TOTP --name=<a name you choose>. Teleport may ask you to confirm with a device you already registered.
3. Add the new entry to Novaz and type the code it shows. The command reference doesn't show what tsh displays for a TOTP device: if you get a QR code, scan it with Scan QR code; if you get a text key, use Enter key manually. See What is a 2FA setup key?
4. Run tsh mfa ls to check that the new device is listed.

The docs don't list Web UI steps for adding a device later.

When Teleport asks for a code

Local users with MFA are asked at sign-in, in the browser and in tsh (Teleport). Two limits are worth knowing:

• If your admin turned on per-session MFA, which asks again before each SSH or Kubernetes session, an authenticator code won't do. That check needs a security key, passkey or SSO (Teleport).
• The extra check before admin actions, such as inviting or resetting users, also needs a security key or SSO. Teleport only turns it on by itself when authenticator codes aren't allowed on the cluster (Teleport).

Recovery codes on Teleport Enterprise Cloud

When you create a Teleport Enterprise Cloud account, the first user gets a set of recovery codes. Teleport says they can reset the account if you lose your password or your MFA device (Teleport). If you didn't save them, open /web/account/security on your cluster and choose Generate new recovery codes (Teleport). Without a Novaz backup (iCloud backup or a backup file), the keys exist only on your iPhone, so these codes are your way back in. More in 2FA backup codes.

Teleport's docs don't mention recovery codes for self-hosted clusters or for users added later.

If Teleport rejects your code

Teleport's docs don't cover rejected codes. Check your iPhone's clock first: Settings > General > Date & Time > Set Automatically. Novaz warns you when the clock is 15 seconds or more off. Don't keep guessing: Teleport locks a local user for 30 minutes after several failed sign-ins within 30 minutes, and an admin can unlock you sooner (Teleport). More in Authenticator code not working?

Changing phones

If you have a Novaz iCloud backup or backup file, restore your accounts on the new iPhone and the Teleport codes keep working. Otherwise, while you can still sign in, add the new phone with tsh mfa add, then remove the old entry with tsh mfa rm <name> (Teleport). See How to transfer your authenticator app to a new iPhone.

If you lose your authenticator

• Another registered device: if you also added a security key or passkey, sign in with it and add a new authenticator.
• Your admin: an admin can run tctl users reset <your user>, which resets your password and MFA devices and creates a new setup link. The link lasts 8 hours by default and 24 hours at most (Teleport). Teleport's docs don't say what proof your admin should ask for.
• Cloud account owner: use your recovery codes. Teleport warns that without them, the only way back in is to set up a new Teleport Enterprise Cloud account (Teleport).

Teleport recommends a second admin user on self-hosted clusters so one lost device doesn't lock everyone out (Teleport). See also Lost the phone with your authenticator app?

Removing the authenticator

Run tsh mfa rm <name> with the name shown by tsh mfa ls (Teleport). If your cluster's setting is on, every local user needs at least one registered device, so add another one first (Teleport). Then open Teleport in Novaz and tap Remove account.

Official Teleport help

• Authentication Options
• Local Users
• Deploy Teleport Community Edition
• Sign up for Teleport Enterprise Cloud
• Teleport Enterprise Cloud FAQ
• tsh Reference
• tctl Reference
• Per-session MFA
• MFA for Administrative Actions