GitHub proxy part 5: OAuth flow to retrieve GitHub identity (#49849)

* GitHub proxy part 5: OAuth flow to retrieve GitHub identity

* review comments round1

* review comments round 2 and update tsh git list

* make -C integrations/operator crd

* make -C integrations/terraform docs

* fix flaky test

api/client/gitserver/gitserver.go

@@ -123,3 +123,12 @@ func (c *Client) DeleteGitServer(ctx context.Context, name string) error {
 func (c *Client) DeleteAllGitServers(ctx context.Context) error {
 	return trace.NotImplemented("DeleteAllGitServers servers not implemented")
 }
+
+// CreateGitHubAuthRequest starts GitHub OAuth flow for authenticated user.
+func (c *Client) CreateGitHubAuthRequest(ctx context.Context, req *types.GithubAuthRequest, org string) (*types.GithubAuthRequest, error) {
+	resp, err := c.grpcClient.CreateGitHubAuthRequest(ctx, &gitserverv1.CreateGitHubAuthRequestRequest{
+		Request:      req,
+		Organization: org,
+	})
+	return resp, trace.Wrap(err)
+}

api/proto/teleport/gitserver/v1/git_server_service.proto

@@ -35,6 +35,9 @@ service GitServerService {
   rpc UpsertGitServer(UpsertGitServerRequest) returns (types.ServerV2);
   // DeleteGitServer is used to delete a Git server object.
   rpc DeleteGitServer(DeleteGitServerRequest) returns (google.protobuf.Empty);
+
+  // CreateGitHubAuthRequest starts GitHub OAuth flow for authenticated user.
+  rpc CreateGitHubAuthRequest(CreateGitHubAuthRequestRequest) returns (types.GithubAuthRequest);
 }
 
 // CreateGitServerRequest is a request to create a Git server.
@@ -84,3 +87,11 @@ message DeleteGitServerRequest {
   // Name is the uuid of the server.
   string name = 1;
 }
+
+// CreateGitHubAuthRequestRequest is the request for CreateGitHubAuthRequest.
+message CreateGitHubAuthRequestRequest {
+  // Request is the basic GitHub auth request.
+  types.GithubAuthRequest request = 1;
+  // Organization is the GitHub organization that the user is accessing.
+  string organization = 2;
+}

api/proto/teleport/legacy/types/types.proto

@@ -3873,6 +3873,10 @@ message ExternalIdentity {
 
   // SAMLSingleLogoutURL is the SAML Single log-out URL to initiate SAML SLO (single log-out), if applicable.
   string SAMLSingleLogoutURL = 3 [(gogoproto.jsontag) = "samlSingleLogoutUrl,omitempty"];
+
+  // UserID is the ID of the identity. Some connectors like GitHub have an
+  // unique ID apart from the username.
+  string UserID = 4 [(gogoproto.jsontag) = "user_id,omitempty"];
 }
 
 // LoginStatus is a login status of the user
@@ -5250,7 +5254,7 @@ message GithubAuthRequest {
   string KubernetesCluster = 13 [(gogoproto.jsontag) = "kubernetes_cluster,omitempty"];
   // SSOTestFlow indicates if the request is part of the test flow.
   bool SSOTestFlow = 14 [(gogoproto.jsontag) = "sso_test_flow"];
-  // ConnectorSpec is embedded connector spec for use in test flow.
+  // ConnectorSpec is embedded connector spec for use in test flow or authenticated user flow.
   GithubConnectorSpecV3 ConnectorSpec = 15 [(gogoproto.jsontag) = "connector_spec,omitempty"];
   // AttestationStatement is an attestation statement for the given public key.
   //
@@ -5274,6 +5278,10 @@ message GithubAuthRequest {
   teleport.attestation.v1.AttestationStatement ssh_attestation_statement = 21 [(gogoproto.jsontag) = "ssh_attestation_statement,omitempty"];
   // TlsAttestationStatement is an attestation statement for the given TLS public key.
   teleport.attestation.v1.AttestationStatement tls_attestation_statement = 22 [(gogoproto.jsontag) = "tls_attestation_statement,omitempty"];
+  // AuthenticatedUser is the username of an authenticated Teleport user. This
+  // OAuth flow is used to retrieve GitHub identity info which will be added to
+  // the existing user.
+  string authenticated_user = 23 [(gogoproto.jsontag) = "authenticated_user,omitempty"];
 }
 
 // SSOWarnings conveys a user-facing main message along with auxiliary warnings.
@@ -5444,6 +5452,12 @@ message GithubClaims {
 
   // Teams is the users team membership
   repeated string Teams = 3 [(gogoproto.jsontag) = "teams"];
+
+  // UserID is a global unique integer that is assigned to each GitHub user. The
+  // user ID is immutable (unlike the GitHub username) and can be found in APIs
+  // like get user.
+  // https://docs.github.com/en/rest/users/users
+  string UserID = 4 [(gogoproto.jsontag) = "user_id,omitempty"];
 }
 
 // TeamMapping represents a single team membership mapping.

api/proto/teleport/userloginstate/v1/userloginstate.proto

@@ -48,4 +48,16 @@ message Spec {
   // original_traits are the user traits that are part of the user's static definition. These traits are
   // not affected by access granted by access lists and are obtained prior to granting access list access.
   repeated teleport.trait.v1.Trait original_traits = 5;
+
+  // GitHubIdentity is the external identity attached to this user state.
+  ExternalIdentity git_hub_identity = 6;
+}
+
+// ExternalIdentity defines an external identity attached to this user state.
+message ExternalIdentity {
+  // UserId is the unique identifier of the external identity such as GitHub user
+  // ID.
+  string user_id = 1;
+  // Username is the username of the external identity.
+  string username = 2;
 }