Add traditional SAN names to workload certificates#

Overview#

Introduction#

As part of establishing an encrypted (TLS or mTLS) connection (after certificate validation), one peer validates the other peer’s identity by checking to see that an expected name is included in the set of names in the workload certificate presented by the other peer. If the check is successful, the peer trusts the identity of the other peer.

Off-mesh applications typically validate identities using traditional SAN names#

The type of name that the Aspen Mesh certificate authorities (CAs) automatically include in the workload certificates they create is considered a nontraditional SAN name because it’s uncommon for off-mesh applications to use that type of name for identity validation. Off-mesh applications typically use a traditional SAN name instead.

Note

If you haven’t already done so, learn about the Aspen Mesh certificate authorities (CAs) and the types of pods they support.

When to add traditional SAN names to workload certificates#

Add traditional SAN names to workload certificates when both of the following are true:

Your off-mesh application needs to validate the identity of a pod (or pod interface) whose workload certificate is created by one of the Aspen Mesh CAs.
You don’t want to rewrite your off-mesh application to perform identity validation using a nontraditional SAN name.

About names in workload certificates#

Fields for specifying names for a workload certificate#

A workload certificate is valid for one or more identity-validation names, which are specified using two fields in the certificate:

Field	Description
Common Name (CN)	The original field in the X.509 certificate specification. Specifies a single name (for example, `www.example.com`) for which a certificate is valid.
Subject Alternative Name (SAN)	A new field added in an extension to the X.509 certificate specification. Specifies additional names (for example, `DNS:test.example.com` or `URI:com.example.uuid:cc1bf660-9e35-4169-9bbf-2a893ea2fa5d`) for which a certificate is valid.

Types of SAN names#

In Aspen Mesh, there are two types of identity-validation names that can be specified in the SAN field:

Nontraditional SAN names
Traditional SAN names

Definition: Nontraditional SAN name#

