Choosing service account authentication methods in Apigee hybrid

Apigee hybrid requires service accounts for secure communication with Google Cloud services. Choose an authentication method for these service accounts that aligns with your security and operational requirements. This guide provides a brief overview of the available options.

Understand service account authentication

Apigee hybrid uses Google Cloud service accounts to authenticate and authorize components running in your Kubernetes cluster. These service accounts access Google Cloud resources, such as Cloud Storage buckets and Cloud Logging. Each service account requires specific Identity and Access Management (IAM)roles to perform its functions.

• Learn more about Google Cloud Identity and Access Management service accounts:Service accounts overview.
• Learn more about service accounts in Apigee hybrid:About service accounts.

Authentication Method Options

Apigee hybrid supports several methods for authenticating service accounts. Each method managesservice account keys differently, offering various levels of security and operational complexity.Consider your platform, security posture, and existing infrastructure when selecting a method.

The following table summarizes the available authentication methods:

Store service account keys in Kubernetes secrets

Store service account keys as Kubernetes secrets within your cluster. This method leverages the built-in secret management capabilities in Kubernetes. Kubernetes secrets can provide a more secure way to manage keys than direct file storage. You still manage key rotation manually.

Hybrid components reference these secrets using theserviceAccountRefandenvs[].serviceAccountRefs properties in theoverrides.yaml file.Kubernetes manages the distribution of these secrets to the appropriate pods.

For example:

logger:serviceAccountRef:"my-project-apigee-logger-key"

To use this method, seeStore service account keys in Kubernetes secrets.

Service account JSON key files

This method involves creating a JSON key file for each service account and storing these filesdirectly on a file system. This approach offers simplicity for initial setup. However, it requiresensuring the security of the file system. Key rotation is manual.

Place each service account's private key JSON file in a directory accessible by theApigee hybrid components. Reference the path to these files in youroverrides.yaml configuration using theserviceAccountPath andenvs[].serviceAccountPaths properties.

For example:

logger:serviceAccountPath:"my-project-apigee-logger.json"

You can generate and download the service account key files using thecreate-service-account tool provided with Apigee hybrid. For more information, seecreate-service-account.

Store service account keys in Vault

Integrate HashiCorp Vault to manage your service account keys. Vault providesa robust solution for secret management, offering features like dynamic secretgeneration, auditing, and automated key rotation. It requires setting up andmaintaining a Vault instance.

You will need to create separate Vault secrets, policies, and roles for the org-level and env-levelcomponents. You reference these secrets in youroverrides.yamlconfiguration using theserviceAccountSecretProviderClass andenvs[].serviceAccountSecretProviderClass properties.

For example:

serviceAccountSecretProviderClass:apigee-orgsakeys-spcenvs:-name:my-envserviceAccountSecretProviderClass:apigee-envsakeys-my-env-spc

SeeStore service account keys in Vault.

Workload Identity Federation for GKE

Workload Identity Federation for GKE allows Kubernetes service accounts to act as Google Cloudservice accounts. This method eliminates the need for service account key filesentirely. Instead, your GKE cluster directly authenticates workloads usingGoogle Cloud IAM. Workload Identity Federation for GKE provides a highly secure and automatedauthentication mechanism, simplifying key management. This method is specific to GKE clusters.

This method requires binding each Kubernetes service account to a specific Google Cloud service account. The Apigee hybrid installation process creates the Kubernetes service accounts specific to your installation when you install the Apigee hybrid Helm charts. When you run thehelm install orhelm upgrade command with the--dry-run flag for each chart, the output will include the commands to bind the Kubernetes service accounts to the Google Cloud service accounts for the specific Apigee hybrid component in that chart.

You enable Workload Identity Federation for GKE in your overrides.yaml file with thegcp.workloadIdentity.enabled property.

For example:

gcp:projectID:my-projectregion:us-west1workloadIdentity:enabled:true

SeeEnable Workload Identity Federation for GKE.

Workload Identity Federation on platforms other than GKE

Workload Identity Federation extends the benefits of Workload Identity Federation for GKE toKubernetes clusters running outside of Google Cloud, such as Azure KubernetesService (AKS), Amazon Elastic Kubernetes Service (EKS), or OpenShift. Thismethod allows your non-GKE cluster to authenticate to Google Cloud usingyour cluster's OIDC provider to configurea trust relationship between your cluster's identity provider and Google Cloud.After initial setup, this method eliminates the need for service account key files.

You can use Workload Identity Federation with:

• Credential configuration files (in place of service account key files)
• Kubernetes secrets
• Vault

To use Workload Identity Federation you create credential configuration files for each Google Cloud service account. You use these files in place of service account key files or to set up the Kubernetes secrets or Vault if you are using those methods.

You enable Workload Identity Federation in your overrides.yaml file with thegcp.federatedWorkloadIdentity.enabled,gcp.federatedWorkloadIdentity.audience, andgcp.federatedWorkloadIdentity.credentialSourceFile properties.

For example:

gcp:projectID:my-projectregion:us-west1federatedWorkloadIdentity:enabled:trueaudience:"//iam.googleapis.com/projects/123123123123/locations/global/workloadIdentityPools/my-wi-pool/providers/my-wi-provider"credentialSourceFile:"/var/run/service-account/token"

SeeEnable Workload Identity Federation.

Choose an Authentication Method

Select an authentication method based on your deployment environment andsecurity requirements.

• For GKE deployments, Workload Identity Federation for GKE offers a secure and streamlined approach. It removes the need to manage service account key files directly.
• For non-GKE Kubernetes deployments (AKS, EKS, OpenShift), Workload Identity Federation provides a similar keyless authentication experience. This method is the recommended choice for these environments.
• If Workload Identity Federation for GKE or Workload Identity Federation are not options, consider using Vault for centralized key management and automation.
• For simpler deployments or if you lack a Vault setup, storing keys in Kubernetes secrets provides a native Kubernetes solution. This method offers better security than direct file storage.
• Direct service account key files are suitable for initial testing or environments where other methods are not feasible. However, this method requires careful manual key management and rotation.

What's next

• Continue planning and preparing:Secure ports usage.
• Learn more about service accounts in Apigee hybrid:About service accounts.
• Install Apigee hybrid:Part 1, Project and org setup: Overview.