Merge pull request #42 from Keyfactor/release-2.1

Release 2.1

Author: spbsoluble

CHANGELOG.md

@@ -48,3 +48,11 @@
 ## Fixes
 - Updated library golang.org/x/crypto to version v0.33.0 to address authorization bypass vulnerability (https://github.com/advisories/GHSA-v778-237x-gjrc)
 - Bug fix for Google ambient credentials
+
+# v2.1.1
+
+## Fixes
+- Update Helm chart deployment template to resolve Docker image metadata issue.
+
+## Chores
+- Update documentation for more clear instructions on deploying workloads to Azure Kubernetes Service and Google Kubernetes Engine, as well as permissions needed on Command Security Roles.

README.md

@@ -71,24 +71,36 @@ Command Issuer enrolls certificates by submitting a POST request to the Command
 
     - If you don't have any suitable Certificate Templates, refer to the [Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/Configuring%20Template%20Options.htm?Highlight=Certificate%20Template) or reach out to your Keyfactor support representative to learn more.
 
-    The Certificate Template that you shoose must be configured to allow CSR Enrollment.
+    The Certificate Template that you choose must be configured to allow CSR Enrollment.
 
     You should make careful note of the allowed Key Types and Key Sizes on the Certificate Template. When creating cert-manager [Certificates](https://cert-manager.io/docs/usage/certificate/), you must make sure that the key `algorithm` and `size` are allowed by your Certificate Template in Command.    
 
     The same goes for **Enrollment RegExes** and **Policies** defined on your Certificate Template. When creating cert-manager [Certificates](https://cert-manager.io/docs/usage/certificate/), you must make sure that the `subject`, `commonName`, `dnsNames`, etc. are allowed and/or configured correctly by your Certificate Template in Command.
 
 3. **Configure Command Security Roles and Claims**
 
-    In Command, Security Roles define groups of users or administrators with specific permissions. Users and subjects are identified by Claims. By adding a Claim to a Security Role, you can define what actions the user or subject can perform and what parts of the system it can interact with.  
+    In Command, Security Roles define groups of users or administrators with specific permissions. Users and subjects are identified by Claims. By adding a Claim to a Security Role, you can define what actions the user or subject can perform and what parts of the system it can interact with.
+
+    The security role will need to be added as an Allowed Requester Security Role on the Certificate Authority and Certificate Template configured in the previous two steps.
 
     - If you haven't created Roles and Access rules before, [this guide](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/SecurityOverview.htm?Highlight=Security%20Roles) provides a primer on these concepts in Command.
 
-    If your security policy requires fine-grain access control, Command Issuer requires the following Access Rules.
+    If your security policy requires fine-grain access control, Command Issuer requires the following Access Rules:
+
+    | Global Permissions                    | Permission Model (Version Two) | Permission Model (Version One) |
+    |-----------------------------------------|---|---|
+    | Metadata > Types > Read | `/metadata/types/read/` | `CertificateMetadataTypes:Read` |
+    | Certificates > Enrollment > Csr | `/certificates/enrollment/csr/` | `CertificateEnrollment:EnrollCSR`  |
+
+    > Documentation for [Version Two Permission Model](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/SecurityRolePermissions.htm#VersionTwoPermissionModel) and [Version One Permission Model](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/SecurityRolePermissions.htm#VersionOnePermissionModel)
+
+![Permission Metadata Read](./docsource/images/security_permission_metadata_read.png)
+
+![Permission Certificate CSR Enrollment](./docsource/images/security_permission_enrollment_csr.png)
+
+![Certificate Authority Allowed Requester](./docsource/images/ca_allowed_requester.png)
 
-    | Global Permissions                    |
-    |-----------------------------------------|
-    | `CertificateMetadataTypes:Read` |
-    | `CertificateEnrollment:EnrollCSR`  |
+![Certificate Template Allowed Requester](./docsource/images/cert_template_allowed_requester.png)
 
 ## Installing Command Issuer
 
@@ -173,11 +185,18 @@ kubectl -n command-issuer-system create secret generic command-secret \
 
 Azure Entra ID workload identity in Azure Kubernetes Service (AKS) allows Command Issuer to exchange a Kubernetes ServiceAccount Token for an Azure Entra ID access token, which is then used to authenticate to Command.
 
+At this time, Azure Kuberentes Services workload identity federation is best supported by [User Assigned Managed Identities](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities?pivots=identity-mi-methods-azp). Other identity solutions such as Azure AD Service Principals are not supported.
+
+Here is a guide on how to use Azure User Assigned Managed Identities to authenticate your AKS workload with your Keyfactor Command instance.
+
 1. Reconfigure the AKS cluster to enable workload identity federation.
 
     ```shell
+    export CLUSTER_NAME=<cluster-name>
+    export RESOURCE_GROUP=<resource-group>
     az aks update \
-        --name ${CLUSTER} \
+        --name ${CLUSTER_NAME} \
+        --resource-group ${RESOURCE_GROUP} \
         --enable-oidc-issuer \
         --enable-workload-identity
     ```
@@ -186,16 +205,28 @@ Azure Entra ID workload identity in Azure Kubernetes Service (AKS) allows Comman
     >
     > Refer to the [AKS documentation](https://learn.microsoft.com/en-us/azure/aks/workload-identity-deploy-cluster) for more information on the `--enable-workload-identity` feature.
 
-2. Reconfigure or deploy Command Issuer with extra labels for the Azure Workload Identity webhook, which will result in the Command Issuer controller Pod having an extra volume containing a Kubernetes ServiceAccount token which it will exchange for a token from Azure.
+2. Create a User Assigned Managed Identity in Azure.
+
+    ```shell
+    export IDENTITY_NAME=command-issuer
+    az identity create --name "${IDENTITY_NAME}" --resource-group "${RESOURCE_GROUP}"
+    ```
+    > Read more about [the `az identity` command](https://learn.microsoft.com/en-us/cli/azure/identity?view=azure-cli-latest).
+
+3. Reconfigure or deploy Command Issuer with extra labels for the Azure Workload Identity webhook, which will result in the Command Issuer controller Pod having an extra volume containing a Kubernetes ServiceAccount token which it will exchange for a token from Azure.
 
     ```shell
+    export UAMI_CLIENT_ID=$(az identity show --name $IDENTITY_NAME --resource-group $RESOURCE_GROUP --query clientId --output tsv)
+
+    echo "Identity Client ID: ${UAMI_CLIENT_ID}"
+
     helm install command-cert-manager-issuer command-issuer/command-cert-manager-issuer \
         --namespace command-issuer-system \
         --create-namespace \
-        --set "fullnameOverride=$chart_name" \
+        --set "fullnameOverride=command-cert-manager-issuer" \
         --set-string "podLabels.azure\.workload\.identity/use=true" \
-        --set-string "serviceAccount.labels.azure\.workload\.identity/use=true"
-        # --set-string "serviceAccount.annotations.azure\.workload\.identity/client-id=<managed identity client ID>" # May be necessary, but is usually not.
+        --set-string "serviceAccount.labels.azure\.workload\.identity/use=true" \
+        --set-string "serviceAccount.annotations.azure\.workload\.identity/client-id=${UAMI_CLIENT_ID}"
     ```
 
     If successful, the Command Issuer Pod will have new environment variables and the Azure WI ServiceAccount token as a projected volume:
@@ -209,7 +240,7 @@ Azure Entra ID workload identity in Azure Kubernetes Service (AKS) allows Comman
       command-cert-manager-issuer:
         ...
         Environment:
-          AZURE_CLIENT_ID:             <GUID>
+          AZURE_CLIENT_ID:             <UAMI_CLIENT_ID>
           AZURE_TENANT_ID:             <GUID>
           AZURE_FEDERATED_TOKEN_FILE:  /var/run/secrets/azure/tokens/azure-identity-token
           AZURE_AUTHORITY_HOST:        https://login.microsoftonline.com/
@@ -226,35 +257,83 @@ Azure Entra ID workload identity in Azure Kubernetes Service (AKS) allows Comman
 
     > Refer to [Azure Workload Identity docs](https://azure.github.io/azure-workload-identity/docs/installation/mutating-admission-webhook.html) more information on the role of the Mutating Admission Webhook.
 
-3. Create a User Assigned Managed Identity in Azure.
-
-    ```shell
-    export IDENTITY_NAME=command-issuer
-    az identity create --name "${IDENTITY_NAME}"
-    ```
-
-    > Read more about [the `az identity` command](https://learn.microsoft.com/en-us/cli/azure/identity?view=azure-cli-latest).
-
 4. Associate a Federated Identity Credential (FIC) with the User Assigned Managed Identity. The FIC allows Command Issuer to act on behalf of the Managed Identity by telling Azure to expect:
     - The `iss` claim of the ServiceAccount token to match the cluster's OIDC Issuer. Azure will also use the Issuer URL to download the JWT signing certificate.
     - The `sub` claim of the ServiceAccount token to match the ServiceAccount's name and namespace.
 
     ```shell
     export SERVICE_ACCOUNT_NAME=command-cert-manager-issuer # This is the default Kubernetes ServiceAccount used by the Command Issuer controller.
     export SERVICE_ACCOUNT_NAMESPACE=command-issuer-system # This is the default namespace for Command Issuer used in this doc.
-    export SERVICE_ACCOUNT_ISSUER=$(az aks show --resource-group $AZURE_DEFAULTS_GROUP --name $CLUSTER --query "oidcIssuerProfile.issuerUrl" -o tsv)
+
+    export SERVICE_ACCOUNT_ISSUER=$(az aks show --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --query "oidcIssuerProfile.issuerUrl" -o tsv)
     az identity federated-credential create \
-        --name "command-issuer" \
+        --name "${IDENTITY_NAME}-federated-credentials" \
         --identity-name "${IDENTITY_NAME}" \
+        --resource-group "${RESOURCE_GROUP}" \
         --issuer "${SERVICE_ACCOUNT_ISSUER}" \
-        --subject "system:serviceaccount:${SERVICE_ACCOUNT_NAMESPACE}:${SERVICE_ACCOUNT_NAME}"
+        --subject "system:serviceaccount:${SERVICE_ACCOUNT_NAMESPACE}:${SERVICE_ACCOUNT_NAME}" \
+        --audiences "api://AzureADTokenExchange"
     ```
 
     > Read more about [Workload Identity federation](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation) in the Entra ID documentation.
     >
     > Read more about [the `az identity federated-credential` command](https://learn.microsoft.com/en-us/cli/azure/identity/federated-credential?view=azure-cli-latest).
 
-5. Add Microsoft Entra ID as an [Identity Provider in Command](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/IdentityProviders.htm?Highlight=identity%20provider), and [add the Managed Identity's Client ID as an `oid` claim to the Security Role](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/SecurityOverview.htm?Highlight=Security%20Roles) created/identified earlier.
+5. Get the Managed Identity's Principal ID and Entra Identity Provider Information
+
+  ```shell
+  export UAMI_PRINCIPAL_ID=$(az identity show --name $IDENTITY_NAME --resource-group $RESOURCE_GROUP --query principalId --output tsv)
+  export CURRENT_TENANT=$(az account show --query tenantId --output tsv)
+  echo "UAMI Principal ID: ${UAMI_PRINCIPAL_ID}"
+
+  echo "View then OIDC configuration for the Entra OIDC token issuer: https://login.microsoftonline.com/$CURRENT_TENANT/v2.0/.well-known/openid-configuration"
+  
+  echo "Authority: https://login.microsoftonline.com/$CURRENT_TENANT/v2.0"
+  ```
+
+  > **IMPORTANT NOTE**: The Microsoft Entra Identity Provider is associated with your Azure tenant ID. Multi-tenant Azure workloads will require a Command Identity Provider for each tenant. 
+
+6. Add the Microsoft Entra ID as an [Identity Provider in Command](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/IdentityProviders.htm?Highlight=identity%20provider) using the identity provider information from the previous step, and [add the Managed Identity's Principal ID as an `OAuth Subject` claim to the Security Role](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/SecurityOverview.htm?Highlight=Security%20Roles) created/identified earlier.
+
+## Google Kubernetes Engine (GKE) Workload Identity
+
+Google Kuberentes Engine (GKE) supports the ability to authenticate your GKE workloads using workload identity. 
+
+By default, GKE clusters are assigned the [default service account](https://cloud.google.com/compute/docs/access/service-accounts#token) for your Google project. This service account is used to generate an ID token for your workload. However, you may opt to use [Workload Identity Federation](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#metadata-server) to your GKE cluster.
+
+1. Get the OAuth Client and Identity Provider for your GKE Cluster
+
+  Regardless if you are using the default service account or a custom service account, the following script will help you derive your GKE cluster's OAuth Client:
+
+  ```shell
+  export CLUSTER_NAME=<cluster-name>
+  export GCLOUD_REGION=<region>
+  export GCLOUD_PROJECT_ID=$(gcloud config get-value project) # populate with the current PROJECT_ID context
+  export GCLOUD_PROJECT_NUMBER=$(gcloud projects describe $GCLOUD_PROJECT_ID --format="value(projectNumber)")
+    
+  export GCLOUD_SERVICE_ACCOUNT=$(gcloud container clusters describe $CLUSTER_NAME \
+  --zone $GCLOUD_REGION \
+  --format="value(nodeConfig.serviceAccount)")
+
+  if [[ "$GCLOUD_SERVICE_ACCOUNT" == "default" ]]; then
+    # Override service account with default compute service account
+    GCLOUD_SERVICE_ACCOUNT="[email protected]"
+  fi
+  
+  echo "Service account: $GCLOUD_SERVICE_ACCOUNT"
+  
+  # Get OAuth2 Client ID of service account
+  export GCLOUD_SERVICE_ACCOUNT_CLIENT_ID=$(gcloud iam service-accounts describe $GCLOUD_SERVICE_ACCOUNT \
+  --format="value(oauth2ClientId)")
+  
+  echo "Service account OAuth2 client ID: $GCLOUD_SERVICE_ACCOUNT_CLIENT_ID"
+  
+  echo "View the OIDC configuration for Google's OIDC token issuer: https://accounts.google.com/.well-known/openid-configuration"
+  
+  echo "Authority: https://accounts.google.com"
+  ```
+
+2. Add Google as an [Identity Provider in Command](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/IdentityProviders.htm?Highlight=identity%20provider) using the identity provider information from the previous step, and [add the Service Account's OAuth Client ID as an `OAuth Subject` claim to the Security Role](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/SecurityOverview.htm?Highlight=Security%20Roles) created/identified earlier.
 
 # CA Bundle
 

deploy/charts/command-cert-manager-issuer/README.md

@@ -6,9 +6,7 @@
 
 [![Go Report Card](https://goreportcard.com/badge/github.com/Keyfactor/command-cert-manager-issuer)](https://goreportcard.com/report/github.com/Keyfactor/command-cert-manager-issuer)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://img.shields.io/badge/License-Apache%202.0-blue.svg)
-![Version: v1.0.3](https://img.shields.io/badge/Version-v1.0.3-informational?style=flat-square)
 ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square)
-![AppVersion: v1.0.3](https://img.shields.io/badge/AppVersion-v1.0.3-informational?style=flat-square)
 
 A Helm chart for the Keyfactor Command External Issuer for cert-manager.
 

deploy/charts/command-cert-manager-issuer/templates/deployment.yaml

@@ -38,7 +38,7 @@ spec:
             {{- end}}
           command:
             - /manager
-          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
+          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.Version }}"
           imagePullPolicy: {{ .Values.image.pullPolicy }}
           livenessProbe:
             httpGet:

deploy/charts/command-cert-manager-issuer/values.yaml

@@ -6,7 +6,7 @@ replicaCount: 1
 image:
   repository: "keyfactor/command-cert-manager-issuer"
   pullPolicy: IfNotPresent
-  # Overrides the image tag whose default is the chart appVersion.
+  # Overrides the image tag whose default is the chart version.
   tag: ""
 
 imagePullSecrets: []