GitLab Delegated Joining (#22705)

* Add type for GitLab ProvisionToken

* Add default behaviour for domain

* Add IDTokenClaims for GitLab

* Add gitlab token source and token validator

* Thread GitLab support through auth and tbot packages

* Adjust cluster name fetching in token validator

* Initialize GitLab token validator in auth

* Improve comment on `sub`

* Working GitLab CI delegated joining

* Add additional token rule fields

* Add checking for new configuration fields

* add additional test cases for validation of gitlab config struct

* Add TestAuth_RegisterUsingToken_GitLab

* Add tests for IDTokenSource

* Fix imports

* Add tests for GitLab Token Validator

* Fix some comments that were incomplete

* Add license headers

lib/gitlab/gitlab.go

@@ -0,0 +1,96 @@
+/*
+Copyright 2023 Gravitational, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+	http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package gitlab
+
+import (
+	"github.com/gravitational/trace"
+	"github.com/mitchellh/mapstructure"
+)
+
+// GitLab Workload Identity
+//
+// GL provides workloads with the ID token in an environment variable included
+// in the workflow config, with the specified audience:
+//
+// ```yaml
+// job-name:
+//  id_tokens:
+//    TBOT_GITLAB_JWT:
+//      aud: https://teleport.example.com
+// ```
+//
+// We will require the user to configure this to be `TBOT_GITLAB_JWT` and to
+// set this value to the name of their Teleport cluster.
+//
+// Valuable reference:
+// - https://docs.gitlab.com/ee/ci/secrets/id_token_authentication.html
+// - https://docs.gitlab.com/ee/ci/cloud_services/
+// - https://docs.gitlab.com/ee/ci/yaml/index.html#id_tokens
+//
+// The GitLab issuer's well-known OIDC document is at
+// https://gitlab.com/.well-known/openid-configuration
+// For GitLab self-hosted servers, this will be at
+// https://$HOSTNAME/.well-known/openid-configuration
+
+// IDTokenClaims is the structure of claims contained within a GitLab issued
+// ID token.
+//
+// See the following for the structure:
+// https://docs.gitlab.com/ee/ci/cloud_services/#how-it-works
+type IDTokenClaims struct {
+	// Sub roughly uniquely identifies the workload. Example:
+	// `project_path:mygroup/my-project:ref_type:branch:ref:main`
+	// project_path:{group}/{project}:ref_type:{type}:ref:{branch_name}
+	Sub string `json:"sub"`
+	// Git ref for this job
+	Ref string `json:"ref"`
+	// Git ref type. Example:
+	// `branch` or `tag`
+	RefType string `json:"ref_type"`
+	// Use this to scope to group or user level namespace by path. Example:
+	// `mygroup`
+	NamespacePath string `json:"namespace_path"`
+	// Use this to scope to project by path. Example:
+	// `mygroup/myproject`
+	ProjectPath string `json:"project_path"`
+	// Username of the user executing the job
+	UserLogin string `json:"user_login"`
+	// Pipeline source.
+	// https://docs.gitlab.com/ee/ci/jobs/job_control.html#common-if-clauses-for-rules
+	// Example: `web`
+	PipelineSource string `json:"pipeline_source"`
+	// Environment this job deploys to (if one is associated)
+	Environment string `json:"environment"`
+}
+
+// JoinAuditAttributes returns a series of attributes that can be inserted into
+// audit events related to a specific join.
+func (c *IDTokenClaims) JoinAuditAttributes() (map[string]interface{}, error) {
+	res := map[string]interface{}{}
+	d, err := mapstructure.NewDecoder(&mapstructure.DecoderConfig{
+		TagName: "json",
+		Result:  &res,
+	})
+	if err != nil {
+		return nil, trace.Wrap(err)
+	}
+
+	if err := d.Decode(c); err != nil {
+		return nil, trace.Wrap(err)
+	}
+	return res, nil
+}

lib/gitlab/token_source.go

@@ -0,0 +1,44 @@
+/*
+Copyright 2023 Gravitational, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package gitlab
+
+import "github.com/gravitational/trace"
+
+type envGetter func(key string) string
+
+// IDTokenSource allows a GitLab ID token to be fetched whilst executing
+// within the context of a GitLab actions workflow.
+type IDTokenSource struct {
+	getEnv envGetter
+}
+
+func (its *IDTokenSource) GetIDToken() (string, error) {
+	tok := its.getEnv("TBOT_GITLAB_JWT")
+	if tok == "" {
+		return "", trace.BadParameter(
+			"TBOT_GITLAB_JWT environment variable missing",
+		)
+	}
+
+	return tok, nil
+}
+
+func NewIDTokenSource(getEnv envGetter) *IDTokenSource {
+	return &IDTokenSource{
+		getEnv,
+	}
+}

lib/gitlab/token_source_test.go

@@ -0,0 +1,52 @@
+/*
+Copyright 2023 Gravitational, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package gitlab
+
+import (
+	"testing"
+
+	"github.com/gravitational/trace"
+	"github.com/stretchr/testify/require"
+)
+
+func TestIDTokenSource_GetIDToken(t *testing.T) {
+	t.Run("value present", func(t *testing.T) {
+		its := &IDTokenSource{
+			getEnv: func(key string) string {
+				if key == "TBOT_GITLAB_JWT" {
+					return "foo"
+				}
+				return ""
+			},
+		}
+		tok, err := its.GetIDToken()
+		require.NoError(t, err)
+		require.Equal(t, "foo", tok)
+	})
+
+	t.Run("value missing", func(t *testing.T) {
+		its := &IDTokenSource{
+			getEnv: func(key string) string {
+				return ""
+			},
+		}
+		tok, err := its.GetIDToken()
+		require.Error(t, err)
+		require.True(t, trace.IsBadParameter(err))
+		require.Equal(t, "", tok)
+	})
+}

lib/gitlab/token_validator.go

@@ -0,0 +1,169 @@
+/*
+Copyright 2023 Gravitational, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package gitlab
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/coreos/go-oidc"
+	"github.com/gravitational/trace"
+	"github.com/jonboulle/clockwork"
+
+	"github.com/gravitational/teleport/api/types"
+	"github.com/gravitational/teleport/lib/services"
+)
+
+type clusterNameGetter interface {
+	GetClusterName(opts ...services.MarshalOption) (types.ClusterName, error)
+}
+
+type IDTokenValidatorConfig struct {
+	// Clock is used by the validator when checking expiry and issuer times of
+	// tokens. If omitted, a real clock will be used.
+	Clock clockwork.Clock
+	// ClusterNameGetter is used to get the cluster name in order to identify
+	// the correct audience for the token.
+	ClusterNameGetter clusterNameGetter
+	// insecure configures the validator to use HTTP rather than HTTPS. This
+	// is not exported as this is only used in the test for now.
+	insecure bool
+}
+
+type IDTokenValidator struct {
+	IDTokenValidatorConfig
+}
+
+func NewIDTokenValidator(
+	cfg IDTokenValidatorConfig,
+) (*IDTokenValidator, error) {
+	if cfg.Clock == nil {
+		cfg.Clock = clockwork.NewRealClock()
+	}
+
+	if cfg.ClusterNameGetter == nil {
+		return nil, trace.BadParameter(
+			"ClusterNameGetter must be configured",
+		)
+	}
+
+	return &IDTokenValidator{
+		IDTokenValidatorConfig: cfg,
+	}, nil
+}
+
+func (id *IDTokenValidator) issuerURL(domain string) string {
+	scheme := "https"
+	if id.insecure {
+		scheme = "http"
+	}
+
+	return fmt.Sprintf("%s://%s", scheme, domain)
+}
+
+func (id *IDTokenValidator) Validate(
+	ctx context.Context, domain string, token string,
+) (*IDTokenClaims, error) {
+	p, err := oidc.NewProvider(
+		ctx,
+		id.issuerURL(domain),
+	)
+	if err != nil {
+		return nil, trace.Wrap(err)
+	}
+
+	clusterNameResource, err := id.ClusterNameGetter.GetClusterName()
+	if err != nil {
+		return nil, err
+	}
+
+	verifier := p.Verifier(&oidc.Config{
+		ClientID: clusterNameResource.GetClusterName(),
+		Now:      id.Clock.Now,
+	})
+
+	idToken, err := verifier.Verify(ctx, token)
+	if err != nil {
+		return nil, trace.Wrap(err)
+	}
+
+	// `go-oidc` does not implement not before check, so we need to manually
+	// perform this
+	if err := checkNotBefore(
+		id.Clock.Now(), time.Minute*2, idToken,
+	); err != nil {
+		return nil, trace.Wrap(err)
+	}
+
+	claims := IDTokenClaims{}
+	if err := idToken.Claims(&claims); err != nil {
+		return nil, trace.Wrap(err)
+	}
+	return &claims, nil
+}
+
+// checkNotBefore ensures the token was not issued in the future.
+// https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5
+// 4.1.5.  "nbf" (Not Before) Claim
+// TODO(strideynet): upstream support for `nbf` into the go-oidc lib.
+func checkNotBefore(
+	now time.Time, leeway time.Duration, token *oidc.IDToken,
+) error {
+	claims := struct {
+		NotBefore *jsonTime `json:"nbf"`
+	}{}
+	if err := token.Claims(&claims); err != nil {
+		return trace.Wrap(err)
+	}
+
+	if claims.NotBefore != nil {
+		adjustedNow := now.Add(leeway)
+		nbf := time.Time(*claims.NotBefore)
+		if adjustedNow.Before(nbf) {
+			return trace.AccessDenied("token not before in future")
+		}
+	}
+
+	return nil
+}
+
+// jsonTime unmarshaling sourced from
+// https://github.com/gravitational/go-oidc/blob/master/oidc.go#L295
+// TODO(strideynet): upstream support for `nbf` into the go-oidc lib.
+type jsonTime time.Time
+
+func (j *jsonTime) UnmarshalJSON(b []byte) error {
+	var n json.Number
+	if err := json.Unmarshal(b, &n); err != nil {
+		return err
+	}
+	var unix int64
+
+	if t, err := n.Int64(); err == nil {
+		unix = t
+	} else {
+		f, err := n.Float64()
+		if err != nil {
+			return err
+		}
+		unix = int64(f)
+	}
+	*j = jsonTime(time.Unix(unix, 0))
+	return nil
+}

lib/gitlab/token_validator_test.go

@@ -0,0 +1,261 @@
+/*
+Copyright 2022 Gravitational, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package gitlab
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/rsa"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jonboulle/clockwork"
+	"github.com/stretchr/testify/require"
+	"gopkg.in/square/go-jose.v2"
+	"gopkg.in/square/go-jose.v2/jwt"
+
+	"github.com/gravitational/teleport/api/types"
+	"github.com/gravitational/teleport/lib/services"
+)
+
+type fakeIDP struct {
+	t          *testing.T
+	signer     jose.Signer
+	privateKey *rsa.PrivateKey
+	server     *httptest.Server
+}
+
+func newFakeIDP(t *testing.T) *fakeIDP {
+	privateKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	require.NoError(t, err)
+
+	signer, err := jose.NewSigner(
+		jose.SigningKey{Algorithm: jose.RS256, Key: privateKey},
+		(&jose.SignerOptions{}).WithType("JWT"),
+	)
+	require.NoError(t, err)
+
+	f := &fakeIDP{
+		signer:     signer,
+		privateKey: privateKey,
+		t:          t,
+	}
+
+	providerMux := http.NewServeMux()
+	providerMux.HandleFunc(
+		"/.well-known/openid-configuration",
+		f.handleOpenIDConfig,
+	)
+	providerMux.HandleFunc(
+		"/oauth/discovery/keys",
+		f.handleJWKSEndpoint,
+	)
+
+	srv := httptest.NewServer(providerMux)
+	t.Cleanup(srv.Close)
+	f.server = srv
+	return f
+}
+
+func (f *fakeIDP) issuer() string {
+	return f.server.URL
+}
+
+func (f *fakeIDP) handleOpenIDConfig(w http.ResponseWriter, r *http.Request) {
+	// mimic https://gitlab.com/.well-known/openid-configuration
+	response := map[string]interface{}{
+		"claims_supported": []string{
+			"sub",
+			"aud",
+			"exp",
+			"iat",
+			"iss",
+			"jti",
+			"nbf",
+		},
+		"id_token_signing_alg_values_supported": []string{"RS256"},
+		"issuer":                                f.issuer(),
+		"jwks_uri":                              f.issuer() + "/oauth/discovery/keys",
+		"response_types_supported":              []string{"id_token"},
+		"scopes_supported":                      []string{"openid"},
+		"subject_types_supported":               []string{"public"},
+	}
+	responseBytes, err := json.Marshal(response)
+	require.NoError(f.t, err)
+	_, err = w.Write(responseBytes)
+	require.NoError(f.t, err)
+}
+
+func (f *fakeIDP) handleJWKSEndpoint(w http.ResponseWriter, r *http.Request) {
+	// mimic https://gitlab.com/oauth/discovery/keys
+	// but with our own keys
+	jwks := jose.JSONWebKeySet{
+		Keys: []jose.JSONWebKey{
+			{
+				Key: &f.privateKey.PublicKey,
+			},
+		},
+	}
+	responseBytes, err := json.Marshal(jwks)
+	require.NoError(f.t, err)
+	_, err = w.Write(responseBytes)
+	require.NoError(f.t, err)
+}
+
+func (f *fakeIDP) issueToken(
+	t *testing.T,
+	issuer,
+	audience,
+	userLogin,
+	sub string,
+	issuedAt time.Time,
+	expiry time.Time,
+) string {
+	stdClaims := jwt.Claims{
+		Issuer:    issuer,
+		Subject:   sub,
+		Audience:  jwt.Audience{audience},
+		IssuedAt:  jwt.NewNumericDate(issuedAt),
+		NotBefore: jwt.NewNumericDate(issuedAt),
+		Expiry:    jwt.NewNumericDate(expiry),
+	}
+	customClaims := map[string]interface{}{
+		"user_login": userLogin,
+	}
+	token, err := jwt.Signed(f.signer).
+		Claims(stdClaims).
+		Claims(customClaims).
+		CompactSerialize()
+	require.NoError(t, err)
+
+	return token
+}
+
+type mockClusterNameGetter string
+
+func (m mockClusterNameGetter) GetClusterName(opts ...services.MarshalOption) (types.ClusterName, error) {
+	return types.NewClusterName(types.ClusterNameSpecV2{
+		ClusterID:   uuid.NewString(),
+		ClusterName: string(m),
+	})
+}
+
+func TestIDTokenValidator_Validate(t *testing.T) {
+	t.Parallel()
+	idp := newFakeIDP(t)
+	teleportClusterName := "teleport.example.com"
+
+	tests := []struct {
+		name        string
+		assertError require.ErrorAssertionFunc
+		want        *IDTokenClaims
+		token       string
+	}{
+		{
+			name:        "success",
+			assertError: require.NoError,
+			token: idp.issueToken(
+				t,
+				idp.issuer(),
+				teleportClusterName,
+				"unpetitchien",
+				"project_path:mygroup/my-project:ref_type:branch:ref:main",
+				time.Now().Add(-5*time.Minute),
+				time.Now().Add(5*time.Minute),
+			),
+			want: &IDTokenClaims{
+				UserLogin: "unpetitchien",
+				Sub:       "project_path:mygroup/my-project:ref_type:branch:ref:main",
+			},
+		},
+		{
+			name:        "expired",
+			assertError: require.Error,
+			token: idp.issueToken(
+				t,
+				idp.issuer(),
+				teleportClusterName,
+				"octocat",
+				"project_path:mygroup/my-project:ref_type:branch:ref:main",
+				time.Now().Add(-15*time.Minute),
+				time.Now().Add(-5*time.Minute),
+			),
+		},
+		{
+			name:        "future",
+			assertError: require.Error,
+			token: idp.issueToken(
+				t,
+				idp.issuer(),
+				teleportClusterName,
+				"octocat",
+				"project_path:mygroup/my-project:ref_type:branch:ref:main",
+				time.Now().Add(10*time.Minute),
+				time.Now().Add(20*time.Minute),
+			),
+		},
+		{
+			name:        "invalid audience",
+			assertError: require.Error,
+			token: idp.issueToken(
+				t,
+				idp.issuer(),
+				"wrong-teleport.example.com",
+				"octocat",
+				"project_path:mygroup/my-project:ref_type:branch:ref:main",
+				time.Now().Add(-5*time.Minute),
+				time.Now().Add(5*time.Minute),
+			),
+		},
+		{
+			name:        "invalid issuer",
+			assertError: require.Error,
+			token: idp.issueToken(
+				t,
+				"https://the.wrong.issuer",
+				teleportClusterName,
+				"octocat",
+				"project_path:mygroup/my-project:ref_type:branch:ref:main",
+				time.Now().Add(-5*time.Minute),
+				time.Now().Add(5*time.Minute),
+			),
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ctx := context.Background()
+			v, err := NewIDTokenValidator(IDTokenValidatorConfig{
+				Clock:             clockwork.NewRealClock(),
+				insecure:          true,
+				ClusterNameGetter: mockClusterNameGetter(teleportClusterName),
+			})
+			require.NoError(t, err)
+
+			claims, err := v.Validate(
+				ctx,
+				idp.server.Listener.Addr().String(),
+				tt.token,
+			)
+			tt.assertError(t, err)
+			require.Equal(t, tt.want, claims)
+		})
+	}
+}