Authenticating pods with short-term credentials¶

Some OpenShift Container Platform clusters use short-term security credentials, created and managed outside the cluster, for individual components. Applications in customer workloads on these clusters can authenticate by using the short-term authentication method that the cluster uses.

Short-term authentication for workloads¶

To use short-term authentication in your applications, you must configure access in your cloud provider, create an OpenShift Container Platform service account, and deploy workloads that use this authentication method.

1. Create a federated identity service account in the Identity and Access Management (IAM) settings for your cloud provider.
2. Create an OpenShift Container Platform service account that can impersonate a service account for your cloud provider.
3. Configure any workloads related to your application to use the OpenShift Container Platform service account.

Environment and user access requirements¶

To configure short-term authentication for workloads, you must meet specific environment and user access requirements.

To configure this authentication method, you must meet the following requirements:

• Your cluster must use short-term security credentials.
• You must have access to the OpenShift CLI (oc) as a user with the cluster-admin role.
• In your cloud provider console, you must have access as a user with privileges to manage Identity and Access Management (IAM) and federated identity configurations.

GCP Workload Identity authentication for applications on Google Cloud¶

You can configure GCP Workload Identity authentication so that applications on a Google Cloud cluster can authenticate with Google Cloud services by using short-term credentials instead of long-lived service account keys.

To configure this authentication method, complete the following tasks:

• Configure access in Google Cloud.
• Create an OpenShift Container Platform service account that can use this access.
• Deploy customer workloads that authenticate with GCP Workload Identity.

Creating a federated Google Cloud service account¶

You can use the Google Cloud console to create a workload identity pool and provider and allow an OpenShift Container Platform service account to impersonate a Google Cloud service account.

Prerequisites

• Your Google Cloud cluster uses GCP Workload Identity.
• You have access to the Google Cloud console as a user with privileges to manage Identity and Access Management (IAM) and workload identity configurations.
• You have created a Google Cloud project to use with your application.

Procedure

1. In the IAM configuration for your Google Cloud project, identify the identity pool and provider that the cluster uses for GCP Workload Identity authentication.
2. Grant permission for external identities to impersonate a Google Cloud service account. With these permissions, an OpenShift Container Platform service account can work as a federated workload identity.

   For more information, see Google Cloud documentation about allowing your external workload to access Google Cloud resources.

Creating an OpenShift Container Platform service account for Google Cloud¶

You create an OpenShift Container Platform service account and annotate it to impersonate a Google Cloud service account.

Prerequisites

• Your Google Cloud cluster uses GCP Workload Identity.
• You have created a federated Google Cloud service account.
• You have access to the OpenShift CLI (oc) as a user with the cluster-admin role.
• You have access to the Google Cloud CLI (gcloud) as a user with privileges to manage Identity and Access Management (IAM) and workload identity configurations.

Procedure

1. Create an OpenShift Container Platform service account to use for GCP Workload Identity pod authentication by running the following command:
   terminal

   $ oc create serviceaccount <service_account_name>

2. Annotate the service account with the identity provider and Google Cloud service account to impersonate by running the following command:
   terminal

   $ oc patch serviceaccount <service_account_name> -p '{"metadata": {"annotations": {"cloud.google.com/workload-identity-provider": "projects/<project_number>/locations/global/workloadIdentityPools/<identity_pool>/providers/<identity_provider>"}}}'

   Replace <project_number>, <identity_pool>, and <identity_provider> with the values for your configuration.

   Note

   For <project_number>, specify the Google Cloud project number, not the project ID.

3. Annotate the service account with the email address for the Google Cloud service account by running the following command:
   terminal

   $ oc patch serviceaccount <service_account_name> -p '{"metadata": {"annotations": {"cloud.google.com/service-account-email": "<service_account_email>"}}}'

   Replace <service_account_email> with the email address for the Google Cloud service account.

   Tip

   Google Cloud service account email addresses typically use the format <service_account_name>@<project_id>.iam.gserviceaccount.com

4. Annotate the service account to use the direct external credentials configuration injection mode by running the following command:
   terminal

   $ oc patch serviceaccount <service_account_name> -p '{"metadata": {"annotations": {"cloud.google.com/injection-mode": "direct"}}}'

   In this mode, the Workload Identity Federation webhook controller directly generates the Google Cloud external credentials configuration and injects them into the pod.

5. Use the Google Cloud CLI (gcloud) to specify the permissions for the workload by running the following command:
   terminal

   $ gcloud projects add-iam-policy-binding <project_id> --member "<service_account_email>" --role "projects/<project_id>/roles/<role_for_workload_permissions>"

   Replace <role_for_workload_permissions> with the role for the workload. Specify a role that grants the permissions that your workload requires.

Verification

