feat: Support assertion based auth

This PR brings in support for authentication:-
- Using JWT Bearer token instead of user/password clientid/client-secret flow
- Using Client Assertion Token instead of client Secret

This is primarly used with the new JWT Bearer
- Based on RFC-7523
- Feature is supported from UAA 76.23.0 & cf-cli v8.12.0

fixes: #474

Author: vipinvkmenon

README.md

@@ -57,11 +57,21 @@ Client and client secret:
 cfg, _ := config.New("https://api.example.org", config.ClientCredentials("cf", "secret"))
 cf, _ := client.New(cfg)
 ```
+Client and client assertion:
+```go
+cfg, _ := config.New("https://api.example.org", config.ClientCredentials("cf",""),config.ClientAssertion("client-assertion-token"))
+cf, _ := client.New(cfg)
+```
 Static OAuth token, which requires both an access and refresh token:
 ```go
 cfg, _ := config.New("https://api.example.org", config.Token(accessToken, refreshToken))
 cf, _ := client.New(cfg)
 ```
+Using JWT Bearer Assertion Grant
+```go
+cfg, _ := config.New("https://api.example.org",config.JWTBearerAssertion("jwt-assertion-token"))
+cf, _ := client.New(cfg)
+```
 For more detailed examples of using the various authentication and configuration options, see the
 [auth example](./examples/auth/main.go).
 

config/config.go

@@ -25,11 +25,11 @@ const (
 	GrantTypeRefreshToken      = "refresh_token"
 	GrantTypeClientCredentials = "client_credentials"
 	GrantTypePassword          = "password"
-
-	DefaultRequestTimeout = 30 * time.Second
-	DefaultUserAgent      = "Go-CF-Client/3.0"
-	DefaultClientID       = "cf"
-	DefaultSSHClientID    = "ssh-proxy"
+	GrantTypeJwtBearer         = "jwt_bearer"
+	DefaultRequestTimeout      = 30 * time.Second
+	DefaultUserAgent           = "Go-CF-Client/3.0"
+	DefaultClientID            = "cf"
+	DefaultSSHClientID         = "ssh-proxy"
 )
 
 var ErrConfigInvalid = errors.New("configuration is invalid")
@@ -48,6 +48,8 @@ type Config struct {
 	grantType         string
 	origin            string
 	scopes            []string
+	assertion         string
+	clientAssertion   string
 	oAuthToken        *oauth2.Token
 	httpClient        *http.Client
 	httpAuthClient    *http.Client
@@ -170,6 +172,21 @@ func (c *Config) CreateOAuth2TokenSource(ctx context.Context) (oauth2.TokenSourc
 	case GrantTypeRefreshToken:
 		authConfig := threeLeggedAuthConfigFn()
 		tokenSource = authConfig.TokenSource(oauthCtx, c.oAuthToken)
+	case GrantTypeJwtBearer:
+		var uaaEndpointURL string
+		if c.origin != "" {
+			// Add optional login hint to the token URL
+			uaaEndpointURL = addLoginHintToURL(c.uaaEndpointURL+"/oauth/token", c.origin)
+		}
+		tokenSource = &jwt.JWTAssertionTokenSource{
+			Assertion:       c.assertion,
+			ClientAssertion: c.clientAssertion,
+			TokenURL:        uaaEndpointURL,
+			ClientID:        c.clientID,
+			ClientSecret:    c.clientSecret,
+			HTTPClient:      c.httpClient,
+			Scopes:          c.scopes,
+		}
 	default:
 		return nil, fmt.Errorf("unsupported OAuth2 grant type '%s'", c.grantType)
 	}
@@ -252,7 +269,9 @@ func setGrantType(c *Config) error {
 	switch {
 	case c.username != "" && c.password != "":
 		c.grantType = GrantTypePassword
-	case c.clientID != "" && c.clientSecret != "":
+	case c.assertion != "":
+		c.grantType = GrantTypeJwtBearer
+	case c.clientID != "" && (c.clientSecret != "" || c.clientAssertion != ""):
 		c.grantType = GrantTypeClientCredentials
 	case c.oAuthToken != nil:
 		c.grantType = GrantTypeRefreshToken

config/config_test.go

@@ -12,6 +12,8 @@ import (
 
 const accessToken = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6InRlc3QgY2YgdG9rZW4iLCJpYXQiOjE1MTYyMzkwMjIsImV4cCI6MTUxNjIzOTAyMn0.mLvUvu-ED_lIkyI3UTXS_hUEPPFdI0BdNqRMgMThAhk"
 const refreshToken = "secret-refresh-token"
+const clientAssertion = "client-assertion-token"
+const jwtAssertion = "jwt-assertion-token"
 
 func TestInvalidConfig(t *testing.T) {
 	c := &Config{}
@@ -112,6 +114,17 @@ func TestClientCredentials(t *testing.T) {
 		require.Equal(t, refreshToken, c.oAuthToken.RefreshToken)
 		require.Equal(t, GrantTypeClientCredentials, c.grantType)
 	})
+
+	t.Run("with clientID and client assertion", func(t *testing.T) {
+		c, err := New("https://api.example.com",
+			ClientCredentials("clientID", ""),
+			ClientAssertion(clientAssertion),
+			AuthTokenURL("https://login.cf.example.com", "https://token.cf.example.com")) // skip service discovery
+		require.NoError(t, err)
+		require.Equal(t, "clientID", c.clientID)
+		require.Equal(t, clientAssertion, c.clientAssertion)
+		require.Equal(t, GrantTypeClientCredentials, c.grantType)
+	})
 }
 
 func TestToken(t *testing.T) {
@@ -224,3 +237,14 @@ func TestNewConfigFromCFHomeDir(t *testing.T) {
 		require.Equal(t, GrantTypePassword, cfg.grantType)
 	})
 }
+
+func TestJwBearerAssertion(t *testing.T) {
+	t.Run("minimalistic setup", func(t *testing.T) {
+		cfg, err := New("https://api.example.com",
+			JWTBearerAssertion(jwtAssertion),
+			AuthTokenURL("https://login.cf.example.com", "https://token.cf.example.com")) // skip service discovery
+		require.NoError(t, err)
+		require.Equal(t, jwtAssertion, cfg.assertion)
+		require.Equal(t, GrantTypeJwtBearer, cfg.grantType)
+	})
+}

config/options.go

@@ -31,6 +31,24 @@ func ClientCredentials(clientID, clientSecret string) Option {
 	}
 }
 
+// ClientAssertion is a functional option to set client assertion.
+func ClientAssertion(assertion string) Option {
+	return func(c *Config) error {
+		// if set, must be a valid JWT token
+		// alternative to client secret
+		// usually used with ClientCredentials
+		// can be combined with JWTBearerAssertion
+		// refer RFC 7523 for more details
+		if assertion = strings.TrimSpace(assertion); assertion == "" {
+			return errors.New("assertion must be valid JWT Token")
+		} else {
+			c.clientAssertion = assertion
+		}
+
+		return nil
+	}
+}
+
 // UserPassword is a functional option to set user credentials.
 func UserPassword(username, password string) Option {
 	return func(c *Config) error {
@@ -45,6 +63,24 @@ func UserPassword(username, password string) Option {
 	}
 }
 
+// JWTBearerAssertion is a functional option to set JWT Bearer credentials.
+func JWTBearerAssertion(assertion string) Option {
+	return func(c *Config) error {
+		// if set, must be a valid JWT token
+		// can be used alone
+		// or with ClientCredentials
+		// or with ClientCredentials + ClientAssertion
+		// refer RFC 7523 for more details
+		if assertion = strings.TrimSpace(assertion); assertion == "" {
+			return errors.New("assertion is required for JWT Bearer grant type")
+		} else {
+			c.assertion = assertion
+		}
+
+		return nil
+	}
+}
+
 // Token is a functional option to set the access and refresh tokens.
 func Token(accessToken, refreshToken string) Option {
 	return func(c *Config) error {

examples/auth/main.go

@@ -20,6 +20,9 @@ const clientID = "cf"
 const clientSecret = "secret"
 const accessToken = "<access-token>"
 const refreshToken = "<refresh-token>"
+const jwtAssertion = "<jwt-assertion>"
+const clientAssertion = "<client-assertion>"
+const origin = "<origin>"
 
 func main() {
 	err := execute()
@@ -77,6 +80,32 @@ func execute() error {
 		return err
 	}
 
+	// use the hardcoded CF API endpoint and JWT Bearer Assertion token and optional origin
+	// minimally requires the assertion
+	cfg, err = config.New(apiURL,
+		config.JWTBearerAssertion(jwtAssertion),
+		config.Origin(origin))
+	if err != nil {
+		return err
+	}
+	err = listOrganizationsWithConfig(cfg)
+	if err != nil {
+		return err
+	}
+
+	// use the hardcoded CF API endpoint and JWT Bearer Assertion token and optional origin
+	// minimally requires the assertion
+	cfg, err = config.New(apiURL,
+		config.ClientCredentials(clientID, ""),
+		config.ClientAssertion(clientAssertion))
+	if err != nil {
+		return err
+	}
+	err = listOrganizationsWithConfig(cfg)
+	if err != nil {
+		return err
+	}
+
 	// Unnecessarily use all config options
 	cfg, err = config.New(apiURL,
 		config.UserPassword(username, password),

internal/jwt/token.go

@@ -5,16 +5,36 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"net/url"
 	"strings"
 	"time"
 
 	"golang.org/x/oauth2"
 )
 
+const (
+	grantTypeJwtBearer  = "urn:ietf:params:oauth:grant-type:jwt-bearer"
+	clientAssertionType = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+)
+
 type tokenPayload struct {
 	Expiration int64 `json:"exp"`
 }
 
+type JWTAssertionTokenSource struct { // revive:disable-line:exported
+	Assertion       string
+	ClientAssertion string
+	ClientID        string
+	ClientSecret    string
+	GrantType       string
+	Scopes          []string
+	TokenURL        string
+	HTTPClient      *http.Client
+}
+
 func AccessTokenExpiration(accessToken string) (time.Time, error) {
 	tp := strings.Split(accessToken, ".")
 	if len(tp) != 3 {
@@ -64,3 +84,107 @@ func ToOAuth2Token(accessToken, refreshToken string) (*oauth2.Token, error) {
 	}
 	return oAuthToken, nil
 }
+
+func (s *JWTAssertionTokenSource) Token() (*oauth2.Token, error) {
+	data := url.Values{}
+
+	if s.TokenURL == "" {
+		return nil, fmt.Errorf("token URL is required")
+	}
+	if s.GrantType == "" {
+		data.Set("grant_type", grantTypeJwtBearer)
+	} else {
+		data.Set("grant_type", s.GrantType)
+	}
+	// Assertion is required for JWT Bearer grant type
+	if s.Assertion == "" && (s.GrantType == grantTypeJwtBearer || s.GrantType == "") {
+		return nil, fmt.Errorf("assertion is required for JWT Bearer grant type")
+	}
+
+	if s.Assertion != "" {
+		if err := validateJWTTokenFormat(s.Assertion); err != nil {
+			return nil, err
+		}
+		data.Set("assertion", s.Assertion)
+	}
+
+	// Optional client_id
+	if s.ClientID != "" {
+		data.Set("client_id", s.ClientID)
+	}
+
+	// Optional client_secret
+	if s.ClientSecret != "" {
+		if s.ClientID == "" {
+			return nil, fmt.Errorf("client_id is required when using client secret")
+		}
+		data.Set("client_secret", s.ClientSecret)
+	}
+
+	// Optional client_assertion
+	if s.ClientAssertion != "" {
+		if s.ClientID == "" {
+			return nil, fmt.Errorf("client_id is required when using client assertion")
+		}
+		if err := validateJWTTokenFormat(s.ClientAssertion); err != nil {
+			return nil, err
+		}
+		data.Set("client_assertion_type", clientAssertionType)
+		data.Set("client_assertion", s.ClientAssertion)
+	}
+	if len(s.Scopes) > 0 {
+		data.Set("scope", strings.Join(s.Scopes, " "))
+	}
+
+	req, err := http.NewRequest("POST", s.TokenURL, strings.NewReader(data.Encode()))
+	if err != nil {
+		return nil, fmt.Errorf("token request object creation failed: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	client := s.HTTPClient
+	if client == nil {
+		client = http.DefaultClient
+	}
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("token request failed: %w", err)
+	}
+	defer func() {
+		if err := resp.Body.Close(); err != nil {
+			log.Printf("failed to close response body: %v", err)
+		}
+	}()
+
+	body, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("token request failed: %s", body)
+	}
+
+	var token oauth2.Token
+	err = json.Unmarshal(body, &token)
+	if err != nil {
+		return nil, fmt.Errorf("token unmarshal error: %w", err)
+	}
+	return &token, nil
+}
+
+// validateJWTTokenFormat checks if the provided JWT token has a valid format.
+func validateJWTTokenFormat(token string) error {
+	parts := strings.Split(token, ".")
+	if len(parts) != 3 {
+		return errors.New("token must have three parts separated by '.'")
+	}
+
+	for i, part := range parts {
+		if part == "" {
+			return fmt.Errorf("token part is empty")
+		}
+		if _, err := base64.RawURLEncoding.DecodeString(part); err != nil {
+			return fmt.Errorf("invalid base64 encoding in part %d", i+1)
+		}
+	}
+
+	return nil
+}