[v18] refactor new join flow

Backport #59331 to branch/v18

Author: nklaassen

api/gen/proto/go/teleport/join/v1/joinservice.pb.go

@@ -34,39 +34,11 @@ message ClientInit {
   string token_name = 2;
   // SystemRole is the system role requested, e.g. Proxy, Node, Instance, Bot.
   string system_role = 3;
-  // PublicTlsKey is the public key requested for the subject of the x509 certificate.
-  // It must be encoded in PKIX, ASN.1 DER form.
-  bytes public_tls_key = 4;
-  // PublicSshKey is the public key requested for the subject of the SSH certificate.
-  // It must be encoded in SSH wire format.
-  bytes public_ssh_key = 5;
   // ForwardedByProxy will be set to true when the message is forwarded by the
   // Proxy service. When this is set the Auth service must ignore any
   // any credentials authenticating the request, except for the purpose of
   // accepting ProxySuppliedParams.
-  bool forwarded_by_proxy = 6;
-
-  // HostParams holds parameters that are specific to host joining and
-  // irrelevant to bot joining.
-  message HostParams {
-    // HostName is the user-friendly node name for the host. This comes from
-    // teleport.nodename in the service configuration and defaults to the
-    // hostname. It is encoded as a valid principal in issued certificates.
-    string host_name = 1;
-    // AdditionalPrincipals is a list of additional principals requested.
-    repeated string additional_principals = 2;
-    // DnsNames is a list of DNS names requested for inclusion in the x509 certificate.
-    repeated string dns_names = 3;
-  }
-  optional HostParams host_params = 7;
-
-  // BotParams holds parameters that are specific to bot joining and irrelevant
-  // to host joining.
-  message BotParams {
-    // Expires is a desired time of the expiry of the returned certificates.
-    optional google.protobuf.Timestamp expires = 9;
-  }
-  optional BotParams bot_params = 8;
+  bool forwarded_by_proxy = 4;
 
   // ProxySuppliedParams holds parameters set by the Proxy when nodes join
   // via the proxy address. They must only be trusted if the incoming join
@@ -78,13 +50,68 @@ message ClientInit {
     // ClientVersion is the Teleport version of the client attempting to join.
     string client_version = 2;
   }
-  optional ProxySuppliedParams proxy_supplied_parameters = 9;
+  optional ProxySuppliedParams proxy_supplied_parameters = 5;
+}
+
+// PublicKeys holds public keys sent by the client requested subject keys for
+// issued certificates.
+message PublicKeys {
+  // PublicTlsKey is the public key requested for the subject of the x509 certificate.
+  // It must be encoded in PKIX, ASN.1 DER form.
+  bytes public_tls_key = 1;
+  // PublicSshKey is the public key requested for the subject of the SSH certificate.
+  // It must be encoded in SSH wire format.
+  bytes public_ssh_key = 2;
+}
+
+// HostParams holds parameters required for host joining.
+message HostParams {
+  // PublicKeys holds the host public keys.
+  PublicKeys public_keys = 1;
+  // HostName is the user-friendly node name for the host. This comes from
+  // teleport.nodename in the service configuration and defaults to the
+  // hostname. It is encoded as a valid principal in issued certificates.
+  string host_name = 2;
+  // AdditionalPrincipals is a list of additional principals requested.
+  repeated string additional_principals = 3;
+  // DnsNames is a list of DNS names requested for inclusion in the x509 certificate.
+  repeated string dns_names = 4;
+}
+
+// BotParams holds parameters required for bot joining.
+message BotParams {
+  // PublicKeys holds the bot public keys.
+  PublicKeys public_keys = 1;
+  // Expires is a desired time of the expiry of the returned certificates.
+  optional google.protobuf.Timestamp expires = 2;
+}
+
+// ClientParams holds either host or bot join parameters.
+message ClientParams {
+  oneof payload {
+    HostParams host_params = 1;
+    BotParams bot_params = 2;
+  }
+}
+
+// TokenInit is sent by the client in response to the ServerInit message for
+// the Token join method.
+//
+// The Token method join flow is:
+// 1. client->server: ClientInit
+// 2. server->client: ServerInit
+// 3. client->server: TokenInit
+// 4. server->client: Result
+message TokenInit {
+  // ClientParams holds parameters for the specific type of client trying to join.
+  ClientParams client_params = 1;
 }
 
 // JoinRequest is the message type sent from the joining client to the server.
 message JoinRequest {
   oneof payload {
     ClientInit client_init = 1;
+    TokenInit token_init = 2;
   }
 }
 
