You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: knox-site/docs/config_preauth_sso_provider.md
+112-1Lines changed: 112 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -57,7 +57,7 @@ The following table describes the configuration options for the web app security
57
57
58
58
Name | Description | Default
59
59
---------|-----------|--------
60
-
preauth.validation.method | Optional parameter that indicates the types of trust validation to perform on incoming requests. There could be one or more comma-separated validators defined in this property. If there are multiple validators, Apache Knox validates each validator in the same sequence as it is configured. This works similar to short-circuit AND operation i.e. if any validator fails, Knox does not perform further validation and returns overall failure immediately. Possible values are: null, preauth.default.validation, preauth.ip.validation, custom validator (details described in [Custom Validator](dev-guide.html#Validator)). Failure results in a 403 forbidden HTTP status response.| null - which means 'preauth.default.validation' that is no validation will be performed and that we are assuming that the network security and external authentication system is sufficient.
60
+
preauth.validation.method | Optional parameter that indicates the types of trust validation to perform on incoming requests. There could be one or more comma-separated validators defined in this property. If there are multiple validators, Apache Knox validates each validator in the same sequence as it is configured. This works similar to short-circuit AND operation i.e. if any validator fails, Knox does not perform further validation and returns overall failure immediately. Possible values are: null, preauth.default.validation, preauth.ip.validation, preauth.k8s.service.account.validation (see [Kubernetes ServiceAccount Validator](#kubernetes-serviceaccount-validator)), custom validator (details described in [Custom Validator](dev-guide.html#Validator)). Failure results in a 403 forbidden HTTP status response.| null - which means 'preauth.default.validation' that is no validation will be performed and that we are assuming that the network security and external authentication system is sufficient.
61
61
preauth.ip.addresses | Optional parameter that indicates the list of trusted ip addresses. When preauth.ip.validation is indicated as the validation method this parameter must be provided to indicate the trusted ip address set. Wildcarded IPs may be used to indicate subnet level trust. ie. 127.0.* | null - which means that no validation will be performed.
62
62
preauth.custom.header | Required parameter for indicating a custom header to use for extracting the preauthenticated principal. The value extracted from this header is utilized as the PrimaryPrincipal within the established Subject. An incoming request that is missing the configured header will be refused with a 401 unauthorized HTTP status. | SM_USER for SiteMinder usecase
63
63
preauth.custom.group.header | Optional parameter for indicating a HTTP header name that contains a comma separated list of groups. These are added to the authenticated Subject as group principals. A missing group header will result in no groups being extracted from the incoming request and a log entry but processing will continue. | null - which means that there will be no group principals extracted from the request and added to the established Subject.
@@ -101,3 +101,114 @@ The following curl command can be used to request a directory listing from HDFS
Omitting the `--header "iv_user: guest"` above will result in a rejected request.
104
+
105
+
#### Kubernetes ServiceAccount Validator ####
106
+
107
+
The Kubernetes ServiceAccount Validator (`preauth.k8s.service.account.validation`) is a `PreAuthValidator` implementation shipped in the `gateway-provider-security-k8s` module. It is intended for deployments where Knox runs inside a Kubernetes cluster and accepts pre-authenticated requests from workloads whose identity is asserted via a [SPIFFE](https://spiffe.io/) ID.
108
+
109
+
The validator enforces a binding between:
110
+
111
+
1. the calling workload's SPIFFE identity (its Kubernetes namespace and ServiceAccount), and
112
+
2. the user the caller is asserting in the `HeaderPreAuth` custom user header.
113
+
114
+
The asserted user is only accepted if the corresponding ServiceAccount in Kubernetes carries an annotation that explicitly authorizes that ServiceAccount to assert that user. This prevents a compromised or misconfigured workload from spoofing arbitrary identities through the pre-auth header.
115
+
116
+
##### How it works #####
117
+
118
+
For each incoming request the validator:
119
+
120
+
1. Reads the SPIFFE header (default `x-spiffe-id`). Its value must be a Kubernetes-style SPIFFE ID of the form `spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>`. Anything else is rejected.
121
+
2. Reads the asserted user header (default `x-knoxidf-obo.username`). A missing or empty value is rejected.
122
+
3. Looks up the `ServiceAccount` named `<service-account>` in namespace `<namespace>` via the Kubernetes API and reads the annotation configured by `preauth.k8s.sa.user.annotation` (default `knox.apache.org/owner-username`).
123
+
4. Accepts the request only if the annotation is present and its value equals the asserted user. Otherwise the request is rejected and `HeaderPreAuth` returns 403.
124
+
125
+
ServiceAccount annotation lookups are cached in-memory (Caffeine, write-expiring). Successful lookups (including "annotation missing") are cached; transient errors talking to the Kubernetes API are not cached so they will be retried on the next request.
126
+
127
+
##### Prerequisites #####
128
+
129
+
- Knox must run inside a Kubernetes pod (or otherwise have a kubeconfig discoverable by the fabric8 `KubernetesClient`).
130
+
- The ServiceAccount Knox runs as must have permission to `get``serviceaccounts` in any namespace whose workloads it must authorize. Grant this with a `ClusterRole`/`ClusterRoleBinding` (or namespace-scoped `Role`/`RoleBinding`).
131
+
- A trust path must inject the SPIFFE header into incoming requests. The network/mesh configuration MUST prevent clients from setting this header themselves; otherwise this validator can be bypassed.
132
+
- Each ServiceAccount permitted to assert a user MUST be annotated with the configured annotation key, e.g.:
133
+
134
+
apiVersion: v1
135
+
kind: ServiceAccount
136
+
metadata:
137
+
name: my-workload-sa
138
+
namespace: analytics
139
+
annotations:
140
+
knox.apache.org/owner-username: alice
141
+
142
+
##### Configuration parameters #####
143
+
144
+
All parameters are set as `<param>` entries on the `HeaderPreAuth` provider.
145
+
146
+
Name | Description | Default
147
+
---------|-----------|--------
148
+
preauth.validation.method | Must include `preauth.k8s.service.account.validation` to enable this validator. May be combined with other validators (comma-separated, short-circuit AND). | n/a
149
+
preauth.k8s.sa.spiffe.header | HTTP header carrying the caller's SPIFFE ID. Must be set/overwritten by a trusted hop — never by clients directly. | `x-spiffe-id`
150
+
preauth.k8s.sa.custom.header | HTTP header carrying the asserted user that the caller is requesting to act as. This is the value validated against the ServiceAccount annotation. | `x-knoxidf-obo.username`
151
+
preauth.k8s.sa.user.annotation | Annotation key on the `ServiceAccount` whose value, when equal to the asserted user, authorizes the assertion. | `knox.apache.org/owner-username`
152
+
preauth.k8s.sa.cache.ttl.seconds | Write-expiry TTL (in seconds) for cached ServiceAccount annotation lookups. Must be `> 0`. Lower values pick up annotation changes faster at the cost of more API calls. | `60`
153
+
preauth.k8s.sa.cache.max.size | Maximum number of distinct `(namespace, service-account)` entries kept in the lookup cache. Must be `> 0`. | `1000`
154
+
155
+
Note: the user header default (`x-knoxidf-obo.username`) is independent of the `HeaderPreAuth``preauth.custom.header` parameter — `preauth.custom.header` controls which header `HeaderPreAuth` extracts as the primary principal, while `preauth.k8s.sa.custom.header` controls which header this validator checks against the ServiceAccount annotation. Configure both to the same header name in deployments where the same value plays both roles.
Assuming the namespace `analytics` contains a ServiceAccount `my-workload-sa` annotated with `knox.apache.org/owner-username: alice`, and the service mesh injects `x-spiffe-id` for that workload:
The request is accepted and processed as user `alice`. Sending the same request with `x-knoxidf-obo.username: bob` (or with a SPIFFE ID pointing to a ServiceAccount that is not annotated for `alice`) yields a 403 response.
203
+
204
+
##### Failure modes #####
205
+
206
+
The validator rejects the request (causing `HeaderPreAuth` to return 403) and emits a WARN log entry when:
207
+
208
+
- the SPIFFE header is missing or empty;
209
+
- the user header is missing or empty;
210
+
- the SPIFFE header value is not a parseable Kubernetes SPIFFE ID (`spiffe://.../ns/<ns>/sa/<sa>`);
211
+
- the target `ServiceAccount` does not exist or carries no annotation under the configured key;
212
+
- the annotation value does not match the asserted user.
213
+
214
+
Errors talking to the Kubernetes API are logged at ERROR and result in rejection but are not cached, so transient API outages do not produce sticky 403s once the API recovers.
0 commit comments