Workload identity for Kubernetes (JWT-based authentication)
An workload identity is an identity used by workloads to authenticate to Conjur and access secrets. This topic describes how to define workload identities in Conjur for Kubernetes workloads
For more general information about workloads in Conjur, see Workloads in Conjur.
Service account token (JWT)
The subject (sub
) of a JWT is the fully qualified service account identity which combines the namespace
and serviceaccount
names.
"sub": "system:serviceaccount:test-app-namespace:test-app-sa"
-
The Namespace name in a Kubernetes cluster is unique.
-
The service account in a Namespace is unique.
Let's examine the claims in the following sample JWT:
{ "aud": [ "https://conjur.host.name/" ], "exp": 1637781121, "iat": 1637773921, "iss": "https://kubernetes.default.svc.cluster.local", "kubernetes.io": { "namespace": "test-app-namespace", "pod": { "name": "test-app-pod-554b4c6496-m849s", "uid": "e71d7a37-0725-4cf7-a685-c5a43d94f6ea" }, "serviceaccount": { "name": "test-app-sa", "uid": "ee0952eb-72df-4d98-a3a6-e1550e9e63cc" } }, "nbf": 1637773921, "sub": "system:serviceaccount:test-app-namespace:test-app-sa" }
The following claims from the JWT can be used to define a Kubernetes workload identity in Conjur:
Claim path |
Description |
---|---|
|
Identifies possible token recipients. We recommend narrowing down the In parallel, when defining the JWT Authenticator policy, we also recommend utilizing this claim in combination with the For more details about defining the JWT Authenticator policy, see JWT-based Kubernetes authentication. |
|
The Namespace name (unique at the Kubernetes cluster level) This can be used as the workload identity name. In parallel, when defining the JWT Authenticator policy, use the |
|
Pod name (unique at the namespace level) Usually not constant for Pods created from Deployments, StatefulSets or for Pods that are part of an auto-scaling group. In cases where the Pod name is a constant, this can be used together with the |
|
Service account name (unique at the namespace level) If your organization allows creating a service account with the same name in another namespace, we recommend that you do not use the value from this claim on its own. |
|
Combination of namespace and service account names (unique at the Kubernetes cluster level) Provides the highest identity granularity. We strongly recommend using the value of this claim as the name for the workload identity, together with one host annotation. In parallel, use the |
Workload identity for Kubernetes resources
In Conjur, a workload is represented as a host
and its identifying attributes are is defined in policy using host annotations. These annotations determine the granularity at which authentication of the workload is performed and access is granted to the workload.
This section demonstrates how you would define a workload identity in Conjur for a Kubernetes resource based on claims in the service account token (JWT).
Once you have decided on the granularity of authentication and secret access that you want to enforce, you set up and load the relevant JWT Authenticator and host
policies.
For example, to control authentication and secret access by the test-app-namespace
namespace and test-app-sa
service account, you'd first define the JWT Authenticator in a policy as follows:
-
You'd include the
token-app-property
variable, and set its value tosub
-
You'd include the
identity-path
variable, and set its value toapp-path
Next, you'd define a policy for the workload identity (host
) as follows::
-
You'd name the
host id
for the expectedsub
claim value. For example, using the sample claim earlier in this topic, thehost id
would besystem:serviceaccount:test-app-namespace:test-app-sa
-
You'd include one host annotation,
authn-jwt/<serviceId>/sub
, whose value would be equivalent to the value of thesub
claim
- !policy
id: app-path
body:
- !host
id: system:serviceaccount:test-app-namespace:test-app-sa
annotations:
authn-jwt/<serviceId>/sub: system:serviceaccount:test-app-namespace:test-app-sa
Relationship between the JWT Authenticator and the workload identity
The following table lists the possible token-app-property
values you could use in your JWT Authenticator policy, and the respective annotation that you'd need to define in the host
policy:
token-app-property format |
Annotation format |
Description |
---|---|---|
|
|
Expected |
|
|
Expected |
|
|
Expected |
|
|
Expected |
When multiple applications are running in the same namespace and each application needs access to different secrets, you'd need to create a dedicated service account for each application and a respective workload identity in Conjur.
Each service account should be mapped into the relevant workload Pod and the service account should be projected to the relevant container.