hashicorp/nomad · error

PrivateKey is required for `private_key` KeySource

Error message

PrivateKey is required for `private_key` KeySource

What it means

If the client assertion KeySource is `private_key`, the assertion must be signed with a locally provided key, so PrivateKey is mandatory. Validate returns this error when a private_key KeySource is selected without key material.

Source

Thrown at nomad/structs/acl.go:1778

	c.PrivateKey.Canonicalize()
}

func (c *OIDCClientAssertion) IsSet() bool {
	return c != nil && c.KeySource != ""
}

func (c *OIDCClientAssertion) Validate() error {
	if c == nil {
		return nil
	}
	if len(c.Audience) == 0 || c.Audience[0] == "" {
		return errors.New("missing Audience")
	}
	switch c.KeySource {
	case OIDCKeySourceNomad:
	case OIDCKeySourcePrivateKey:
		if c.PrivateKey == nil {
			return errors.New("PrivateKey is required for `private_key` KeySource")
		}
		if err := c.PrivateKey.Validate(); err != nil {
			return fmt.Errorf("invalid PrivateKey: %w", err)
		}
	case OIDCKeySourceClientSecret:
		if c.ClientSecret == "" {
			return errors.New("OIDCClientSecret is required for `client_secret` KeySource")
		}
	default:
		return fmt.Errorf("invalid KeySource %q", c.KeySource)
	}
	return nil
}

type OIDCClientAssertionKeyIDHeader string

const (
	OIDCClientAssertionHeaderKid     OIDCClientAssertionKeyIDHeader = "kid"

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set the PrivateKey field (PemKey or PemKeyFile, KeyID, etc.) alongside KeySource private_key
2. Or switch KeySource to "nomad" if the IdP can consume Nomad-generated keys, or "client_secret" for a plain secret

Example fix

// before
assertion := &api.OIDCClientAssertion{KeySource: "private_key", Audience: aud}
// after
assertion := &api.OIDCClientAssertion{KeySource: "private_key", Audience: aud,
  PrivateKey: &api.OIDCClientAssertionKey{PemKeyFile: "/etc/nomad/assertion.key", KeyID: "key-1", KeyIDHeader: "kid"}}

func privateKeyAssertionOK(c *structs.OIDCClientAssertion) bool {
  return c == nil || c.KeySource != structs.OIDCKeySourcePrivateKey || c.PrivateKey != nil
}

When it happens

Trigger: Configuring OIDCClientAssertion with KeySource "private_key" but leaving PrivateKey nil.

Common situations: Choosing private_key signing for IdPs that don't support Nomad-managed keys but forgetting to supply the key config; configs migrated from KeySource "nomad" where the key field was unused.

Related errors

• missing Audience
• invalid config: %w
• %w; key header for key ID must be %q
• %w; certificate-derived key header must be one of: %q, %q
• no auth method config or client assertion

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/1a0a531a4621021f. Report an issue: GitHub.