feat: use JWT bearer token for self agent registration

Assisted by: Cursor

Signed-off-by: Jayendra Parsai <jparsai@redhat.com>

Author: jparsai

cmd/argocd-agent/principal.go

@@ -99,8 +99,8 @@ func NewPrincipalRunCommand() *cobra.Command {
 		otlpAddress  string
 		otlpInsecure bool
 
-		enableSelfClusterRegistration     bool
-		selfClusterRegistrationSharedCert string
+		enableSelfClusterRegistration bool
+		selfRegClientCertSecretName   string
 	)
 	command := &cobra.Command{
 		Use:   "principal",
@@ -329,10 +329,18 @@ func NewPrincipalRunCommand() *cobra.Command {
 			opts = append(opts, principal.WithRedis(redisAddress, redisPassword, redisCompressionType))
 			opts = append(opts, principal.WithHealthzPort(healthzPort))
 
-			// Self cluster registration options
+			// Self cluster registration validation and options
+			if enableSelfClusterRegistration {
+				if selfRegClientCertSecretName == "" {
+					cmdutil.Fatal("Self cluster registration requires --self-reg-client-cert-secret to be set")
+				}
+				if !enableResourceProxy {
+					cmdutil.Fatal("Self cluster registration requires --enable-resource-proxy to be enabled")
+				}
+			}
 			opts = append(opts, principal.WithClusterRegistration(enableSelfClusterRegistration))
-			if selfClusterRegistrationSharedCert != "" {
-				opts = append(opts, principal.WithSelfClusterRegistrationSharedCert(selfClusterRegistrationSharedCert))
+			if selfRegClientCertSecretName != "" {
+				opts = append(opts, principal.WithClientCertSecretName(selfRegClientCertSecretName))
 			}
 
 			s, err := principal.NewServer(ctx, kubeConfig, namespace, opts...)
@@ -493,11 +501,10 @@ func NewPrincipalRunCommand() *cobra.Command {
 
 	command.Flags().BoolVar(&enableSelfClusterRegistration, "enable-self-cluster-registration",
 		env.BoolWithDefault("ARGOCD_PRINCIPAL_ENABLE_SELF_CLUSTER_REGISTRATION", false),
-		"Allow agents with valid client certificates to self-register on connection")
-
-	command.Flags().StringVar(&selfClusterRegistrationSharedCert, "self-cluster-registration-shared-cert",
-		env.StringWithDefault("ARGOCD_PRINCIPAL_SELF_CLUSTER_REGISTRATION_SHARED_CERT", nil, ""),
-		"Name of the TLS secret containing the shared client certificate for cluster secrets (requires ca.crt, tls.crt, tls.key)")
+		"Allow agents with valid credentials to self-register on connection (requires --self-reg-client-cert-secret)")
+	command.Flags().StringVar(&selfRegClientCertSecretName, "self-reg-client-cert-secret",
+		env.StringWithDefault("ARGOCD_PRINCIPAL_SELF_REG_CLIENT_CERT_SECRET", nil, ""),
+		"TLS secret containing shared client cert for self-registered cluster secrets (must have tls.crt, tls.key, ca.crt)")
 
 	return command
 }

hack/dev-env/start-principal.sh

@@ -45,11 +45,14 @@ if [ -f "$E2E_ENV_FILE" ]; then
     source "$E2E_ENV_FILE"
     export ARGOCD_PRINCIPAL_ENABLE_WEBSOCKET=${ARGOCD_PRINCIPAL_ENABLE_WEBSOCKET:-false}
     export ARGOCD_PRINCIPAL_ENABLE_SELF_CLUSTER_REGISTRATION=${ARGOCD_PRINCIPAL_ENABLE_SELF_CLUSTER_REGISTRATION:-false}
+    if [ -n "$ARGOCD_PRINCIPAL_SELF_REG_CLIENT_CERT_SECRET" ]; then
+        export ARGOCD_PRINCIPAL_SELF_REG_CLIENT_CERT_SECRET
+    fi
 fi
 
-export ARGOCD_AGENT_RESOURCE_PROXY=$(ip r show default | sed -e 's,.*\ src\ ,,' | sed -e 's,\ metric.*$,,')
+ARGOCD_AGENT_RESOURCE_PROXY=$(ip r show default | sed -e 's,.*\ src\ ,,' | sed -e 's,\ metric.*$,,')
+export ARGOCD_AGENT_RESOURCE_PROXY
 
-SCRIPTPATH="$( cd -- "$(dirname "$0")" >/dev/null 2>&1 ; pwd -P )"
 go run github.com/argoproj-labs/argocd-agent/cmd/argocd-agent principal \
 	--allowed-namespaces '*' \
 	--kubecontext vcluster-control-plane \

internal/argocd/cluster/cluster.go

@@ -16,21 +16,19 @@ package cluster
 
 import (
 	"context"
-	"crypto/x509"
 	"errors"
 	"fmt"
 	"time"
 
-	"github.com/argoproj-labs/argocd-agent/internal/config"
 	"github.com/argoproj-labs/argocd-agent/internal/event"
-	"github.com/argoproj-labs/argocd-agent/internal/tlsutil"
 	"github.com/redis/go-redis/v9"
 	"github.com/redis/go-redis/v9/maintnotifications"
 	"github.com/sirupsen/logrus"
 
 	appv1 "github.com/argoproj/argo-cd/v3/pkg/apis/application/v1alpha1"
 	cacheutil "github.com/argoproj/argo-cd/v3/util/cache"
 	appstatecache "github.com/argoproj/argo-cd/v3/util/cache/appstate"
+	"github.com/argoproj/argo-cd/v3/util/db"
 	v1 "k8s.io/api/core/v1"
 	apierrors "k8s.io/apimachinery/pkg/api/errors"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
@@ -191,36 +189,35 @@ func NewClusterCacheInstance(redisAddress, redisPassword string, redisCompressio
 	return clusterCache, nil
 }
 
-// CreateCluster creates a cluster secret for an agent's cluster on the principal.
-// If sharedClientCertSecretName is provided, it reads the TLS credentials from that secret
-// (shared client cert mode). Otherwise, it generates a new client certificate signed
-// by the principal's CA (legacy mode, requires CA private key).
-func CreateCluster(ctx context.Context, kubeclient kubernetes.Interface, namespace, agentName, resourceProxyAddress, sharedClientCertSecretName string) error {
-	var clientCert, clientKey, caData string
-	var err error
-
-	if sharedClientCertSecretName != "" {
-		// Shared client cert mode: read from existing secret
-		log().WithFields(logrus.Fields{
-			"agent":  agentName,
-			"secret": sharedClientCertSecretName,
-		}).Info("Using shared client certificate mode for cluster registration")
-
-		clientCert, clientKey, caData, err = readSharedClientCertFromSecret(ctx, kubeclient, namespace, sharedClientCertSecretName)
-		if err != nil {
-			return fmt.Errorf("could not read shared client certificate from secret %s: %v", sharedClientCertSecretName, err)
-		}
-	} else {
-		// Legacy mode: generate client certificate signed by principal's CA
-		log().WithField("agent", agentName).Info("Generating unique client certificate for cluster registration")
+// TokenIssuer is an interface for issuing resource proxy tokens.
+// This is a subset of the issuer.Issuer interface to avoid circular dependencies.
+type TokenIssuer interface {
+	IssueResourceProxyToken(agentName string) (string, error)
+}
 
-		clientCert, clientKey, caData, err = generateAgentClientCert(ctx, kubeclient, namespace, agentName, config.SecretNamePrincipalCA)
-		if err != nil {
-			return fmt.Errorf("could not generate client certificate: %v", err)
-		}
+// CreateClusterWithBearerToken creates a cluster secret for an agent using both mTLS and JWT bearer token authentication.
+// - The shared client certificate (mTLS) proves the request comes from a trusted ArgoCD server
+// - The JWT bearer token identifies which specific agent is being accessed
+func CreateClusterWithBearerToken(ctx context.Context, kubeclient kubernetes.Interface, namespace, agentName, resourceProxyAddress string, tokenIssuer TokenIssuer, clientCertSecretName string) error {
+	logCtx := log().WithField("agent", agentName).WithField("process", "self-registration")
+	logCtx.Info("Creating self-registered cluster secret with shared client cert and bearer token")
+
+	// Generate bearer token for this agent
+	bearerToken, err := tokenIssuer.IssueResourceProxyToken(agentName)
+	if err != nil {
+		logCtx.WithError(err).Error("Failed to issue resource proxy token")
+		return fmt.Errorf("could not issue resource proxy token: %v", err)
+	}
+	logCtx.Info("Successfully issued resource proxy token")
+
+	// Read shared client certificate for mTLS
+	clientCert, clientKey, caData, err := readClientCertFromSecret(ctx, kubeclient, namespace, clientCertSecretName)
+	if err != nil {
+		logCtx.WithError(err).Error("Failed to read client certificate from secret")
+		return fmt.Errorf("could not read client certificate from secret %s: %v", clientCertSecretName, err)
 	}
+	logCtx.Info("Successfully read client certificate from secret")
 
-	// Note: this structure has to be same as manual creation done by `argocd-agentctl agent create <agent_name>`
 	cluster := &appv1.Cluster{
 		Server: fmt.Sprintf("https://%s?agentName=%s", resourceProxyAddress, agentName),
 		Name:   agentName,
@@ -229,6 +226,7 @@ func CreateCluster(ctx context.Context, kubeclient kubernetes.Interface, namespa
 			LabelKeySelfRegisteredCluster: "true",
 		},
 		Config: appv1.ClusterConfig{
+			BearerToken: bearerToken,
 			TLSClientConfig: appv1.TLSClientConfig{
 				CertData: []byte(clientCert),
 				KeyData:  []byte(clientKey),
@@ -237,97 +235,140 @@ func CreateCluster(ctx context.Context, kubeclient kubernetes.Interface, namespa
 		},
 	}
 
-	// Convert cluster object to Kubernetes secret object
 	secret := &v1.Secret{
 		ObjectMeta: metav1.ObjectMeta{
 			Name:      getClusterSecretName(agentName),
 			Namespace: namespace,
 		},
 	}
 	if err := ClusterToSecret(cluster, secret); err != nil {
+		logCtx.WithError(err).Error("Failed to convert cluster to secret")
 		return fmt.Errorf("could not convert cluster to secret: %v", err)
 	}
 
-	// Create the secret to register the agent's cluster.
 	if _, err = kubeclient.CoreV1().Secrets(namespace).Create(ctx, secret, metav1.CreateOptions{}); err != nil {
 		if apierrors.IsAlreadyExists(err) {
+			logCtx.Info("Cluster secret already exists, skipping creation")
 			return nil
 		}
-		return fmt.Errorf("could not create cluster secret to register agent's cluster: %v", err)
+		logCtx.WithError(err).Error("Failed to create cluster secret")
+		return fmt.Errorf("could not create cluster secret: %w", err)
+	}
+
+	logCtx.Info("Successfully created cluster secret with shared client cert and bearer token")
+	return nil
+}
+
+// IsClusterSelfRegistered checks if a cluster secret was created by self-registration.
+func IsClusterSelfRegistered(ctx context.Context, kubeclient kubernetes.Interface, namespace, agentName string) (bool, error) {
+	secret, err := kubeclient.CoreV1().Secrets(namespace).Get(ctx, getClusterSecretName(agentName), metav1.GetOptions{})
+	if err != nil {
+		return false, err
+	}
+	return secret.Labels[LabelKeySelfRegisteredCluster] == "true", nil
+}
+
+// UpdateClusterBearerToken updates an existing cluster secret with a new bearer token.
+// This is used when the signing key rotates and existing tokens become invalid.
+func UpdateClusterBearerToken(ctx context.Context, kubeclient kubernetes.Interface, namespace, agentName string, tokenIssuer TokenIssuer) error {
+	logCtx := log().WithField("agent", agentName).WithField("process", "self-registration")
+	logCtx.Info("Updating cluster secret bearer token")
+
+	secretName := getClusterSecretName(agentName)
+
+	secret, err := kubeclient.CoreV1().Secrets(namespace).Get(ctx, secretName, metav1.GetOptions{})
+	if err != nil {
+		logCtx.WithError(err).Error("Failed to get cluster secret")
+		return fmt.Errorf("could not get cluster secret: %v", err)
+	}
+
+	cluster, err := db.SecretToCluster(secret)
+	if err != nil {
+		logCtx.WithError(err).Error("Failed to parse cluster secret")
+		return fmt.Errorf("could not parse cluster secret: %v", err)
+	}
+
+	// Generate new bearer token
+	bearerToken, err := tokenIssuer.IssueResourceProxyToken(agentName)
+	if err != nil {
+		logCtx.WithError(err).Error("Failed to issue new resource proxy token")
+		return fmt.Errorf("could not issue resource proxy token: %v", err)
+	}
+	logCtx.Info("Successfully issued new resource proxy token")
+
+	cluster.Config.BearerToken = bearerToken
+
+	if err := ClusterToSecret(cluster, secret); err != nil {
+		logCtx.WithError(err).Error("Failed to convert cluster to secret")
+		return fmt.Errorf("could not convert cluster to secret: %v", err)
+	}
+
+	if _, err = kubeclient.CoreV1().Secrets(namespace).Update(ctx, secret, metav1.UpdateOptions{}); err != nil {
+		logCtx.WithError(err).Error("Failed to update cluster secret")
+		return fmt.Errorf("could not update cluster secret: %v", err)
 	}
 
+	logCtx.Info("Successfully updated cluster secret bearer token")
 	return nil
 }
 
-// readSharedClientCertFromSecret reads TLS credentials from an existing Kubernetes TLS secret.
+// readClientCertFromSecret reads TLS credentials from an existing Kubernetes TLS secret.
 // The secret should contain tls.crt, tls.key, and ca.crt keys.
-func readSharedClientCertFromSecret(ctx context.Context, kubeclient kubernetes.Interface, namespace, sharedClientCertSecretName string) (clientCert, clientKey, caData string, err error) {
-	secret, err := kubeclient.CoreV1().Secrets(namespace).Get(ctx, sharedClientCertSecretName, metav1.GetOptions{})
+func readClientCertFromSecret(ctx context.Context, kubeclient kubernetes.Interface, namespace, secretName string) (clientCert, clientKey, caData string, err error) {
+	secret, err := kubeclient.CoreV1().Secrets(namespace).Get(ctx, secretName, metav1.GetOptions{})
 	if err != nil {
-		return "", "", "", fmt.Errorf("could not read TLS secret %s/%s: %v", namespace, sharedClientCertSecretName, err)
+		return "", "", "", fmt.Errorf("could not read TLS secret %s/%s: %w", namespace, secretName, err)
 	}
 
 	certData, ok := secret.Data["tls.crt"]
 	if !ok {
-		return "", "", "", fmt.Errorf("secret %s/%s missing tls.crt", namespace, sharedClientCertSecretName)
+		return "", "", "", fmt.Errorf("secret %s/%s missing tls.crt", namespace, secretName)
 	}
 
 	keyData, ok := secret.Data["tls.key"]
 	if !ok {
-		return "", "", "", fmt.Errorf("secret %s/%s missing tls.key", namespace, sharedClientCertSecretName)
+		return "", "", "", fmt.Errorf("secret %s/%s missing tls.key", namespace, secretName)
 	}
 
 	// CA cert can be in ca.crt (cert-manager style) or tls.crt of a separate CA secret
 	caBytes, ok := secret.Data["ca.crt"]
 	if !ok {
-		return "", "", "", fmt.Errorf("secret %s/%s missing ca.crt", namespace, sharedClientCertSecretName)
+		return "", "", "", fmt.Errorf("secret %s/%s missing ca.crt", namespace, secretName)
 	}
 
 	return string(certData), string(keyData), string(caBytes), nil
 }
 
-// ClusterSecretExists checks if a cluster secret exists for the given agent.
-func ClusterSecretExists(ctx context.Context, kubeclient kubernetes.Interface, namespace, agentName string) (bool, error) {
-	if _, err := kubeclient.CoreV1().Secrets(namespace).Get(ctx, getClusterSecretName(agentName), metav1.GetOptions{}); err != nil {
-		if apierrors.IsNotFound(err) {
-			return false, nil
-		}
-		return false, err
-	}
-	return true, nil
-}
-
-func generateAgentClientCert(ctx context.Context, kubeclient kubernetes.Interface, namespace, agentName, caSecretName string) (clientCert, clientKey, caData string, err error) {
+// GetClusterBearerToken retrieves the bearer token from an existing cluster secret.
+func GetClusterBearerToken(ctx context.Context, kubeclient kubernetes.Interface, namespace, agentName string) (string, error) {
+	logCtx := log().WithField("agent", agentName).WithField("process", "self-registration")
+	logCtx.Info("Retrieving bearer token from cluster secret")
 
-	// Read the CA certificate from the principal's CA secret
-	tlsCert, err := tlsutil.TLSCertFromSecret(ctx, kubeclient, namespace, caSecretName)
+	secretName := getClusterSecretName(agentName)
+	secret, err := kubeclient.CoreV1().Secrets(namespace).Get(ctx, secretName, metav1.GetOptions{})
 	if err != nil {
-		err = fmt.Errorf("could not read CA secret: %v", err)
-		return
+		logCtx.WithError(err).Info("Failed to get cluster secret")
+		return "", fmt.Errorf("could not get cluster secret: %v", err)
 	}
 
-	// Parse CA certificate from PEM format
-	signerCert, err := x509.ParseCertificate(tlsCert.Certificate[0])
+	cluster, err := db.SecretToCluster(secret)
 	if err != nil {
-		err = fmt.Errorf("could not parse CA certificate: %v", err)
-		return
+		logCtx.WithError(err).Error("Failed to parse cluster secret")
+		return "", fmt.Errorf("could not parse cluster secret: %v", err)
 	}
 
-	// Generate a client cert with agent name as CN and sign it with the CA's cert and key
-	clientCert, clientKey, err = tlsutil.GenerateClientCertificate(agentName, signerCert, tlsCert.PrivateKey)
-	if err != nil {
-		err = fmt.Errorf("could not create client cert: %v", err)
-		return
-	}
+	return cluster.Config.BearerToken, nil
+}
 
-	// Convert CA certificate to PEM format
-	caData, err = tlsutil.CertDataToPEM(tlsCert.Certificate[0])
-	if err != nil {
-		err = fmt.Errorf("could not convert CA certificate to PEM format: %v", err)
-		return
+// ClusterSecretExists checks if a cluster secret exists for the given agent.
+func ClusterSecretExists(ctx context.Context, kubeclient kubernetes.Interface, namespace, agentName string) (bool, error) {
+	if _, err := kubeclient.CoreV1().Secrets(namespace).Get(ctx, getClusterSecretName(agentName), metav1.GetOptions{}); err != nil {
+		if apierrors.IsNotFound(err) {
+			return false, nil
+		}
+		return false, err
 	}
-
-	return
+	return true, nil
 }
 
 func getClusterSecretName(agentName string) string {