A nontraditional SAN name is a name in the SAN field that is specified as a SPIFFE URI (for example, URI:spiffe://cluster.local/ns/default/sa/httpbin).

Nontraditional SAN names are always enabled for both Istiod and Citadel (if installed), are unique to the service account that the workload is configured to use, and are automatically included in workload certificates that both CAs create.

Definition: Traditional SAN name#

A traditional SAN name is a name in the SAN field that is specified as one of the following:

A DNS name (for example, DNS:test.example.com or DNS:httpbin.example.com)
A non-SPIFFE URI (for example, URI:com.example.uuid:cc1bf660-9e35-4169-9bbf-2a893ea2fa5d or URI:http://test.example.com/get)

Enable traditional SAN names#

About enabling traditional SAN names#

Traditional SAN names are disabled by default for Istiod. If you want Istiod to add traditional SAN names to the workload certificates it creates, you must enable traditional SAN names for Istiod.

Traditional SAN names are always enabled for Citadel and can’t be disabled, so Citadel (if installed) always adds traditional SAN names to the workload certificates it creates.

Why you should enable traditional SAN names for Istiod#

Enable traditional SAN names for Istiod so off-mesh, on-cluster non-gateway pods (whose certificates are created by Citadel) can use DNS names and non-SPIFFE URIs to validate the identities of on-mesh non-gateway pods and the on-mesh interfaces of Istio gateway pods (whose certificates are created by Istiod).

Enable traditional SAN names for Istiod#

Open your Aspen Mesh override values file (aspen-mesh-override-values.yaml) in a text editor.

Copy the following information and paste it into the file:

global:
  # Enable traditional SAN names for Istiod.
  certificateCustomFields: true

Save and close the file.
Perform an upgrade of Aspen Mesh from the current version to the same version (perform only the tasks in that section).

Traditional SAN names are now enabled for Istiod. Istiod includes traditional SAN names in the workload certificates it creates.

Default traditional SAN name for a workload#

If you don’t specify custom traditional SAN names for a workload, Istiod (if traditional SAN names are enabled for it) and Citadel (if installed) add a default traditional SAN name of the following form to the workload certificates they create for all pods (or pod interfaces) in that workload:

DNS:<serviceAccountName>.<namespaceName>.svc.cluster.local

where <serviceAccountName> is the name of the service account that the workload is configured to use.

Examples

DNS:default.alpha.svc.cluster.local

DNS:sleep.beta.svc.cluster.local

Which items can perform identity validation using traditional SAN names#

On-mesh items always validate identities using a nontraditional SAN name#

For a pod (or pod interface) whose workload certificate is created by Istiod (regardless of whether traditional SAN names are enabled for it) or Citadel (if installed) and whose identity is being validated, on-mesh items always perform identity validation using a nontraditional SAN name (SPIFFE URI):

This type of on-mesh item	Can use this type of name	To validate the identity of this type of pod (or pod interface)
On-mesh non-gateway pod	SPIFFE URI only	Off-mesh, on-cluster non-gateway pod
On-mesh non-gateway pod	SPIFFE URI only	On-mesh non-gateway pod
On-mesh non-gateway pod	SPIFFE URI only	On-mesh interface of an Istio gateway pod
On-mesh interface of an Istio gateway pod	SPIFFE URI only	Off-mesh, on-cluster non-gateway pod
On-mesh interface of an Istio gateway pod	SPIFFE URI only	On-mesh non-gateway pod

Off-mesh items can validate identities using a nontraditional or traditional SAN name#

For a pod (or pod interface) whose workload certificate is created by Istiod (if traditional SAN names are enabled for it) or Citadel (if installed) and whose identity is being validated, off-mesh items can perform identity validation using a nontraditional SAN name (SPIFFE URI) or a traditional SAN name (DNS name or non-SPIFFE URI):

This type of off-mesh item	Can use this type of name	To validate the identity of this type of pod (or pod interface)
Off-mesh, on-cluster non-gateway pod	SPIFFE URI, DNS name, or non-SPIFFE URI	Off-mesh, on-cluster non-gateway pod
Off-mesh, on-cluster non-gateway pod	SPIFFE URI, DNS name, or non-SPIFFE URI	On-mesh non-gateway pod
Off-mesh, on-cluster non-gateway pod	SPIFFE URI, DNS name, or non-SPIFFE URI	On-mesh interface of an Istio gateway pod
Off-mesh, off-cluster workload	SPIFFE URI, DNS name, or non-SPIFFE URI	Off-mesh interface of an Istio gateway pod

Specify custom traditional SAN names for a workload#

About specifying custom traditional SAN names for a workload#

If you don’t want to use the default traditional SAN name for a workload, you can specify custom traditional SAN names:

Istiod (if traditional SAN names are enabled for it) adds the custom traditional SAN names instead of the default traditional SAN name to the workload certificates it creates for all pods (or pod interfaces) whose workloads are configured to use a particular service account.
Citadel (if installed) adds the custom traditional SAN names instead of the default traditional SAN name to the workload certificates it creates for all pods whose workloads (or all pod interfaces whose gateways) are configured to use the Citadel workload certificate for a particular service account. Note that this is not necessarily the service account that the workload itself is configured to use.

Specify custom traditional SAN names for a workload#

Open the manifest for the appropriate service account in a text editor.

Use this table to determine which service-account manifest to open:

If you want to specify custom traditional SAN names for	Then open the manifest for the service account
The pods in an on-mesh non-gateway workload	That the workload is configured to use
The on-mesh interfaces of the pods in an Istio gateway workload	That the workload is configured to use
The pods in an off-mesh, on-cluster non-gateway workload	Whose Citadel workload certificate the non-gateway workload is configured to use
The off-mesh interfaces of the pods in an Istio gateway workload	Whose Citadel workload certificate the Istio gateway (not the Istio gateway workload) is configured to use

In the .metadata field, add an annotations field.

Example

apiVersion: v1
kind: ServiceAccount
metadata:
  name: <serviceAccountName>
  annotations:

In the .metadata.annotations field, add the following certificate.aspenmesh.io/customFields field and value as a template:

"certificate.aspenmesh.io/customFields": '{ "SAN": { "DNS": [ "<dnsName>" ], "URI": [ "<nonSpiffeUri>" ] } }'

Example

apiVersion: v1
kind: ServiceAccount
metadata:
  name: <serviceAccountName>
  annotations:
    "certificate.aspenmesh.io/customFields": '{ "SAN": { "DNS": [ "<dnsName>" ], "URI": [ "<nonSpiffeUri>" ] } }'

Modify the value of the certificate.aspenmesh.io/customFields field to specify custom traditional SAN names:
- To specify only DNS names, delete , "URI": [ "<nonSpiffeUri>" ].
- To specify only non-SPIFFE URIs, delete "DNS": [ "<dnsName>" ], .
- To specify more than one DNS name or non-SPIFFE URI, separate each one (in quotation marks) with a comma.
Example
```
apiVersion: v1
kind: ServiceAccount
metadata:
  name: <serviceAccountName>
  annotations:
    "certificate.aspenmesh.io/customFields": '{ "SAN": { "DNS": [ "test.example.com", "httpbin.example.com" ], "URI": [ "com.example.uuid:cc1bf660-9e35-4169-9bbf-2a893ea2fa5d", "http://test.example.com/get" ] } }'
```
Note

DNS names and non-SPIFFE URIs are the only types of traditional SAN names supported by the Aspen Mesh CAs. You may not specify other types of traditional SAN names (for example, IP addresses).
Save and close the manifest.

If the service account is already running, update the service account:

$ kubectl apply -f <serviceAccountManifestFilename> --namespace <namespaceName>

For each on-mesh workload that is running and is configured to use the service account, restart all pods in the workload.

Example
```
$ kubectl rollout restart deployment <deploymentName> --namespace <namespaceName>
```
If traditional SAN names are enabled for Istiod, Istiod adds the traditional SAN names you specified in the service account to the workload certificates for the following items (and deletes the default traditional SAN name from those certificates):
- The pods in on-mesh non-gateway workloads configured to use the service account
- The on-mesh interfaces of the pods in Istio gateway workloads configured to use the service account
If Citadel is installed, Citadel adds the traditional SAN names you specified in the service account to the workload certificates for the following items (and deletes the default traditional SAN name from those certificates):
- The pods in off-mesh, on-cluster non-gateway workloads configured to use the service account’s Citadel workload certificate
- The off-mesh interfaces of the workload pods for Istio gateways configured to use the service account’s Citadel workload certificate