Add Private Key JWT support for client credentials in Management API (#528)

Co-authored-by: Kunal Dawar <[email protected]>
Co-authored-by: Kunal Dawar <[email protected]>

Author: ErwinSteffens

EXAMPLES.md

@@ -1,11 +1,94 @@
 # Examples
 
+- [OAuth Client Credentials](#oauth-client-credentials)
 - [Request Options](#request-options)
 - [Pagination](#pagination)
   - [Page based pagination](#page-based-pagination)
   - [Checkpoint pagination](#checkpoint-pagination)
 - [Custom User Structs](#providing-a-custom-user-struct)
 
+## OAuth Client Credentials
+
+The SDK provides several ways to authenticate with Auth0 using OAuth client credentials.
+
+### Management API Initialization
+
+When initializing the Management API client, you can use these client credentials options:
+
+```go
+// Standard client credentials with client secret
+api, err := management.New(
+    "your-tenant.auth0.com",
+    management.WithClientCredentials(
+        context.Background(),
+        "YOUR_CLIENT_ID",
+        "YOUR_CLIENT_SECRET"
+    )
+)
+
+// Client credentials with custom audience
+api, err := management.New(
+    "your-tenant.auth0.com",
+    management.WithClientCredentialsAndAudience(
+        context.Background(),
+        "YOUR_CLIENT_ID",
+        "YOUR_CLIENT_SECRET",
+        "https://custom-api.example.com"
+    )
+)
+
+// Client credentials with Private Key JWT
+api, err := management.New(
+    "your-tenant.auth0.com",
+    management.WithClientCredentialsPrivateKeyJwt(
+        context.Background(),
+        "YOUR_CLIENT_ID",
+        privateKey,
+        "RS256"
+    )
+)
+
+// Private Key JWT with custom audience
+api, err := management.New(
+    "your-tenant.auth0.com",
+    management.WithClientCredentialsPrivateKeyJwtAndAudience(
+        context.Background(),
+        "YOUR_CLIENT_ID",
+        privateKey,
+        "RS256",
+        "https://custom-api.example.com"
+    )
+)
+
+// Using a pre-acquired static token
+api, err := management.New(
+    "your-tenant.auth0.com",
+    management.WithStaticToken("YOUR_ACCESS_TOKEN")
+)
+```
+
+### Authentication API Initialization
+
+For the Authentication API, use these initialization patterns:
+
+```go
+// With client secret authentication
+auth, err := authentication.New(
+    context.Background(),
+    "your-tenant.auth0.com",
+    authentication.WithClientID("YOUR_CLIENT_ID"),
+    authentication.WithClientSecret("YOUR_CLIENT_SECRET")
+)
+
+// With private key JWT authentication
+auth, err := authentication.New(
+    context.Background(),
+    "your-tenant.auth0.com",
+    authentication.WithClientID("YOUR_CLIENT_ID"),
+    authentication.WithClientAssertion(privateKey, "RS256")
+)
+```
+
 ## Request Options
 
 Fine-grained configuration can be provided on a per-request basis to enhance the request with specific query params, headers, or to pass it a custom context.
@@ -42,7 +125,7 @@ This SDK supports both offset and checkpoint pagination.
 
 ### Page based pagination
 
-When retrieving lists of resources, if no query parameters are set using the `management.PerPage` and `Management.IncludeTotals` helper funcs, then the SDK will default to sending `per_page=50` and `include_totals=true`. 
+When retrieving lists of resources, if no query parameters are set using the `management.PerPage` and `Management.IncludeTotals` helper funcs, then the SDK will default to sending `per_page=50` and `include_totals=true`.
 
 > **Note**
 > The maximum value of the `per_page` query parameter is 100.
@@ -71,16 +154,17 @@ for {
     page++
 }
 ```
+
 </details>
 
 ### Checkpoint pagination
 
 Checkpoint pagination can be used when you wish to retrieve more than 1000 results from certain APIs. The APIs that support checkpoint based pagination are:
 
-* `Log.List` (`/api/v2/logs`)
-* `Organization.List` (`/api/v2/organizations`)
-* `Organization.Members` (`/api/v2/organizations/{id}/members`)
-* `Role.Users` (`/api/v2/roles/{id}/users`)
+- `Log.List` (`/api/v2/logs`)
+- `Organization.List` (`/api/v2/organizations`)
+- `Organization.Members` (`/api/v2/organizations/{id}/members`)
+- `Role.Users` (`/api/v2/roles/{id}/users`)
 
 <details>
   <summary>Checkpoint pagination example</summary>
@@ -109,11 +193,11 @@ for {
     if err != nil {
         log.Fatalf("err :%+v", err)
     }
-    
+
     for _, org := range orgList.Organizations {
         log.Printf("org %s", org.GetID())
     }
-    
+
     // The `HasNext` helper func checks whether
     // the API has informed us that there is
     // more data to retrieve or not.
@@ -122,6 +206,7 @@ for {
     }
 }
 ```
+
 </details>
 
 However, for `Log.List`, the `Next` value is not returned via the API but instead is an ID of a log entry. Determining if there are more logs to retrieved must also be done manually.
@@ -159,6 +244,7 @@ for {
     logFromId = logs[len(logs)-1].GetID()
 }
 ```
+
 </details>
 
 ## Providing a custom User struct

authentication/authentication.go

@@ -4,18 +4,12 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
-	"fmt"
 	"net/http"
 	"net/url"
 	"reflect"
 	"strings"
 	"time"
 
-	"github.com/google/uuid"
-	"github.com/lestrrat-go/jwx/v2/jwa"
-	"github.com/lestrrat-go/jwx/v2/jwk"
-	"github.com/lestrrat-go/jwx/v2/jwt"
-
 	"github.com/auth0/go-auth0/authentication/oauth"
 	"github.com/auth0/go-auth0/internal/client"
 	"github.com/auth0/go-auth0/internal/idtokenvalidator"
@@ -256,8 +250,14 @@ func (a *Authentication) addClientAuthenticationToURLValues(params oauth.ClientA
 
 	switch {
 	case a.clientAssertionSigningKey != "" && a.clientAssertionSigningAlg != "":
-		clientAssertion, err := createClientAssertion(
-			a.clientAssertionSigningAlg,
+		alg, err := client.DetermineSigningAlgorithm(a.clientAssertionSigningAlg)
+		if err != nil {
+			return err
+		}
+
+		// Using the improved createClientAssertion with a standard lifetime
+		clientAssertion, err := client.CreateClientAssertion(
+			alg,
 			a.clientAssertionSigningKey,
 			clientID,
 			a.url.JoinPath("/").String(),
@@ -292,8 +292,14 @@ func (a *Authentication) addClientAuthenticationToClientAuthStruct(params *oauth
 	}
 
 	if a.clientAssertionSigningKey != "" && a.clientAssertionSigningAlg != "" {
-		clientAssertion, err := createClientAssertion(
-			a.clientAssertionSigningAlg,
+		alg, err := client.DetermineSigningAlgorithm(a.clientAssertionSigningAlg)
+		if err != nil {
+			return err
+		}
+
+		// Using the improved createClientAssertion with a standard lifetime
+		clientAssertion, err := client.CreateClientAssertion(
+			alg,
 			a.clientAssertionSigningKey,
 			params.ClientID,
 			a.url.JoinPath("/").String(),
@@ -314,43 +320,3 @@ func (a *Authentication) addClientAuthenticationToClientAuthStruct(params *oauth
 
 	return nil
 }
-
-func determineAlg(alg string) (jwa.SignatureAlgorithm, error) {
-	switch alg {
-	case "RS256":
-		return jwa.RS256, nil
-	default:
-		return "", fmt.Errorf("Unsupported client assertion algorithm \"%s\" provided", alg)
-	}
-}
-
-func createClientAssertion(clientAssertionSigningAlg, clientAssertionSigningKey, clientID, domain string) (string, error) {
-	alg, err := determineAlg(clientAssertionSigningAlg)
-	if err != nil {
-		return "", err
-	}
-
-	key, err := jwk.ParseKey([]byte(clientAssertionSigningKey), jwk.WithPEM(true))
-	if err != nil {
-		return "", err
-	}
-
-	token, err := jwt.NewBuilder().
-		IssuedAt(time.Now()).
-		Subject(clientID).
-		JwtID(uuid.New().String()).
-		Issuer(clientID).
-		Claim("aud", domain).
-		Expiration(time.Now().Add(2 * time.Minute)).
-		Build()
-	if err != nil {
-		return "", err
-	}
-
-	b, err := jwt.Sign(token, jwt.WithKey(alg, key))
-	if err != nil {
-		return "", err
-	}
-
-	return string(b), nil
-}

authentication/oauth_test.go

@@ -11,6 +11,7 @@ import (
 	"time"
 
 	"github.com/auth0/go-auth0/authentication/ciba"
+	"github.com/auth0/go-auth0/internal/client"
 
 	"github.com/lestrrat-go/jwx/v2/jwa"
 	"github.com/lestrrat-go/jwx/v2/jwt"
@@ -286,7 +287,7 @@ func TestLoginWithClientCredentials(t *testing.T) {
 		skipE2E(t)
 		configureHTTPTestRecordings(t, authAPI)
 
-		auth, err := createClientAssertion("RS256", jwtPrivateKey, clientID, "https://"+domain+"/")
+		auth, err := client.CreateClientAssertion("RS256", jwtPrivateKey, clientID, "https://"+domain+"/")
 		require.NoError(t, err)
 
 		tokenSet, err := authAPI.OAuth.LoginWithClientCredentials(context.Background(), oauth.LoginWithClientCredentialsRequest{
@@ -317,7 +318,7 @@ func TestLoginWithClientCredentials(t *testing.T) {
 			Audience: "test-audience",
 		}, oauth.IDTokenValidationOptions{})
 
-		assert.ErrorContains(t, err, "Unsupported client assertion algorithm \"invalid-alg\" provided")
+		assert.ErrorContains(t, err, "unsupported client assertion algorithm \"invalid-alg\"")
 	})
 
 	t.Run("Should support passing an organization", func(t *testing.T) {

authentication/passwordless_test.go

@@ -8,6 +8,8 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
+	"github.com/auth0/go-auth0/internal/client"
+
 	"github.com/auth0/go-auth0/authentication/oauth"
 	"github.com/auth0/go-auth0/authentication/passwordless"
 )
@@ -179,7 +181,7 @@ func TestPasswordlessWithClientAssertion(t *testing.T) {
 		require.NoError(t, err)
 		configureHTTPTestRecordings(t, api)
 
-		auth, err := createClientAssertion("RS256", jwtPrivateKey, clientID, "https://"+domain+"/")
+		auth, err := client.CreateClientAssertion("RS256", jwtPrivateKey, clientID, "https://"+domain+"/")
 		require.NoError(t, err)
 
 		r, err := api.Passwordless.SendSMS(context.Background(), passwordless.SendSMSRequest{

internal/client/client.go

@@ -379,6 +379,27 @@ func OAuth2ClientCredentialsAndAudience(
 	return cfg.TokenSource(ctx)
 }
 
+// OAuth2ClientCredentialsPrivateKeyJwt sets the oauth2
+// client credentials with Private Key JWT authentication.
+func OAuth2ClientCredentialsPrivateKeyJwt(ctx context.Context, uri, clientID, clientAssertionSigningKey, clientAssertionSigningAlg string) oauth2.TokenSource {
+	audience := uri + "/api/v2/"
+	return OAuth2ClientCredentialsPrivateKeyJwtAndAudience(ctx, uri, clientID, clientAssertionSigningKey, clientAssertionSigningAlg, audience)
+}
+
+// OAuth2ClientCredentialsPrivateKeyJwtAndAudience sets the oauth2
+// client credentials with Private Key JWT authentication
+// with a custom audience.
+func OAuth2ClientCredentialsPrivateKeyJwtAndAudience(
+	ctx context.Context,
+	uri,
+	clientID,
+	clientAssertionSigningKey,
+	clientAssertionSigningAlg,
+	audience string,
+) oauth2.TokenSource {
+	return newPrivateKeyJwtTokenSource(ctx, uri, clientAssertionSigningAlg, clientAssertionSigningKey, clientID, audience)
+}
+
 // StaticToken sets a static token to be used for oauth2.
 func StaticToken(token string) oauth2.TokenSource {
 	return oauth2.StaticTokenSource(&oauth2.Token{AccessToken: token})