• To verify the service account configuration, inspect the ServiceAccount manifest by running the following command:
  terminal

  $ oc get serviceaccount <service_account_name>

  In the following example, the service-a/app-x OpenShift Container Platform service account can impersonate a Google Cloud service account called app-x:

  Example output

  apiVersion: v1
  kind: ServiceAccount
  metadata:
    name: app-x
    namespace: service-a
    annotations:
      cloud.google.com/workload-identity-provider: "projects/<project_number>/locations/global/workloadIdentityPools/<identity_pool>/providers/<identity_provider>"
      cloud.google.com/service-account-email: "app-x@project.iam.googleapis.com"
      cloud.google.com/audience: "sts.googleapis.com"
      cloud.google.com/token-expiration: "86400"
      cloud.google.com/gcloud-run-as-user: "1000"
      cloud.google.com/injection-mode: "direct"

  where:

  metadata.annotations.cloud.google.com/workload-identity-provider

  Specifies the workload identity provider for the service account of the cluster.

  metadata.annotations.cloud.google.com/audience

  Specifies the allowed audience for the workload identity provider.

  metadata.annotations.cloud.google.com/token-expiration

  Specifies the token expiration time period in seconds.

  metadata.annotations.cloud.google.com/injection-mode

  Specifies the direct external credentials configuration injection mode.

Deploying customer workloads that authenticate with GCP Workload Identity¶

To use short-term authentication in your application, you must configure its related pods to use the OpenShift Container Platform service account. Use of the OpenShift Container Platform service account triggers the webhook to mutate the pods so they can impersonate the Google Cloud service account.

The following example demonstrates how to deploy a pod that uses the OpenShift Container Platform service account and verify the configuration.

Prerequisites

• Your Google Cloud cluster uses GCP Workload Identity.
• You have created a federated Google Cloud service account.
• You have created an OpenShift Container Platform service account for Google Cloud.

Procedure

1. To create a pod that authenticates with GCP Workload Identity, create a deployment YAML file similar to the following example:
   Sample deployment

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: ubi9
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: ubi9
     template:
       metadata:
         labels:
           app: ubi9
       spec:
         serviceAccountName: "<service_account_name>"
         containers:
           - name: ubi
             image: 'registry.access.redhat.com/ubi9/ubi-micro:latest'
             command:
               - /bin/sh
               - '-c'
               - |
                 sleep infinity

   Replace <service_account_name> with the name of the OpenShift Container Platform service account.

2. Apply the deployment file by running the following command:
   terminal

   $ oc apply -f deployment.yaml

Verification

1. To verify that a pod is using short-term authentication, run the following command:
   terminal

   $ oc get pods -o json | jq -r '.items[0].spec.containers[0].env[] | select(.name=="GOOGLE_APPLICATION_CREDENTIALS")'

   Example output:

   {   "name": "GOOGLE_APPLICATION_CREDENTIALS",   "value": "/var/run/secrets/workload-identity/federation.json" }

   The presence of the GOOGLE_APPLICATION_CREDENTIALS environment variable indicates a pod that authenticates with GCP Workload Identity.

2. To verify additional configuration details, examine the pod specification.

   The following example pod specification shows the environment variables and volume fields that the webhook mutates.

   yaml

   apiVersion: v1
   kind: Pod
   metadata:
     name: app-x-pod
     namespace: service-a
   annotations:
     cloud.google.com/skip-containers: "init-first,sidecar"
     cloud.google.com/external-credentials-json: |-
       {
         "type": "external_account",
         "audience": "//iam.googleapis.com/projects/<project_number>/locations/global/workloadIdentityPools/on-prem-kubernetes/providers/<identity_provider>",
         "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
         "token_url": "https://sts.googleapis.com/v1/token",
         "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/app-x@project.iam.gserviceaccount.com:generateAccessToken",
         "credential_source": {
           "file": "/var/run/secrets/sts.googleapis.com/serviceaccount/token",
           "format": {
             "type": "text"
           }
         }
       }
   spec:
     serviceAccountName: app-x
     initContainers:
     - name: init-first
       image: container-image:version
     containers:
     - name: sidecar
       image: container-image:version
     - name: container-name
       image: container-image:version
       env:
       - name: GOOGLE_APPLICATION_CREDENTIALS
         value: /var/run/secrets/gcloud/config/federation.json
       - name: CLOUDSDK_COMPUTE_REGION
         value: asia-northeast1
       volumeMounts:
       - name: gcp-iam-token
         readOnly: true
         mountPath: /var/run/secrets/sts.googleapis.com/serviceaccount
       - mountPath: /var/run/secrets/gcloud/config
         name: external-credential-config
         readOnly: true
     volumes:
     - name: gcp-iam-token
       projected:
         sources:
         - serviceAccountToken:
             audience: sts.googleapis.com
             expirationSeconds: 86400
             path: token
     - downwardAPI:
         defaultMode: 288
         items:
         - fieldRef:
             apiVersion: v1
             fieldPath: metadata.annotations['cloud.google.com/external-credentials-json']
           path: federation.json
       name: external-credential-config

   where:

   annotations.cloud.google.com/external-credentials-json

   Specifies the external credentials configuration generated by the webhook controller. The Kubernetes downwardAPI volume mounts the configuration into the container filesystem.

   spec.containers.env

   Specifies the webhook-injected environment variables for token-based authentication.