@@ -93,6 +120,9 @@ message JoinRequest {
 message ServerInit {
   // JoinMethod is the name of the selected join method.
   string join_method = 1;
+  // SignatureAlgorithmSuite is the name of the signature algorithm suite
+  // currently configured for the cluster.
+  string signature_algorithm_suite = 2;
 }
 
 // Challenge is a challenge message sent from the server that the client must solve.
@@ -102,18 +132,38 @@ message Challenge {}
 // contains the result of the joining process including the assigned host ID
 // and issued certificates.
 message Result {
+  oneof payload {
+    HostResult host_result = 1;
+    BotResult bot_result = 2;
+  }
+}
+
+// Certificates holds issued certificates and cluster CAs.
+message Certificates {
   // TlsCert is an X.509 certificate encoded in ASN.1 DER form.
   bytes tls_cert = 1;
-  // TlsCaCerts is a list of TLS certificate authorities that the agent should trust.
+  // TlsCaCerts is a list of TLS certificate authorities that the client should trust.
   // Each certificate is encoding in ASN.1 DER form.
   repeated bytes tls_ca_certs = 2;
   // SshCert is an SSH certificate encoded in SSH wire format.
   bytes ssh_cert = 3;
-  // SshCaKey is a list of SSH certificate authority public keys that the agent should trust.
+  // SshCaKey is a list of SSH certificate authority public keys that the client should trust.
   // Each CA key is encoded in SSH wire format.
   repeated bytes ssh_ca_keys = 4;
+}
+
+// HostResult holds results for host joining.
+message HostResult {
+  // Certificates holds issued certificates and cluster CAs.
+  Certificates certificates = 1;
   // HostId is the unique ID assigned to the host.
-  optional string host_id = 5;
+  string host_id = 2;
+}
+
+// HostResult holds results for bot joining.
+message BotResult {
+  // Certificates holds issued certificates and cluster CAs.
+  Certificates certificates = 1;
 }
 
 // JoinResponse is the message type sent from the server to the joining client.
@@ -163,7 +213,7 @@ service JoinService {
   // The client must send an ClientInit message on the JoinRequest stream to
   // initiate the join flow.
   //
-  // The server will reply with a JoinResponse where the payload will vary
-  // based on the join method specified in the provision token.
+  // The server will reply with a ServerInit message, and subsequent messages
+  // on the stream will depend on the join method.
   rpc Join(stream JoinRequest) returns (stream JoinResponse);
 }

api/gen/proto/go/teleport/join/v1/joinservice_grpc.pb.go

@@ -20,23 +20,35 @@ import (
 	"github.com/gravitational/trace"
 )
 
-// MarshalText marshals a SignatureAlgorithmSuite value to text. This gets used
-// by json.Marshal.
-func (s SignatureAlgorithmSuite) MarshalText() ([]byte, error) {
+// SignatureAlgorithmSuiteToString converts a [SignatureAlgorithmSuite] to a user-friendly string.
+func SignatureAlgorithmSuiteToString(s SignatureAlgorithmSuite) string {
 	switch s {
 	case SignatureAlgorithmSuite_SIGNATURE_ALGORITHM_SUITE_LEGACY:
-		return []byte("legacy"), nil
+		return "legacy"
 	case SignatureAlgorithmSuite_SIGNATURE_ALGORITHM_SUITE_BALANCED_V1:
-		return []byte("balanced-v1"), nil
+		return "balanced-v1"
 	case SignatureAlgorithmSuite_SIGNATURE_ALGORITHM_SUITE_FIPS_V1:
-		return []byte("fips-v1"), nil
+		return "fips-v1"
 	case SignatureAlgorithmSuite_SIGNATURE_ALGORITHM_SUITE_HSM_V1:
-		return []byte("hsm-v1"), nil
+		return "hsm-v1"
 	default:
-		return []byte(s.String()), nil
+		return s.String()
 	}
 }
 
+// SignatureAlgorithmSuiteFromString parses a string to return a [SignatureAlgorithmSuite].
+func SignatureAlgorithmSuiteFromString(str string) (SignatureAlgorithmSuite, error) {
+	var suite SignatureAlgorithmSuite
+	err := suite.UnmarshalText([]byte(str))
+	return suite, trace.Wrap(err)
+}
+
+// MarshalText marshals a SignatureAlgorithmSuite value to text. This gets used
+// by json.Marshal.
+func (s SignatureAlgorithmSuite) MarshalText() ([]byte, error) {
+	return []byte(SignatureAlgorithmSuiteToString(s)), nil
+}
+
 // UnmarshalJSON unmarshals a SignatureAlgorithmSuite and supports the custom
 // string format or numeric types matching an enum value.
 func (s *SignatureAlgorithmSuite) UnmarshalJSON(data []byte) error {

api/proto/teleport/join/v1/joinservice.proto

@@ -86,6 +86,8 @@ breaking:
   ignore:
     # TODO(codingllama): Remove ignore once the PDP API is stable.
     - api/proto/teleport/decision/v1alpha1
+    # TODO(nklaassen): Remove ignore once the new join API is stable.
+    - api/proto/teleport/join/v1
 
 plugins:
   - plugin: