feat(auth): add ExtraAudience option to RoundTripper

Add ExtraAudience option to RoundTripper to allow operators to include
additional audiences (e.g., provisioning group) when connecting to the
multitenant aggregator. This ensures tokens include both the target API
server's audience and the provisioning group audience, which is required
to pass the enforceManagerProperties check.

- Add ExtraAudience RoundTripperOption
- Improve documentation and comments
- Add comprehensive test coverage

apps/provisioning/pkg/auth/round_tripper.go

@@ -1,3 +1,4 @@
+// Package auth provides authentication utilities for the provisioning API.
 package auth
 
 import (
@@ -6,7 +7,6 @@ import (
 	"net/http"
 
 	"github.com/grafana/authlib/authn"
-	"github.com/grafana/grafana/apps/provisioning/pkg/apis/provisioning/v0alpha1"
 	utilnet "k8s.io/apimachinery/pkg/util/net"
 )
 
@@ -15,29 +15,61 @@ type tokenExchanger interface {
 	Exchange(ctx context.Context, req authn.TokenExchangeRequest) (*authn.TokenExchangeResponse, error)
 }
 
-// RoundTripper injects an exchanged access token for the provisioning API into outgoing requests.
-type RoundTripper struct {
-	client    tokenExchanger
-	transport http.RoundTripper
-	audience  string
+// RoundTripperOption configures optional behavior for the RoundTripper.
+type RoundTripperOption func(*RoundTripper)
+
+// ExtraAudience appends an additional audience to the token exchange request.
+//
+// This is primarily used by operators connecting to the multitenant aggregator,
+// where the token must include both the target API server's audience (e.g., dashboards,
+// folders) and the provisioning group audience. The provisioning group audience is
+// required so that the token passes the enforceManagerProperties check, which prevents
+// unauthorized updates to provisioned resources.
+//
+// Example:
+//
+//	authrt.NewRoundTripper(client, rt, "dashboards.grafana.app", authrt.ExtraAudience("provisioning.grafana.app"))
+func ExtraAudience(audience string) RoundTripperOption {
+	return func(rt *RoundTripper) {
+		rt.extraAudience = audience
+	}
 }
 
-// NewRoundTripper constructs a RoundTripper that exchanges the provided token per request
-// and forwards the request to the provided base transport.
-func NewRoundTripper(tokenExchangeClient tokenExchanger, base http.RoundTripper, audience string) *RoundTripper {
-	return &RoundTripper{
+// RoundTripper is an http.RoundTripper that performs token exchange before each request.
+// It exchanges the service's credentials for an access token scoped to the configured
+// audience(s), then injects that token into the outgoing request's X-Access-Token header.
+type RoundTripper struct {
+	client        tokenExchanger
+	transport     http.RoundTripper
+	audience      string
+	extraAudience string
+}
+
+// NewRoundTripper creates a RoundTripper that exchanges tokens for each outgoing request.
+//
+// Parameters:
+//   - tokenExchangeClient: the client used to exchange credentials for access tokens
+//   - base: the underlying transport to delegate requests to after token injection
+//   - audience: the primary audience for the token (typically the target API server's group)
+//   - opts: optional configuration (e.g., ExtraAudience to include additional audiences)
+func NewRoundTripper(tokenExchangeClient tokenExchanger, base http.RoundTripper, audience string, opts ...RoundTripperOption) *RoundTripper {
+	rt := &RoundTripper{
 		client:    tokenExchangeClient,
 		transport: base,
 		audience:  audience,
 	}
+	for _, opt := range opts {
+		opt(rt)
+	}
+	return rt
 }
 
+// RoundTrip exchanges credentials for an access token and injects it into the request.
+// The token is scoped to all configured audiences and the wildcard namespace ("*").
 func (t *RoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
-	// when we want to write resources with the provisioning API, the audience needs to include provisioning
-	// so that it passes the check in enforceManagerProperties, which prevents others from updating provisioned resources
 	audiences := []string{t.audience}
-	if t.audience != v0alpha1.GROUP {
-		audiences = append(audiences, v0alpha1.GROUP)
+	if t.extraAudience != "" && t.extraAudience != t.audience {
+		audiences = append(audiences, t.extraAudience)
 	}
 
 	tokenResponse, err := t.client.Exchange(req.Context(), authn.TokenExchangeRequest{

apps/provisioning/pkg/auth/round_tripper_test.go

@@ -71,16 +71,29 @@ func TestRoundTripper_AudiencesAndNamespace(t *testing.T) {
 	tests := []struct {
 		name          string
 		audience      string
+		extraAudience string
 		wantAudiences []string
 	}{
 		{
-			name:          "adds group when custom audience",
+			name:          "uses only provided audience by default",
 			audience:      "example-audience",
+			wantAudiences: []string{"example-audience"},
+		},
+		{
+			name:          "uses only group audience by default",
+			audience:      v0alpha1.GROUP,
+			wantAudiences: []string{v0alpha1.GROUP},
+		},
+		{
+			name:          "extra audience adds provisioning group",
+			audience:      "example-audience",
+			extraAudience: v0alpha1.GROUP,
 			wantAudiences: []string{"example-audience", v0alpha1.GROUP},
 		},
 		{
-			name:          "no duplicate when group audience",
+			name:          "extra audience no duplicate when same as primary",
 			audience:      v0alpha1.GROUP,
+			extraAudience: v0alpha1.GROUP,
 			wantAudiences: []string{v0alpha1.GROUP},
 		},
 	}
@@ -88,11 +101,15 @@ func TestRoundTripper_AudiencesAndNamespace(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			fx := &fakeExchanger{resp: &authn.TokenExchangeResponse{Token: "abc123"}}
+			var opts []RoundTripperOption
+			if tt.extraAudience != "" {
+				opts = append(opts, ExtraAudience(tt.extraAudience))
+			}
 			tr := NewRoundTripper(fx, roundTripperFunc(func(_ *http.Request) (*http.Response, error) {
 				rr := httptest.NewRecorder()
 				rr.WriteHeader(http.StatusOK)
 				return rr.Result(), nil
-			}), tt.audience)
+			}), tt.audience, opts...)
 
 			req, _ := http.NewRequestWithContext(context.Background(), http.MethodGet, "http://example", nil)
 			resp, err := tr.RoundTrip(req)