mirror of
https://github.com/status-im/consul.git
synced 2025-01-12 06:44:41 +00:00
5d349cf6f3
This commit modifies the example payloads for various auth methods to remove 'other fields' and instead use complete example payloads.
160 lines
6.6 KiB
Plaintext
160 lines
6.6 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Kubernetes Auth Method
|
|
description: >-
|
|
Use the Kubernetes auth method type to authenticate to Consul with a Kubernetes service account token and receive an ACL token with privileges based on JWT identity attributes. Learn how to configure auth method parameters using this reference page and example configuration.
|
|
---
|
|
|
|
# Kubernetes Auth Method
|
|
|
|
-> **1.5.0+:** This feature is available in Consul versions 1.5.0 and newer.
|
|
|
|
The `kubernetes` auth method type allows for a Kubernetes service account token
|
|
to be used to authenticate to Consul. This method of authentication makes it
|
|
easy to introduce a Consul token into a Kubernetes pod.
|
|
|
|
This page assumes general knowledge of [Kubernetes](https://kubernetes.io/) and
|
|
the concepts described in the main [auth method
|
|
documentation](/consul/docs/security/acl/auth-methods).
|
|
|
|
## Config Parameters
|
|
|
|
The following auth method [`Config`](/consul/api-docs/acl/auth-methods#config)
|
|
parameters are required to properly configure an auth method of type
|
|
`kubernetes`:
|
|
|
|
- `Host` `(string: <required>)` - Must be a host string, a host:port pair, or a
|
|
URL to the base of the Kubernetes API server.
|
|
|
|
- `CACert` `(string: <required>)` - PEM encoded CA cert for use by the TLS
|
|
client used to talk with the Kubernetes API. NOTE: Every line must end with a
|
|
newline (`\n`). If not set, system certificates are used.
|
|
|
|
- `ServiceAccountJWT` `(string: <required>)` - A Service Account Token
|
|
([JWT](https://jwt.io/ 'JSON Web Token')) used by the Consul leader to
|
|
validate application JWTs during login.
|
|
|
|
- `MapNamespaces` `(bool: <false>)` <EnterpriseAlert inline /> -
|
|
**Deprecated in Consul 1.8.0 in favor of [namespace rules](/consul/api-docs/acl/auth-methods#namespacerules).**
|
|
Indicates whether the auth method should attempt to map the Kubernetes namespace to a Consul
|
|
namespace instead of creating tokens in the auth methods own namespace. Note
|
|
that mapping namespaces requires the auth method to reside within the
|
|
`default` namespace.
|
|
Deprecated in Consul 1.8.0 in favor of [namespace rules](/consul/api-docs/acl/auth-methods#namespacerules).
|
|
|
|
- `ConsulNamespacePrefix` `(string: <optional>)` <EnterpriseAlert inline /> -
|
|
**Deprecated in Consul 1.8.0 in favor of [namespace rules](/consul/api-docs/acl/auth-methods#namespacerules).**
|
|
When `MapNamespaces` is enabled, this value will be prefixed to the Kubernetes
|
|
namespace to determine the Consul namespace to create the new token within.
|
|
Deprecated in Consul 1.8.0 in favor of [namespace rules](/consul/api-docs/acl/auth-methods#namespacerules).
|
|
|
|
- `ConsulNamespaceOverrides` `(map: <string:string>)` <EnterpriseAlert inline /> -
|
|
**Deprecated in Consul 1.8.0 in favor of [namespace rules](/consul/api-docs/acl/auth-methods#namespacerules).**
|
|
This field is a mapping of Kubernetes namespace names to Consul namespace
|
|
names. If a Kubernetes namespace is present within this map, the value will
|
|
be used without adding the `ConsulNamespacePrefix`. If the value in the map
|
|
is `""` then the auth methods namespace will be used instead of attempting
|
|
to determine an alternate namespace.
|
|
Deprecated in Consul 1.8.0 in favor of [namespace rules](/consul/api-docs/acl/auth-methods#namespacerules).
|
|
|
|
### Sample Config
|
|
|
|
```json
|
|
{
|
|
"Name": "example-k8s-auth",
|
|
"Type": "kubernetes",
|
|
"Description": "Example JWT auth method",
|
|
"Config": {
|
|
"Host": "https://192.0.2.42:8443",
|
|
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
|
|
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
|
|
}
|
|
}
|
|
```
|
|
|
|
## RBAC
|
|
|
|
The Kubernetes service account corresponding to the configured
|
|
[`ServiceAccountJWT`](/consul/docs/security/acl/auth-methods/kubernetes#serviceaccountjwt)
|
|
needs to have access to two Kubernetes APIs:
|
|
|
|
- [**TokenReview**](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-review-v1/)
|
|
|
|
-> Kubernetes should be running with `--service-account-lookup`. This is
|
|
defaulted to true in Kubernetes 1.7, but any versions prior should ensure
|
|
the Kubernetes API server is started with this setting.
|
|
|
|
- [**ServiceAccount**](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#service-account-tokens)
|
|
|
|
The following is an example
|
|
[RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
|
|
configuration snippet to grant the necessary permissions to a service account
|
|
named `consul-auth-method-example`:
|
|
|
|
```yaml
|
|
---
|
|
kind: ClusterRoleBinding
|
|
apiVersion: rbac.authorization.k8s.io/v1
|
|
metadata:
|
|
name: review-tokens
|
|
namespace: default
|
|
subjects:
|
|
- kind: ServiceAccount
|
|
name: consul-auth-method-example
|
|
namespace: default
|
|
roleRef:
|
|
kind: ClusterRole
|
|
name: system:auth-delegator
|
|
apiGroup: rbac.authorization.k8s.io
|
|
---
|
|
kind: ClusterRole
|
|
apiVersion: rbac.authorization.k8s.io/v1
|
|
metadata:
|
|
name: service-account-getter
|
|
namespace: default
|
|
rules:
|
|
- apiGroups: ['']
|
|
resources: ['serviceaccounts']
|
|
verbs: ['get']
|
|
---
|
|
kind: ClusterRoleBinding
|
|
apiVersion: rbac.authorization.k8s.io/v1
|
|
metadata:
|
|
name: get-service-accounts
|
|
namespace: default
|
|
subjects:
|
|
- kind: ServiceAccount
|
|
name: consul-auth-method-example
|
|
namespace: default
|
|
roleRef:
|
|
kind: ClusterRole
|
|
name: service-account-getter
|
|
apiGroup: rbac.authorization.k8s.io
|
|
```
|
|
|
|
## Kubernetes Authentication Details
|
|
|
|
Initially the
|
|
[`ServiceAccountJWT`](/consul/docs/security/acl/auth-methods/kubernetes#serviceaccountjwt)
|
|
given to the Consul leader uses the TokenReview API to validate the provided
|
|
JWT. The trusted attributes of `serviceaccount.namespace`,
|
|
`serviceaccount.name`, and `serviceaccount.uid` are populated directly from the
|
|
Service Account metadata.
|
|
|
|
The Consul leader makes an additional query, this time to the ServiceAccount
|
|
API to check for the existence of an annotation of
|
|
`consul.hashicorp.com/service-name` on the ServiceAccount object. If one is
|
|
found its value will override the trusted attribute of `serviceaccount.name`
|
|
for the purposes of evaluating any binding rules.
|
|
|
|
## Trusted Identity Attributes
|
|
|
|
The authentication step returns the following trusted identity attributes for
|
|
use in binding rule selectors and bind name interpolation.
|
|
|
|
| Attributes | Supported Selector Operations | Can be Interpolated |
|
|
| -------------------------- | -------------------------------------------------- | ------------------- |
|
|
| `serviceaccount.namespace` | Equal, Not Equal, In, Not In, Matches, Not Matches | yes |
|
|
| `serviceaccount.name` | Equal, Not Equal, In, Not In, Matches, Not Matches | yes |
|
|
| `serviceaccount.uid` | Equal, Not Equal, In, Not In, Matches, Not Matches | yes |
|