diff --git a/docs/config.json b/docs/config.json index 56e750f4b5e14..8b8fa947aac44 100644 --- a/docs/config.json +++ b/docs/config.json @@ -718,6 +718,10 @@ "title": "Session Locking", "slug": "/access-controls/guides/locking/" }, + { + "title": "Passwordless (Preview)", + "slug": "/access-controls/guides/passwordless/" + }, { "title": "Second Factor - WebAuthn", "slug": "/access-controls/guides/webauthn/" @@ -1324,6 +1328,11 @@ "source": "/kubernetes-access/helm/reference/teleport-kube-agent/", "destination": "/setup/helm-reference/teleport-kube-agent/", "permanent": true + }, + { + "source": "/access-controls/guides/u2f/", + "destination": "/access-controls/guides/webauthn/", + "permanent": true } ] } diff --git a/docs/pages/access-controls/guides.mdx b/docs/pages/access-controls/guides.mdx index 1c9bf2a0b1263..294df91c17f13 100644 --- a/docs/pages/access-controls/guides.mdx +++ b/docs/pages/access-controls/guides.mdx @@ -16,6 +16,9 @@ layout: tocless-doc
  • [Impersonating Teleport Users](./guides/impersonation.mdx). Create certs for CI/CD using impersonation.
    • +
  • + [Passwordless](./guides/passwordless.mdx). Use passwordless authentication (Preview). +
  • [Second Factor - WebAuthn](./guides/webauthn.mdx). Add Two-Factor Authentication through WebAuthn.
    • diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx new file mode 100644 index 0000000000000..fab927b4ff9c7 --- /dev/null +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -0,0 +1,292 @@ +--- +title: "Passwordless (Preview)" +description: Learn how to use passwordless authentication with Teleport. +--- + + + Passwordless is currently in Preview. + + +Passwordless takes advantage of WebAuthn to provide passwordless and +usernameless authentication for Teleport. + +## Prerequisites + +- A Teleport cluster with WebAuthn configured. + See the [Second Factor: WebAuthn](./webauthn.mdx) guide. +- A hardware device with support for WebAuthn and resident keys. + As an alternative, you can use a Mac with biometrics / Touch ID. +- A web browser with WebAuthn support. To see if your browser supports + WebAuthn, check the [WebAuthn Compatibility]( + https://developers.yubico.com/WebAuthn/WebAuthn_Browser_Support/) page. +- A signed and notarized `tsh` for Touch ID. + [Download the macOS tsh installer](../../installation.mdx#macos). + +A Teleport cluster capable of WebAuthn is automatically capable of passwordless. + +## Step 1/2. Register + +Register your passwordless device using `tsh`: + +```code +$ tsh mfa add +# Choose device type [TOTP, WEBAUTHN, TOUCHID]: WEBAUTHN +# Enter device name: bio +# Allow passwordless logins [YES, NO]: YES +# Tap any *registered* security key +# Tap your *new* security key +# MFA device "bio" added. +``` + +You may pick either `WEBAUTHN` or `TOUCHID` as the device type. Make sure to +answer `YES` to "Allow passwordless logins". + +If you are using a hardware device, a passwordless registration will occupy a +resident key slot. Resident keys, also called discoverable credentials, are +stored in persistent memory in the authenticator (i.e., the device that is used +to authenticate). In contrast, MFA keys are encrypted by the authenticator and +stored in the Teleport Auth Server. Regardless of your device type, passwordless +registrations may also be used for regular MFA. + + +If you plan on relying exclusively on passwordless, it's recommended to register +more than one device. A portable hardware device is ideal, as it can be shared +between `tsh`, the Teleport Web UI, and different computers. + + +
    + Touch ID registrations are isolated by application. A Touch ID registration + for `tsh` is different from a registration made from Chrome or Safari. You may + register the same Touch ID device from multiple applications to get + passwordless access in all of them. +
    + +## Step 2/2. Authenticate + +Authenticate using your passwordless credential: + +```code +$ tsh login --proxy=example.com --auth=passwordless +# Tap your security key +# > Profile URL: https://example.com +# Logged in as: codingllama +# Cluster: example.com +# Roles: access, editor +# Logins: codingllama +# Kubernetes: enabled +# Valid until: 2021-10-04 23:32:29 -0700 PDT [valid for 12h0m0s] +# Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty +``` + +A fully passwordless cluster defaults to passwordless logins, making +`--auth=passwordless` unnecessary. See the next section to learn how to enable +passwordless by default. + + +You can also execute passwordless logins in the Teleport Web UI. To do so, look +for the passwordless link in the Web UI. + + +## Optional: Enable passwordless by default + +Passwordless enthusiasts may enable passwordless by default in their clusters. +Note that this configuration changes Teleport's behavior even for users without +a passwordless device registered, so existing users may need to authenticate +using `tsh login --proxy=example.com --auth=local` in order to get their first +passwordless registration. + +To enable passwordless by default, add `connector_name: passwordless` to your +cluster configuration: + + + + + Auth Server `teleport.yaml` file: + + ```yaml + auth_service: + authentication: + type: local + second_factor: on + webauthn: + rp_id: example.com + connector_name: passwordless # passwordless by default + ``` + + + Create a `cap.yaml` file or get the existing configuration using + `tctl get cluster_auth_preference`: + + ```yaml + kind: cluster_auth_preference + version: v2 + metadata: + name: cluster-auth-preference + spec: + type: local + second_factor: on + webauthn: + rp_id: example.com + connector_name: passwordless # passwordless by default + ``` + + Update the configuration: + + ```code + $ tctl create -f cap.yaml + # cluster auth preference has been updated + ``` + + + + + +Create a `cap.yaml` file or get the existing configuration using +`tctl get cluster_auth_preference`: + +```yaml +kind: cluster_auth_preference +version: v2 +metadata: + name: cluster-auth-preference +spec: + type: local + second_factor: on + webauthn: + rp_id: example.com + connector_name: passwordless # passwordless by default +``` + +Update the configuration: + +```code +$ tctl create -f cap.yaml +# cluster auth preference has been updated +``` + + +## Troubleshooting + +### "Allow passwordless logins" doesn't appear + +If you don't see the "Allow passwordless logins" prompt during `tsh mfa add`, +you may be using an older version of `tsh`. Download the latest `tsh` from our +[installation page](../../installation.mdx). + +### Hardware device not usable + +`tsh` only prompts for hardware devices with certain capabilities for +passwordless registrations. If your device isn't blinking it may not be capable +of passwordless logins. + +Below is a non-comprehensive list of requirements: + +- Device must support WebAuthn (sometimes also called FIDO2 or CTAP2). +- Device must be capable of user verification (biometrics or PIN). +- Device must have a PIN set. +- Device must have fingerprints enrolled (if biometric). This typically means + both a PIN *and* fingerprints. + +`tsh` relies in an embedded libfido2 to access hardware devices. If you are +running on Linux, you may be missing the necessary udev rules to access your +device. Try following the [installation instructions for libfido2]( +https://github.com/Yubico/libfido2#installation), which may provide you the +necessary udev rules. + +### Touch ID not usable + +If you are having trouble with Touch ID, make sure that you are using the latest +standalone version of `tsh`. [Download the macOS tsh installer]( +../../installation.mdx#macos). + +Touch ID support requires Macs with the Touch Bar and Secure Enclave. It also +requires macOS >= 10.13 (macOS High Sierra). + +You can run the `tsh touchid diag` command to verify requirements. A capable +device and `tsh` binary should show an output similar to the one below: + +```code +$ tsh touchid diag +# Has compile support? true +# Has signature? true +# Has entitlements? true +# Passed LAPolicy test? true +# Passed Secure Enclave test? true +# Touch ID enabled? true +``` + +### Disable passwordless + +If you want to forbid passwordless access to your cluster, add `passwordless: +false` to your configuration: + + + + + Auth Server `teleport.yaml` file: + + ```yaml + # snippet from /etc/teleport.yaml: + auth_service: + authentication: + type: local + second_factor: on + webauthn: + rp_id: example.com + passwordless: false # disable passwordless + ``` + + + Create a `cap.yaml` file or get the existing configuration using + `tctl get cluster_auth_preference`: + + ```yaml + kind: cluster_auth_preference + version: v2 + metadata: + name: cluster-auth-preference + spec: + type: local + second_factor: on + webauthn: + rp_id: example.com + passwordless: false # disable passwordless + ``` + + Update the configuration: + + ```code + $ tctl create -f cap.yaml + # cluster auth preference has been updated + ``` + + + + + +Create a `cap.yaml` file or get the existing configuration using +`tctl get cluster_auth_preference`: + +```yaml +kind: cluster_auth_preference +version: v2 +metadata: + name: cluster-auth-preference +spec: + type: local + second_factor: on + webauthn: + rp_id: example.com + passwordless: false # disable passwordless +``` + +Update the configuration: + +```code +$ tctl create -f cap.yaml +# cluster auth preference has been updated +``` + diff --git a/docs/pages/access-controls/guides/per-session-mfa.mdx b/docs/pages/access-controls/guides/per-session-mfa.mdx index 5594c7be08d3b..c15ecbeffcbab 100644 --- a/docs/pages/access-controls/guides/per-session-mfa.mdx +++ b/docs/pages/access-controls/guides/per-session-mfa.mdx @@ -246,6 +246,11 @@ $ tsh ssh prod3.example.com # jerry@prod3.example.com > ``` + +If you are using `tsh` in a constrained environment, you can tell it to use +OTP by doing `tsh --mfa-mode=otp ssh prod3.example.com`. + + If per-session MFA was enabled cluster-wide, Jerry would be prompted for MFA even when logging into `dev1.example.com`. @@ -283,11 +288,10 @@ Current limitations for this feature are: - WebAuthn hardware devices aren't currently supported in `tsh` on Windows. - Only `tsh ssh` supports per-session MFA authentication for SSH (OpenSSH `ssh` does not). -- Only `kubectl` supports per-session U2F authentication for Kubernetes. +- Only `kubectl` supports per-session WebAuthn authentication for Kubernetes. - Application access clients don't support per-session MFA authentication yet, although cluster and role configuration applies to them. If you enable per-session MFA checks cluster-wide, you will not be able to use Application access. We're working on integrating per-session MFA checks for these clients. -- For Desktop Access, only WebAuthn devices are supported. Teleport does not - support U2F devices for Desktop Access MFA. +- For Desktop Access, only WebAuthn devices are supported. diff --git a/docs/pages/access-controls/guides/u2f.mdx b/docs/pages/access-controls/guides/u2f.mdx deleted file mode 100644 index 0dd3515630510..0000000000000 --- a/docs/pages/access-controls/guides/u2f.mdx +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: Second Factor - U2F -description: Configuring U2F support in Teleport clusters. ---- - -# U2F (Hardware Tokens) - - - Consider updating your cluster to use [WebAuthn](./webauthn.mdx) as the second - factor protocol. WebAuthn is a modern U2F replacement that allows for a wider - range of devices to be used as second factor authenticators. - - -Teleport supports [FIDO U2F](https://www.yubico.com/about/background/fido/) -hardware keys as a second authentication factor. U2F can be used for logging -into Teleport (`tsh login` or the login page on the Web UI) and for logging -into individual SSH nodes or Kubernetes clusters (`tsh ssh` and `kubectl`). - -## Prerequisites - -(!docs/pages/includes/edition-prereqs-tabs.mdx!) - -- U2F hardware device, such as Yubikey or Solokey -- Web browser that [supports U2F](https://caniuse.com/u2f) - -(!docs/pages/includes/tctl.mdx!) - -## Enable U2F support - -By default U2F is disabled. To enable U2F support, edit the Teleport -configuration file `/etc/teleport.yaml` like so: - -```yaml -# snippet from /etc/teleport.yaml to show an example configuration of U2F: -auth_service: - authentication: - type: local - # to enable U2F support, set this field to 'u2f', 'on' or 'optional' - second_factor: u2f - u2f: - app_id: https://example.com - facets: - - "https://example.com" # app_id should always also be listed as a facet - - "https://example.com:443" - device_attestation_cas: - - "/path/to/u2f_attestation_ca.pem" -``` - -The fields in the above snippet are: - -- `app_id` - public address of the Teleport proxy, *including* the `https://` - prefix. If you use a port number other than 443, include it as well. - - Examples: - - - `https://example.com` (uses default port 443) - - `https://example.com:3080` (uses non-default port 3080) - - - The `app_id` must never change in the lifetime of the cluster, because it's - recorded in the registration data on the U2F device. If the App ID changes, - all existing U2F key registrations will become invalid and all users who use - U2F as the second factor will need to re-register. When using multiple proxy - servers, make sure they are reachable at the same public address (usually - behind a load balancer). - - -- `facets` - list of allowed addresses of the Teleport proxy, checked during - authentication attempts. This list is used to prevent malicious websites and - proxies from requesting U2F challenges on behalf of the legitimate proxy. - - For compatibility with multiple browsers, it's recommended to write down the - proxy address in several formats. For example, if your `app_id` is - `https://example.com`, your `facets` should include `https://example.com` - (same as the app_id) and `https://example.com:443`. - -- `device_attestation_cas` - optional list of certificate authorities (as local - file paths or in-line PEM certificate string) for U2F [device - attestation](https://fidoalliance.org/specs/fido-u2f-v1.0-nfc-bt-amendment-20150514/fido-u2f-overview.html#verifying-that-a-u2f-device-is-genuine) - verification. This field allows you to restrict which U2F device vendors you - trust. Devices from other vendors will be rejected during registration. By - default, any vendor is allowed. - -Once the configuration file was edited, restart `teleport` to pick up the -changes. - -## Register U2F devices as a user - -A user can register multiple U2F devices [using `tsh`](../../setup/reference/cli.mdx#tsh-mfa-add): - -```code -$ tsh mfa add - -# Choose device type [TOTP, U2F]: u2f -# Enter device name: desktop yubikey -# Tap any *registered* security key -# Tap your *new* security key -# MFA device "desktop yubikey" added. -``` - -{/* Convert to new UI component https://github.com/gravitational/next/issues/275 */} - - - U2F devices are currently not supported in `tsh` on Windows. - - -## Login using U2F - -Once a U2F device is registered, the user will be prompted for it on login: - -```code -$ tsh login --proxy=example.com - -# Enter password for Teleport user awly: -# Tap any security key -# > Profile URL: https://example.com -# Logged in as: awly -# Cluster: example.com -# Roles: admin* -# Logins: awly -# Kubernetes: enabled -# Valid until: 2021-04-01 23:32:29 -0700 PDT [valid for 12h0m0s] -# Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty -``` - - -U2F for logging into Teleport is only required for [local -users](../../setup/reference/authentication.mdx#local-no-authentication-connector). SSO users should configure -multi-factor authentication in their SSO provider. - - -## Next steps - -- [Setup per-session U2F checks](per-session-mfa.mdx) diff --git a/docs/pages/access-controls/guides/webauthn.mdx b/docs/pages/access-controls/guides/webauthn.mdx index 8d9ffd187b163..8003bf72cc540 100644 --- a/docs/pages/access-controls/guides/webauthn.mdx +++ b/docs/pages/access-controls/guides/webauthn.mdx @@ -5,9 +5,9 @@ videoBanner: vQgKkD4ZRDU --- Teleport supports [WebAuthn](https://webauthn.guide/) as a second authentication -factor. WebAuthn can be used for logging in to Teleport (`tsh login` or the login -page on the Web UI) and for logging in to individual SSH nodes or Kubernetes -clusters (`tsh ssh` and `kubectl`). +factor. WebAuthn can be used for logging in to Teleport (`tsh login` or the +login page on the Web UI) and for logging in to individual SSH nodes or +Kubernetes clusters (`tsh ssh` and `kubectl`). WebAuthn support includes hardware devices, such as YubiKeys or SoloKeys (`tsh` and Web UI), as well as biometric authenticators like Touch ID and Windows Hello @@ -25,11 +25,10 @@ and Web UI), as well as biometric authenticators like Touch ID and Windows Hello ## Step 1/3. Enable WebAuthn support -WebAuthn is disabled by default. To enable WebAuthn support, update your Teleport -configuration as below: +WebAuthn is disabled by default. To enable WebAuthn support, update your +Teleport configuration as below: - Auth Server `teleport.yaml` file: @@ -84,11 +83,11 @@ configuration as below: $ tctl create -f cap.yaml # cluster auth preference has been updated ``` - + - + Obtain your existing `cluster_auth_preference` resource: @@ -130,10 +129,14 @@ Update the configuration: $ tctl create -f cap.yaml # cluster auth preference has been updated ``` - -You will need to include the following configuration fields. +
    + Starting on Teleport v10, WebAuthn replaces U2F. See the [U2F](#u2f) section. +
    `rp_id` is the public domain of the Teleport Proxy Service, *excluding* protocol (`https://`) and port number. @@ -179,7 +182,6 @@ $ tsh mfa add Once a WebAuthn device is registered, the user will be prompted for it on login: - ```code $ tsh login --proxy=example.com # Enter password for Teleport user codingllama: @@ -193,10 +195,9 @@ $ tsh login --proxy=example.com # Valid until: 2021-10-04 23:32:29 -0700 PDT [valid for 12h0m0s] # Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty ``` - - + ```code $ tsh login --proxy=mytenant.teleport.sh # Enter password for Teleport user codingllama: @@ -210,15 +211,112 @@ $ tsh login --proxy=mytenant.teleport.sh # Valid until: 2021-10-04 23:32:29 -0700 PDT [valid for 12h0m0s] # Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty ``` - WebAuthn for logging in to Teleport is only required for [local users]( - ../../setup/reference/authentication.mdx#local-no-authentication-connector). SSO users should configure - multi-factor authentication in their SSO provider. + ../../setup/reference/authentication.mdx#local-no-authentication-connector). + SSO users should configure multi-factor authentication in their SSO provider. +## U2F + +Starting with Teleport v10, WebAuthn replaces U2F. If you haven't configured U2F +before, no further action is necessary—any U2F devices are automatically +supported. + +If you have an existing U2F configuration, but haven't explicitly configured +WebAuthn yet, Teleport will automatically derive your WebAuthn configuration +from your existing U2F configuration. + +You may write the WebAuthn configuration yourself, but keep the U2F `app_id` +field. Doing so ensures that any already-registered U2F devices won't need to be +re-registered. + +For example, consider the U2F configuration below: + +```yaml +# snippet from /etc/teleport.yaml showing a U2F configuration: +auth_service: + authentication: + type: local + second_factor: u2f + u2f: + app_id: https://example.com + facets: + - "https://example.com" + - "https://example.com:443" + device_attestation_cas: + - "/path/to/u2f_attestation_ca.pem" +``` + +The migrated WebAuthn configuration is: + + + + + ```yaml + # snippet from /etc/teleport.yaml: + auth_service: + authentication: + type: local + second_factor: on # changed from "u2f" + u2f: + # Keep the app_id to avoid re-registering U2F devices. + app_id: https://example.com + webauthn: + # rp_id is the public domain of the Teleport Proxy Service. + # It's similar to the U2F app_id, but without "https://" or port number. + rp_id: example.com + attestation_allowed_cas: + - "/path/to/u2f_attestation_ca.pem" + ``` + + + ```yaml + kind: cluster_auth_preference + version: v2 + metadata: + name: cluster-auth-preference + spec: + type: local + second_factor: on # changed from "u2f" + u2f: + # Keep the app_id to avoid re-registering U2F devices. + app_id: https://example.com + webauthn: + # rp_id is the public domain of the Teleport Proxy Service. + # It's similar to the U2F app_id, but without "https://" or port number. + rp_id: example.com + attestation_allowed_cas: + - "/path/to/u2f_attestation_ca.pem" + ``` + + + + + +```yaml +kind: cluster_auth_preference +version: v2 +metadata: + name: cluster-auth-preference +spec: + type: local + second_factor: on # changed from "u2f" + u2f: + # Keep the app_id to avoid re-registering U2F devices. + app_id: https://example.com + webauthn: + # rp_id is the public domain of the Teleport Proxy Service. + # It's similar to the U2F app_id, but without "https://" or port number. + rp_id: example.com + attestation_allowed_cas: + - "/path/to/u2f_attestation_ca.pem" +``` + + ## Next steps -- [Setup per-session MFA checks](per-session-mfa.mdx) +- [Passwordless](./passwordless.mdx) +- [Setup per-session MFA checks](./per-session-mfa.mdx) diff --git a/docs/pages/access-controls/introduction.mdx b/docs/pages/access-controls/introduction.mdx index 2682056936f34..56833db802749 100644 --- a/docs/pages/access-controls/introduction.mdx +++ b/docs/pages/access-controls/introduction.mdx @@ -34,6 +34,9 @@ guide. Create certs for CI/CD using impersonation. + + Use passwordless authentication (Preview). + Add Two-Factor Authentication through WebAuthn. diff --git a/docs/pages/access-controls/reference.mdx b/docs/pages/access-controls/reference.mdx index 29eca8393370c..011f27656f0d0 100644 --- a/docs/pages/access-controls/reference.mdx +++ b/docs/pages/access-controls/reference.mdx @@ -334,8 +334,8 @@ spec: ## Second Factor - U2F -Refer to the [Second Factor - U2F guide](./guides/u2f.mdx) if you have a cluster -using the legacy U2F support. +Refer to the [Second Factor - WebAuthn](./guides/webauthn.mdx#u2f) guide if you +have a cluster using the legacy U2F support. ## Filter fields diff --git a/docs/pages/setup/operations/backup-restore.mdx b/docs/pages/setup/operations/backup-restore.mdx index 9b5005c7e4da6..832e22815dd34 100644 --- a/docs/pages/setup/operations/backup-restore.mdx +++ b/docs/pages/setup/operations/backup-restore.mdx @@ -150,9 +150,9 @@ also apply to a new cluster being bootstrapped from the state of an old cluster: - Changing the cluster name will break your CAs. This will be caught and Teleport will refuse to start. - - Some user authentication mechanisms (e.g. WebAuthn and U2F) require that the - public endpoint of the Web UI remains the same. This cannot be caught by - Teleport, so be careful! + - Some user authentication mechanisms (e.g. WebAuthn) require that the public + endpoint of the Web UI remains the same. This cannot be caught by Teleport, + so be careful! - Any Node whose invite token is defined in the Auth Service's configuration file will be able to join automatically, but Nodes that were added dynamically will need to be re-invited. @@ -214,9 +214,9 @@ also apply to a new cluster being bootstrapped from the state of an old cluster: - Changing the cluster name will break your CAs. This will be caught and Teleport will refuse to start. - - Some user authentication mechanisms (e.g. WebAuthn and U2F) require that the - public endpoint of the Web UI remains the same. This cannot be caught by - Teleport, so be careful! + - Some user authentication mechanisms (e.g. WebAuthn) require that the public + endpoint of the Web UI remains the same. This cannot be caught by Teleport, + so be careful! - Any Node whose invite token is defined in the Auth Service's configuration file will be able to join automatically, but Nodes that were added dynamically will need to be re-invited. diff --git a/docs/pages/setup/reference/cli.mdx b/docs/pages/setup/reference/cli.mdx index c7ef7e1afcc4e..07be6b2d1ed82 100644 --- a/docs/pages/setup/reference/cli.mdx +++ b/docs/pages/setup/reference/cli.mdx @@ -154,7 +154,8 @@ information about the cluster. | `-i, --identity` | none | **string** filepath | Identity file | | `--cert-format` | `file` | `file` or `openssh` | SSH certificate format | | `--insecure` | none | none | Do not verify the server's certificate and host name. Use only in test environments. | -| `--auth` | `local` | Any defined [authentication connector](./authentication.mdx) | Specify the type of authentication connector to use. | +| `--auth` | `local` | any defined [authentication connector](./authentication.mdx), including `local` and `passwordless` | Specify the type of authentication connector to use. | +| `--mfa-mode` | auto | `auto`, `cross-platform`, `platform` or `otp` | Preferred mode for MFA and Passwordless assertions. | | `--skip-version-check` | none | none | Skip version checking between server and client. | | `-d, --debug` | none | none | Verbose logging to stdout | | `-J, --jumphost` | none | A jump host | SSH jumphost | @@ -695,11 +696,14 @@ registered devices using [`tsh mfa ls`](cli.mdx#tsh-mfa-ls). $ tsh mfa rm ``` +### tsh environment variables + Environment variables configure your tsh client and can help you avoid using flags repetitively. | Environment Variable | Description | Example Value | | - | - | - | -| TELEPORT_AUTH | Name of a defined SAML, OIDC, or GitHub auth connector | okta | +| TELEPORT_AUTH | Name of a defined local, SAML, OIDC, or Github auth connector | okta | +| TELEPORT_MFA_MODE | Preferred mode for MFA and Passwordless assertions | otp | | TELEPORT_CLUSTER | Name of a Teleport root or leaf cluster | cluster.example.com | | TELEPORT_LOGIN | Login name to be used by default on the remote host | root | | TELEPORT_LOGIN_BIND_ADDR | Address in the form of host:port to bind to for login command webhook | host:port | diff --git a/docs/pages/setup/reference/config.mdx b/docs/pages/setup/reference/config.mdx index e93ed77a5d0f7..3c8dfbbc029a8 100644 --- a/docs/pages/setup/reference/config.mdx +++ b/docs/pages/setup/reference/config.mdx @@ -277,14 +277,25 @@ auth_service: # (https://goteleport.com/docs/enterprise/ssh-kubernetes-fedramp/) #local_auth: true - # second_factor can be 'off', 'on', 'optional', 'otp', 'webauthn' or - # 'u2f'. - # - 'on' requires otp and either webauthn (preferred) or u2f. - # - 'optional' allows otp and either webauthn (preferred) or u2f. - # - 'otp', 'webauthn' and 'u2f' require their corresponding second - # factor type. + # second_factor can be 'off', 'on', 'optional', 'otp' or 'webauthn'. + # - 'on' requires either otp or webauthn second factor. + # - 'optional' allows otp and webauthn second factor. + # - 'otp' and 'webauthn' require the corresponding second factor. second_factor: otp + # Sets whether passwordless authorization is allowed. + # Passwordless requires WebAuthn. + # Defaults to "true". + #passwordless: true + + # Sets the authenticator connector for SSO (Enterprise) or the default + # connector for "local" authentication. + # See SSO for Enterprise (https://goteleport.com/docs/enterprise/sso/). + # See Passwordless for local + # (http://goteleport.com/docs/access-controls/guides/passwordless/#optional-enable-passwordless-by-default). + # Defaults to "local". + #connector_name: local + # this section is used if second_factor is set to 'on', 'optional' or # 'webauthn'. webauthn: @@ -333,48 +344,13 @@ auth_service: # second factor modes 'on' and 'optional'. disabled: false - # this section is used if second_factor is set to 'u2f' + # the U2F section is kept for legacy purposes and to support existing + # U2F registrations. u2f: - # public address of the Teleport proxy, _including_ the `https://` - # prefix. If you use a port number other than 443, include it as - # well. - # - # Examples: - # - "https://example.com" (uses default port 443) - # - "https://example.com:3080" (uses non-default port 3080) - # - # IMPORTANT: app_id must never change in the lifetime of the - # cluster, because it's recorded in the registration data on the - # U2F device. If the app_id changes, all existing U2F key - # registrations will become invalid and all users who use U2F as - # the second factor will need to re-register. + # app ID used by U2F registrations. + # Keep it in your config to avoid having to re-register U2F devices. app_id: https://localhost:3080 - # list of allowed addresses of the Teleport proxy checked during - # authentication attempts. This list is used to prevent malicious - # websites and proxies from requesting U2F challenges on behalf of - # the legitimate proxy. - facets: - # app_id should always also be listed as a facet - - https://localhost:3080 - - https://localhost - # localhost allows non-https facets as well - - localhost:3080 - - localhost - - # optional list of certificate authorities (as local file paths or - # in-line PEM certificate string) for U2F [device - # attestation](https://fidoalliance.org/specs/fido-u2f-v1.0-nfc-bt-amendment-20150514/fido-u2f-overview.html#verifying-that-a-u2f-device-is-genuine) - # verification. This field allows you to restrict which U2F device - # vendors you trust. Devices from other vendors will be rejected - # during registration. By default, any vendor is allowed. - device_attestation_cas: - - /path/to/u2f_ca.pem - - | - -----BEGIN CERTIFICATE----- - ... - -----END CERTIFICATE----- - # Locking mode determines how to apply lock views locally available to # a Teleport component; can be strict or best_effort. # See the "Locking mode" section for more details diff --git a/docs/pages/setup/security/reduce-blast-radius.mdx b/docs/pages/setup/security/reduce-blast-radius.mdx index 8a3f7898ca032..4e087a8db59fb 100644 --- a/docs/pages/setup/security/reduce-blast-radius.mdx +++ b/docs/pages/setup/security/reduce-blast-radius.mdx @@ -15,9 +15,9 @@ Teleport encourages users to practice defense in depth so that every component o (!docs/pages/includes/tctl.mdx!) ## Make MFA mandatory for `tsh login` -If a user sets up an account to authenticate to their Teleport cluster with only a password, an adversary can gain access to the password using brute-force attacks, person-in-the-middle attacks, or phishing. But even if a user's password is compromised, you can stop an attacker from authenticating with it when they run `tsh login`. +If a user sets up an account to authenticate to their Teleport cluster with only a password, an adversary can gain access to the password using brute-force attacks, person-in-the-middle attacks, or phishing. But even if a user's password is compromised, you can stop an attacker from authenticating with it when they run `tsh login`. -Teleport lets you make it mandatory for a user to enroll an MFA device when they create an account, and to authenticate using that device when they begin a new Teleport session. +Teleport lets you make it mandatory for a user to enroll an MFA device when they create an account, and to authenticate using that device when they begin a new Teleport session. To do so, make the following changes depending on your environment: @@ -25,7 +25,7 @@ To do so, make the following changes depending on your environment: Ensure that the value of `auth_service.authentication.second_factor` is `otp`, -`u2f`, `webauthn`, or `on`: +`webauthn`, or `on`: ```yaml auth_service: @@ -33,12 +33,6 @@ auth_service: second_factor: webauthn ``` - - -`u2f` is an alias for `webauthn`. - - - @@ -50,7 +44,7 @@ $ tctl get cap > cap.yaml If you have not defined a `cluster_auth_preference`, `cap.yaml` will be blank. -In `cap.yaml`, ensure that the value of `spec.second_factor` is `otp`, `u2f`, +In `cap.yaml`, ensure that the value of `spec.second_factor` is `otp`, `webauthn`, or `on`: ```yaml @@ -62,25 +56,18 @@ spec: second_factor: otp ``` - - -`u2f` is an alias for `webauthn`. - - - -Apply your change: +Apply your change: ```code $ tctl create -f cap.yaml ``` - + To make MFA mandatory for all users, `second_factor` must be set to one of the following values: - `otp` -- `u2f` - `webauthn` - `on` @@ -92,7 +79,7 @@ Choose `on` if you would like to require MFA for all users while letting them ch If you have enabled SSO in your Teleport environment, Teleport will conduct its own MFA challenge before sending a request to the identity provider. This means that, even if an attacker has managed to compromise your organization's SSO provider (e.g., by impersonating an administrator), a malicious user will still need to authenticate using valid credentials. -If your `second_factor` configuration is set to `off` and a user creates an account without a second factor, changing `second_factor` to a value that requires MFA will force that user to authenticate with a credential they have not registered. This will lock them out of their account. You have two ways to avoid this scenario: +If your `second_factor` configuration is set to `off` and a user creates an account without a second factor, changing `second_factor` to a value that requires MFA will force that user to authenticate with a credential they have not registered. This will lock them out of their account. You have two ways to avoid this scenario: - Set `second_factor` to `optional` until you have confirmed that existing users have enrolled their MFA devices. - Run the `tctl users reset ` command to force a user to enter new credentials, including any required MFA device. @@ -127,7 +114,7 @@ spec: Create your dynamic resource using `tctl create -f `. - + ## Require dual authorization for role requests Even if an attacker gains access to a user's credentials and successfully signs into your Teleport cluster, you can still prevent the user from escalating their privileges. If you enable dual authorization, users who request to assume a particular role must obtain permission to do so from two or more reviewers. This way, if a malicous user manages to impersonate a legitimate one, reviewers can contact the real user before granting the new role.