-
Notifications
You must be signed in to change notification settings - Fork 18
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
adds info about kube-rbac-proxy's high-level workflow
- Loading branch information
Showing
1 changed file
with
59 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,59 @@ | ||
| # kube-rbac-proxy | ||
|
|
||
| `kube-rbac-proxy`, as the name suggests, is a proxy that sits in front of a workload and performs authentication | ||
| and authorization on its behalf, to make sure the requests passing through are the ones that it expects to. | ||
|
|
||
| ## Workflow | ||
|
|
||
| The purpose of `kube-rbac-proxy` is to distinguish between calls made by same or different user(s) (or service | ||
| account(s)) to endpoint(s) and protect them from unauthenticated or unauthorized resource access based on the | ||
| Bearer tokens or the RBACs they hold, respectively. | ||
|
|
||
| - [**Authentication**]: Both [OIDC JWT] and [delegated (header-based)] authentication rely on Bearer tokens to | ||
| authenticate the requests. The tokens are validated against the OIDC provider or the Kubernetes API server, | ||
| respectively. The proxy can also be configured to [skip the authentication step] altogether, in which case it will | ||
| not validate the tokens and will assume that the requests are authenticated. This token represents the identity of | ||
| the user or service account that is making the request. A [`TokenReview` request is created], and includes the bearer | ||
| token that the client provided, which is then sent to the API server. The API server verifies the authenticity of | ||
| the token and responds with the details of the authenticated party, if the operation was successful. | ||
|
|
||
| [skip the authentication step]: https://github.com/rexagod/kube-rbac-proxy/blob/4c4a18fa7dd5d8069c0aa3a55028e06631621a52/pkg/authn/delegating.go#L53 | ||
| [OIDC JWT]: https://github.com/rexagod/kube-rbac-proxy/blob/52e49fbdb75e009db4d02e3986e51fdba0526378/pkg/authn/oidc.go#L45-L63 | ||
| [delegated (header-based)]: https://github.com/kubernetes/apiserver/blob/master/pkg/authentication/authenticatorfactory/delegating.go#L102-L112 | ||
| [**Authentication**]: https://github.com/rexagod/kube-rbac-proxy/blob/74181c75b8b6fbcde7eff1ca5fae353faac5cfae/pkg/authn/config.go#L33-L39 | ||
| [`TokenReview` request is created]: https://github.com/kubernetes/apiserver/blob/21bbcb57c672531fe8c431e1035405f9a4b061de/plugin/pkg/authenticator/token/webhook/webhook.go#L51-L53 | ||
|
|
||
| - [**Authorization**]: Once authentication is done, `kube-rbac-proxy` must then decide whether to allow the user's | ||
| request to go through or not. A [`SubjectAccessReview` request is created] for the API server, which allows for the | ||
| review of the subject's access to a particular resource. Essentially, it checks whether the authenticated user or | ||
| service account or has sufficient permissions to perform the desired action on the requested resource, based on | ||
| the RBAC permissions granted to it. If so, the request is forwarded to the endpoint, otherwise it is rejected. Its | ||
| worth mentioning that the HTTP verbs are internally mapped to their [corresponding RBAC verbs]. | ||
|
|
||
| [corresponding RBAC verbs]: https://github.com/rexagod/kube-rbac-proxy/blob/ccd5bc7fec36f9db0747033c2d698cc75a0e314c/pkg/proxy/proxy.go#L49-L60 | ||
| [**Authorization**]: https://github.com/rexagod/kube-rbac-proxy/blob/1c7f88b5e951d25a493a175e93515068f5c77f3b/pkg/authz/auth.go#L31C1-L37 | ||
| [`SubjectAccessReview` request is created]: https://github.com/kubernetes/apiserver/blob/21bbcb57c672531fe8c431e1035405f9a4b061de/plugin/pkg/authorizer/webhook/webhook.go#L57-L59 | ||
|
|
||
| - **Request/response forwarding and error handling**: Once the request is authenticated and authorized, it is | ||
| forwarded to the endpoint. The response from the endpoint is then forwarded back to the client. If the request | ||
| fails at any point, the proxy returns an error response to the client. If the authorization step fails, i.e., the | ||
| client doesn't have the required permissions to access the requested resource, `kube-rbac-proxy` returns an [HTTP | ||
| `403 Forbidden` status code] to the client and does not forward the request to the endpoint. In the case of a | ||
| failed authentication, an [HTTP `401 Unauthorized` status code] is returned instead (note the distinction between | ||
| _authentication_ and _unauthorized_ here). | ||
|
|
||
| [HTTP `403 Forbidden` status code]: https://github.com/rexagod/kube-rbac-proxy/blob/9efde2a776fd516cfa082cc5f2c35c7f9e0e2689/pkg/filters/auth_test.go#L300 | ||
| [HTTP `401 Unauthorized` status code]: https://github.com/rexagod/kube-rbac-proxy/blob/9efde2a776fd516cfa082cc5f2c35c7f9e0e2689/pkg/filters/auth_test.go#L290 | ||
|
|
||
| ## Configuration | ||
|
|
||
| Details on configuring `kube-rbac-proxy` under different scenarios can be found in the repository's [/examples] section. | ||
|
|
||
| [/examples]: https://github.com/rexagod/kube-rbac-proxy/tree/9f436d46699dfd425f2682e4338069642b682892/examples | ||
|
|
||
| ## Debugging | ||
|
|
||
| In addition to enabling debug logs or compiling a custom binary with debugging capabilities (`-gcflags="all=-N -l"`), | ||
| users can grep [the audit logs] for more information about requests or responses concerning `kube-rbac-proxy`. | ||
|
|
||
| [the audit logs]: https://docs.openshift.com/container-platform/4.13/security/audit-log-view.html |