OIDC private key JWT / client assertion

CHANGELOG.md

@@ -4,6 +4,7 @@ Canonical reference for changes, improvements, and bugfixes for cap.
 
 ## Next
 
+* feat (oidc): add WithClientAssertionJWT to enable "private key JWT" ([PR #155](https://github.com/hashicorp/cap/pull/155))
 * feat (oidc): add WithVerifier ([PR #141](https://github.com/hashicorp/cap/pull/141))
 * feat (ldap): add an option to enable sAMAccountname logins when upndomain is set ([PR #146](https://github.com/hashicorp/cap/pull/146))
 * feat (saml): enhancing signature validation in SAML Response ([PR #144](https://github.com/hashicorp/cap/pull/144))

go.mod

@@ -5,6 +5,7 @@ go 1.21
 require (
 	github.com/coreos/go-oidc/v3 v3.11.0
 	github.com/go-jose/go-jose/v3 v3.0.3
+	github.com/go-jose/go-jose/v4 v4.0.5
 	github.com/hashicorp/go-cleanhttp v0.5.2
 	github.com/hashicorp/go-hclog v1.6.3
 	github.com/hashicorp/go-multierror v1.1.1
@@ -20,7 +21,6 @@ require (
 require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/fatih/color v1.17.0 // indirect
-	github.com/go-jose/go-jose/v4 v4.0.5 // indirect
 	github.com/google/go-cmp v0.6.0 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect
 	github.com/mattn/go-colorable v0.1.13 // indirect

oidc/clientassertion/algorithms.go

@@ -0,0 +1,55 @@
+package clientassertion
+
+import (
+	"crypto/rsa"
+	"errors"
+	"fmt"
+)
+
+type (
+	SignatureAlgorithm string
+	HSAlgorithm        SignatureAlgorithm
+	RSAlgorithm        SignatureAlgorithm
+)
+
+const (
+	HS256 HSAlgorithm = "HS256"
+	HS384 HSAlgorithm = "HS384"
+	HS512 HSAlgorithm = "HS512"
+	RS256 RSAlgorithm = "RS256"
+	RS384 RSAlgorithm = "RS384"
+	RS512 RSAlgorithm = "RS512"
+)
+
+var (
+	ErrUnsupportedAlgorithm = errors.New("unsupported algorithm")
+	ErrInvalidSecretLength  = errors.New("invalid secret length for algorithm")
+)
+
+func (a HSAlgorithm) Validate(secret string) error {
+	// verify secret length based on alg
+	var expectLen int
+	switch a {
+	case HS256:
+		expectLen = 32
+	case HS384:
+		expectLen = 48
+	case HS512:
+		expectLen = 64
+	default:
+		return fmt.Errorf("%w %q for client secret", ErrUnsupportedAlgorithm, a)
+	}
+	if len(secret) < expectLen {
+		return fmt.Errorf("%w: %q must be %d bytes long", ErrInvalidSecretLength, a, expectLen)
+	}
+	return nil
+}
+
+func (a RSAlgorithm) Validate(key *rsa.PrivateKey) error {
+	switch a {
+	case RS256, RS384, RS512:
+		return key.Validate()
+	default:
+		return fmt.Errorf("%w %q for for RSA key", ErrUnsupportedAlgorithm, a)
+	}
+}

oidc/clientassertion/client_assertion.go

@@ -0,0 +1,195 @@
+package clientassertion
+
+import (
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/go-jose/go-jose/v4"
+	"github.com/go-jose/go-jose/v4/jwt"
+	"github.com/hashicorp/go-uuid"
+)
+
+const (
+	// ClientAssertionJWTType is the proper value for client_assertion_type.
+	// https://www.rfc-editor.org/rfc/rfc7523.html#section-2.2
+	ClientAssertionJWTType = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+)
+
+var (
+	// these may happen due to user error
+	ErrMissingClientID    = errors.New("missing client ID")
+	ErrMissingAudience    = errors.New("missing audience")
+	ErrMissingAlgorithm   = errors.New("missing signing algorithm")
+	ErrMissingKeyOrSecret = errors.New("missing private key or client secret")
+	ErrBothKeyAndSecret   = errors.New("both private key and client secret provided")
+	// if these happen, either the user directly instantiated &JWT{}
+	// or there's a bug somewhere.
+	ErrMissingFuncIDGenerator = errors.New("missing IDgen func; please use NewJWT()")
+	ErrMissingFuncNow         = errors.New("missing now func; please use NewJWT()")
+	ErrCreatingSigner         = errors.New("error creating jwt signer")
+)
+
+// NewJWT sets up a new JWT to sign with a private key or client secret
+func NewJWT(clientID string, audience []string, opts ...Option) (*JWT, error) {
+	j := &JWT{
+		clientID: clientID,
+		audience: audience,
+		headers:  make(map[string]string),
+		genID:    uuid.GenerateUUID,
+		now:      time.Now,
+	}
+
+	var errs []error
+	for _, opt := range opts {
+		if err := opt(j); err != nil {
+			errs = append(errs, err)
+		}
+	}
+	if len(errs) > 0 {
+		return nil, errors.Join(errs...)
+	}
+
+	if err := j.Validate(); err != nil {
+		return nil, fmt.Errorf("new client assertion validation error: %w", err)
+	}
+	return j, nil
+}
+
+// JWT signs a JWT with either a private key or a secret
+type JWT struct {
+	// for JWT claims
+	clientID string
+	audience []string
+	headers  map[string]string
+
+	// for signer
+	alg jose.SignatureAlgorithm
+	// key may be any key type that jose.SigningKey accepts for its Key
+	key any
+	// secret may be used instead of key
+	secret string
+
+	// these are overwritten for testing
+	genID func() (string, error)
+	now   func() time.Time
+}
+
+// Validate validates the expected fields
+func (j *JWT) Validate() error {
+	var errs []error
+	if j.genID == nil {
+		errs = append(errs, ErrMissingFuncIDGenerator)
+	}
+	if j.now == nil {
+		errs = append(errs, ErrMissingFuncNow)
+	}
+	// bail early if any internal func errors
+	if len(errs) > 0 {
+		return errors.Join(errs...)
+	}
+
+	if j.clientID == "" {
+		errs = append(errs, ErrMissingClientID)
+	}
+	if len(j.audience) == 0 {
+		errs = append(errs, ErrMissingAudience)
+	}
+	if j.alg == "" {
+		errs = append(errs, ErrMissingAlgorithm)
+	}
+	if j.key == nil && j.secret == "" {
+		errs = append(errs, ErrMissingKeyOrSecret)
+	}
+	if j.key != nil && j.secret != "" {
+		errs = append(errs, ErrBothKeyAndSecret)
+	}
+	// if any of those fail, we have no hope.
+	if len(errs) > 0 {
+		return errors.Join(errs...)
+	}
+
+	// finally, make sure Serialize() works; we can't pre-validate everything,
+	// and this whole thing is useless if it can't Serialize()
+	if _, err := j.Serialize(); err != nil {
+		return fmt.Errorf("serialization error during validate: %w", err)
+	}
+
+	return nil
+}
+
+// Serialize returns a signed JWT string
+func (j *JWT) Serialize() (string, error) {
+	builder, err := j.builder()
+	if err != nil {
+		return "", err
+	}
+	token, err := builder.Serialize()
+	if err != nil {
+		return "", fmt.Errorf("failed to sign token: %w", err)
+	}
+	return token, nil
+}
+
+func (j *JWT) builder() (jwt.Builder, error) {
+	signer, err := j.signer()
+	if err != nil {
+		return nil, err
+	}
+	id, err := j.genID()
+	if err != nil {
+		return nil, fmt.Errorf("failed to generate token id: %w", err)
+	}
+	claims := j.claims(id)
+	return jwt.Signed(signer).Claims(claims), nil
+}
+
+func (j *JWT) signer() (jose.Signer, error) {
+	sKey := jose.SigningKey{
+		Algorithm: j.alg,
+	}
+
+	// Validate() ensures these are mutually exclusive
+	if j.secret != "" {
+		sKey.Key = []byte(j.secret)
+	}
+	if j.key != nil {
+		sKey.Key = j.key
+	}
+
+	sOpts := &jose.SignerOptions{
+		ExtraHeaders: make(map[jose.HeaderKey]interface{}, len(j.headers)),
+	}
+	// note: extra headers can override "kid"
+	for k, v := range j.headers {
+		sOpts.ExtraHeaders[jose.HeaderKey(k)] = v
+	}
+
+	signer, err := jose.NewSigner(sKey, sOpts.WithType("JWT"))
+	if err != nil {
+		return nil, fmt.Errorf("%w: %w", ErrCreatingSigner, err)
+	}
+	return signer, nil
+}
+
+func (j *JWT) claims(id string) *jwt.Claims {
+	now := j.now().UTC()
+	return &jwt.Claims{
+		Issuer:    j.clientID,
+		Subject:   j.clientID,
+		Audience:  j.audience,
+		Expiry:    jwt.NewNumericDate(now.Add(5 * time.Minute)),
+		NotBefore: jwt.NewNumericDate(now.Add(-1 * time.Second)),
+		IssuedAt:  jwt.NewNumericDate(now),
+		ID:        id,
+	}
+}
+
+// Serializer is the primary interface impelmented by JWT.
+type Serializer interface {
+	Serialize() (string, error)
+}
+
+// ensure JWT implements Serializer, which is accepted by the oidc option
+// oidc.WithClientAssertionJWT.
+var _ Serializer = &JWT{}