mirrors/pinniped
1
0
Fork 0
mirror of https://github.com/vmware-tanzu/pinniped.git synced 2025-12-23 06:15:47 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

improve errors and docs for JWTAuthenticator features, with int tests

Browse Source
This commit is contained in:
Ryan Richard
2025-07-18 12:22:06 -07:00
parent cc4a148c70
commit 83696fd023
31 changed files with 1787 additions and 410 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
apis/concierge/authentication/v1alpha1/types_jwtauthenticator.go.tmpl
View File

@@ -77,14 +77,12 @@ type JWTAuthenticatorSpec struct {
// ClaimValidationRule provides the configuration for a single claim validation rule.
type ClaimValidationRule struct {
// claim is the name of a required claim.
// Same as --oidc-required-claim flag.
// Only string claim keys are supported.
// Mutually exclusive with expression and message.
// +optional
Claim string `json:"claim,omitempty"`
// requiredValue is the value of a required claim.
// Same as --oidc-required-claim flag.
// Only string claim values are supported.
// If claim is set and requiredValue is not set, the claim must be present with a value set to the empty string.
// Mutually exclusive with expression and message.
@@ -147,9 +145,14 @@ type JWTTokenClaims struct {
Username string `json:"username"`
// usernameExpression represents an expression which will be evaluated by CEL.
//
// The expression's result will become the user's username.
//
// usernameExpression is similar to claimMappings.username.expression from Kubernetes AuthenticationConfiguration
// as documented in https://kubernetes.io/docs/reference/access-authn-authz/authentication.
// This is an advanced configuration option. During an end-user login flow, each of these CEL expressions
// must evaluate to the expected type without errors, or else the user's login will fail.
// Additionally, mistakes in this configuration can cause the users to have unintended usernames.
//
// The expression must produce a non-empty string value.
// If the expression uses 'claims.email', then 'claims.email_verified' must be used in
// the expression or extra[*].valueExpression or claimValidationRules[*].expression.
@@ -180,9 +183,14 @@ type JWTTokenClaims struct {
Groups string `json:"groups"`
// groupsExpression represents an expression which will be evaluated by CEL.
//
// The expression's result will become the user's group memberships.
//
// groupsExpression is similar to claimMappings.groups.expression from Kubernetes AuthenticationConfiguration
// as documented in https://kubernetes.io/docs/reference/access-authn-authz/authentication.
// This is an advanced configuration option. During an end-user login flow, each of these CEL expressions
// must evaluate to one of the expected types without errors, or else the user's login will fail.
// Additionally, mistakes in this configuration can cause the users to have unintended group memberships.
//
// The expression must produce a string or string array value.
// "", [], and null values are treated as the group mapping not being present.
//
@@ -198,18 +206,45 @@ type JWTTokenClaims struct {
// +optional
GroupsExpression string `json:"groupsExpression,omitempty"`
// extra is similar to claimMappings.extra from Kubernetes AuthenticationConfiguration as documented in
// https://kubernetes.io/docs/reference/access-authn-authz/authentication. However, note that the
// Pinniped Concierge issues client certificates to users for the purpose of authenticating, and
// the Kubernetes API server does not have any mechanism for transmitting auth extras via client
// certificates. When configured, these extras will appear in client certificates issued by the
// Pinniped Supervisor in the x509 Subject field as Organizational Units (OU). However, when this
// client certificate is presented to Kubernetes for authentication, Kubernetes will ignore these
// extras. This is probably only useful if you are using a custom authenticating proxy in front
// of your Kubernetes API server which can translate these OUs into auth extras, as described by
// extra is similar to claimMappings.extra from Kubernetes AuthenticationConfiguration
// as documented in https://kubernetes.io/docs/reference/access-authn-authz/authentication.
//
// However, note that the Pinniped Concierge issues client certificates to users for the purpose
// of authenticating, and the Kubernetes API server does not have any mechanism for transmitting
// auth extras via client certificates. When configured, these extras will appear in client
// certificates issued by the Pinniped Supervisor in the x509 Subject field as Organizational
// Units (OU). However, when this client certificate is presented to Kubernetes for authentication,
// Kubernetes will ignore these extras. This is probably only useful if you are using a custom
// authenticating proxy in front of your Kubernetes API server which can translate these OUs into
// auth extras, as described by
// https://kubernetes.io/docs/reference/access-authn-authz/authentication/#authenticating-proxy.
// This is an advanced configuration option. During an end-user login flow, each of these CEL expressions
// must evaluate to either a string or an array of strings, or else the user's login will fail.
//
// These keys must be a domain-prefixed path (such as "acme.io/foo") and must not contain an equals sign ("=").
//
// expression must produce a string or string array value.
// If the value is empty, the extra mapping will not be present.
//
// Documentation on CEL: https://kubernetes.io/docs/reference/using-api/cel/
//
// hard-coded extra key/value
// - key: "acme.io/foo"
// valueExpression: "'bar'"
// This will result in an extra attribute - acme.io/foo: ["bar"]
//
// hard-coded key, value copying claim value
// - key: "acme.io/foo"
// valueExpression: "claims.some_claim"
// This will result in an extra attribute - acme.io/foo: [value of some_claim]
//
// hard-coded key, value derived from claim value
// - key: "acme.io/admin"
// valueExpression: '(has(claims.is_admin) && claims.is_admin) ? "true":""'
// This will result in:
// - if is_admin claim is present and true, extra attribute - acme.io/admin: ["true"]
// - if is_admin claim is present and false or is_admin claim is not present, no extra attribute will be added
//
// +optional
Extra []ExtraMapping `json:"extra,omitempty"`
}
@@ -222,6 +257,7 @@ type ExtraMapping struct {
// be valid HTTP Path characters as defined by RFC 3986.
// key must be lowercase.
// Required to be unique.
// Additionally, the key must not contain an equals sign ("=").
// +required
Key string `json:"key"`