Skip to main content
Version: 18.x

Bound Keypair Joining Concepts

Report an issue with this page

This page discusses the main concepts needed to understand Bound Keypair Joining.

Bound keypair​

The term "bound keypair" refers to both the type of credential and way it's used in Teleport: first, a bot generates a standard public/private keypair; next, Teleport is configured to trust the public key, binding it to a token.

While bots using Bound Keypair Joining will receive regular, short-lived Teleport certificates, and will refresh them regularly in a similar manner to renewable certificates, they also make use of an additional public/private keypair that is not tied directly to a certificate. Critically, this means the keypair does not have an expiration date, and that any trust relationship established between Teleport and a Bound Keypair bot is controlled by server-side configuration within Teleport and not due to the passage of time.

Once this trust relationship has been established, bots can - in a sense - serve as their own identity authority, similar to how cloud providers can attest to the identity of a host or CI workflow run. Teleport issues the joining bot a unique cryptographic challenge which the bot signs using its private key, and the result is verified using the key registered with Teleport.

As this self attestation is not by itself a sufficient security guarantee, Bound Keypair Joining makes use of additional server-side rules to control whether or not a join attempt will be allowed, including:

Onboarding​

Onboarding takes place at first join and is the stage at which a public key becomes bound to a token. There are two methods bots may use to complete this step:

  • Preregistered keys: a private key is generated locally on the bot host, and the public key is copied out-of-band to Teleport by a human user or a script. This method ensures no secret values are ever copied between systems.
  • Registration secrets: a one time use random secret is generated by Teleport and provided to the bot host via either a human user or a script, similar to the ephemeral token join method.

If a registration secret is used, the bot uses the registration secret to prove its identity for this first connection, generates a keypair on the fly, and registers the public key with Teleport.

Registration secrets are used by default: if a token is created and no initial (preregistered) public key is provided, a registration secret will be randomly generated by Teleport and written to the token's status.bound_keypair.registration_secret field.

In both cases - once registered, or when using preregistered keys - the joining bot is then required to complete a joining challenge. A unique cryptographic challenge is generated by Teleport which the bot must sign and return. If the signature matches the registered public key, onboarding has succeeded: the public key is permanently bound to the token, a certificate bundle is issued, and a join state document is provided for use on the next join attempt.

Recovery​

Recovery takes place when a bot uses its private key to request new certificates. This can occur in two situations:

  • On first join, when the bot has no certificates.
  • When the bot's certificates expire before they can be renewed, such as when a bot is offline for longer than its configured certificate_ttl.

So long as the bot has and maintains valid Teleport credentials - by default, bot certificates are valid for an hour and renewed every 20 minutes, but these values are configurable - no recovery will be needed after the initial join. Recovery is only required when a bot is unable to refresh its certificates for longer than its configured certificate TTL (e.g. 1 hour).

The behavior of the recovery process depends on two values configured in the token resource: the recovery mode (spec.bound_keypair.recovery.mode), and the recovery limit (spec.bound_keypair.recovery.limit). The mode may have these values:

  • standard (default): only limit recovery attempts can be automatically attempted.

    This mode is recommended for most situations. Bots can recover automatically so long as the recovery count (status.bound_keypair.recovery_count) doesn't exceed the configured limit, which allows cluster administrators to select their tolerance for automatic bot recovery attempts.

    Join state verification is enabled, which helps prevent keypair reuse, but does require clients to store additional on each join.

    Note that as the initial join counts as a recovery attempt, limit must always be at least 1 for the initial join to succeed.

  • relaxed: limit is ignored, but join state verification remains enabled.

    This mode allows for unlimited recovery attempts and is useful for lower security impact bots, or deployments where bots are regularly expected to go offline for extended periods.

    Like standard mode, join state verification is enabled to help prevent keypair reuse, but does require clients to store additional state on each join.

  • insecure: limit is ignored, and join state verification is disabled.

    This mode is the most flexible, as bots can rejoin repeatedly and can operate without mutable client-side state. However, this disables most additional security checks and should be used with care. See the admin guide for more information on using insecure mode in practice.

Join state verification​

A join state document is an additional piece of information provided to joining bots alongside their usual Teleport certificate bundle. It contains signed information about the state of the joining process, including a sequence number that uniquely identifies each join attempt.

Join state verification both ensures that the bot can provide a valid and signed join state document, and that the document contains the expected sequence number.

  • If successful, the join attempt can proceed and a new join state document will be issued with an incremented sequence counter.
  • If the sequence number presented by the client is outdated, the join attempt is rejected, and a lock is created to ensure existing clients will be denied further access to the Teleport cluster.

This system takes advantage of Teleport's short lived certificates and frequent bot reauthentication. If an attacker somehow obtains a copy of a bot's keypair and attempts to use it to retrieve Teleport certificates, they will initially succeed. However, the original bot will eventually make another authentication attempt, using its now-outdated join state document. This join attempt with an outdated document will trigger a lockout and block both the original bot and any credentials in use by the attacker.

Note that join state verification is disabled when the token's spec.bound_keypair.recovery.mode is set to insecure.