Skip to main content
Welcome to Virtru's support portal. As we work to make this page more accessible to screen readers, please contact us at support@virtru.com for technical support.

Reference: Virtru Private Keystore (for Google Workspace CSE) ENV Variables

  • Updated

Summary

This reference document provides a comprehensive list of environment variables and Helm chart configuration values for the Virtru Private Keystore for Google Workspace CSE. It covers both Linux and Kubernetes deployments.

Table of Contents

1.0 Environment Variables

1.1 Values to Fill Out if Using CKS

Refer to the chart at the end of this section for detailed descriptions of each value.

HMAC_TOKEN_ID=00000000000000000000@tokens.virtru.com
HMAC_TOKEN_SECRET=00000000000000000000
CKS_HMAC_TOKEN_ID=v0000000000000000000@token.virtru.com
CKS_HMAC_TOKEN_SECRET=0000000000000000000000
JWKS_AUTHN_ISSUERS=000000000000000000000
JWKS_AUTHZ_ISSUERS=0000000000000000000000000
JWT_AUD=000000000000000000000
JWT_KACLS_URL=https://csesrv.customer.com
TAKEOUT_CLAIM=cse_takeout
ACM_URL=https://api.virtru.com/acm/api
ACCOUNTS_URL=https://api.virtru.com/accounts/api
CKS_URL=https://cks.customer.com
PORT=9000
USE_SSL=true
USE_CKS=true

#Values to set below if using Drive Labels integration
#DRIVE_LABELS=true
#SERVICE_ACCOUNT_EMAIL=<admin-email@customerdomain.com>
#DRIVE_TIME=15
#DRIVE_LABELS_TIME=15
#ADMIN_TIME=15
#GOOGLE_APPLICATION_CREDENTIALS=/app/cse/credentials.json

1.2 Values to Fill Out if Not Using CKS

HMAC_TOKEN_ID=00000000000000000000@tokens.virtru.com
HMAC_TOKEN_SECRET=00000000000000000000
#CKS_HMAC_TOKEN_ID=
#CKS_HMAC_TOKEN_SECRET=
JWKS_AUTHN_ISSUERS=000000000000000000000
JWKS_AUTHZ_ISSUERS=0000000000000000000000000
JWT_AUD=000000000000000000000
JWT_KACLS_URL=https://csesrv.customer.com
TAKEOUT_CLAIM=cse_takeout
ACM_URL=https://api.virtru.com/acm/api
ACCOUNTS_URL=https://api.virtru.com/accounts/api
#CKS_URL=
PORT=9000
USE_SSL=true
USE_CKS=false
SECRET_KEY=0000000000000000
SECRET_KEYS_PATH=/app/cse/secrets.json

#Values to set below if using Drive Labels integration
#DRIVE_LABELS=true
#SERVICE_ACCOUNT_EMAIL=<admin-email@customerdomain.com>
#DRIVE_TIME=15
#DRIVE_LABELS_TIME=15
#ADMIN_TIME=15
#GOOGLE_APPLICATION_CREDENTIALS=/app/cse/credentials.json

1.3 Environment Variables Reference

Environment Variable Description Example
HMAC_TOKEN_ID The HMAC token credentials used to access Virtru SaaS (Provided by Virtru) 0000000000000000000000000@tokens.virtru.com
HMAC_TOKEN_SECRET The HMAC token secret (Provided by Virtru) 0000000000000000000000000
CKS_HMAC_TOKEN_ID The HMAC token credentials used to access the CKS. These values can be found in the customer's CKS server in the send_to_virtru.tar.gz file within the /var/virtru/cks directory. (Only if using CKS option) 0000000000000000000000000@tokens.virtru.com
CKS_HMAC_TOKEN_SECRET The CKS HMAC token secret (Only if using CKS option) 0000000000000000000000000
JWKS_AUTHN_ISSUERS A base64-encoded map of accepted Authentication issuer IDs (from the authentication JWT) to the URL where the issuer publishes its JSON Web Keyset. This is dictated by the customer via their IDP.

Example for Google IDP:
echo '{ "https://accounts.google.com": "https://www.googleapis.com/oauth2/v3/certs" }' | base64

Note: These values will differ if using a third-party IdP. Please refer to your IdP's specific configurations.

Example for Okta IDP:
echo '{ "<issuer>": "<jwks_uri>" }' | base64
Refer to the customer's Okta .well-known file to confirm the issuer and jwks_uri variables:
https://<example>.okta.com/.well-known/openid-configuration 		Base64-encoded value
JWKS_AUTHZ_ISSUERS A base64-encoded map of accepted Authorization issuer IDs (from the authorization JWT) to the URL where the issuer publishes its JSON Web Keyset. This is dictated by Google (referenced here).

Command to generate:
echo '{ "gsuitecse-tokenissuer-drive@system.gserviceaccount.com": "https://www.googleapis.com/service_accounts/v1/jwk/gsuitecse-tokenissuer-drive@system.gserviceaccount.com","gsuitecse-tokenissuer-meet@system.gserviceaccount.com": "https://www.googleapis.com/service_accounts/v1/jwk/gsuitecse-tokenissuer-meet@system.gserviceaccount.com","gsuitecse-tokenissuer-calendar@system.gserviceaccount.com": "https://www.googleapis.com/service_accounts/v1/jwk/gsuitecse-tokenissuer-calendar@system.gserviceaccount.com","gsuitecse-tokenissuer-gmail@system.gserviceaccount.com": "https://www.googleapis.com/service_accounts/v1/jwk/gsuitecse-tokenissuer-gmail@system.gserviceaccount.com","apps-security-cse-kaclscommunication@system.gserviceaccount.com": "https://www.googleapis.com/service_accounts/v1/jwk/apps-security-cse-kaclscommunication@system.gserviceaccount.com"}' | base64 		Base64-encoded value
JWT_AUD Base64-encoded JSON map of JWT audiences for authorization and authentication. These ensure that JWTs written by authn or authz issuers for other services are not accepted. The authz audience (sent by Google) will always be cse-authorization, but the authn audience will be configured through the customer's IDP. For Google OAuth, the authn audience is the OAuth client ID string.

Example for Google IDP:
echo '{ "authn": "000000000000000000000000000000000.apps.googleusercontent.com", "authz":"cse-authorization" }' | base64

Example for Okta IDP:
echo '{ "authn": "<Okta-client-ID>", "authz":"cse-authorization" }' | base64 		Base64-encoded value
JWT_KACLS_URL The URL where the CSE service is hosted. This field allows detection of potential man-in-the-middle servers configured by insiders or rogue domain admins. https://cse.the-customer-domain.com
TAKEOUT_CLAIM The JWT claim used to signify if a user has permission to submit a takeout unwrap claim. This will be configured on the authentication token from the customer's identity provider. cse_takeout
ACM_URL The Virtru ACM URL https://api.virtru.com/acm/api
ACCOUNTS_URL The Virtru Accounts URL https://api.virtru.com/accounts/api
CKS_URL The CKS URL. Should be wherever the customer's CKS is accessible from. https://cks.the-customer-domain.com
USE_CKS Flag to enable or disable connection to the Virtru CKS for key management. Set to true if using a Virtru CKS, or false to use a local secret key instead. true or false (default is false)
PORT The port to run the CSE server on 9000
USE_SSL Whether the application should use SSL. Set to false to run over HTTP and true to use HTTPS. true
SECRET_KEY If NOT using CKS (only available on v3.0.0 and later).
DO NOT LOSE THIS KEY

Generate a secret key and store it locally on your server:
echo "my-key-name:$(openssl rand 32 | base64)" 2&1 | tee cseSecret.txt 		my-key-name:00000000000000000000000000000000
SECRET_KEYS_PATH If NOT using CKS (only available on v3.0.0 and later).
Path to secrets.json file where secret key(s) are held in the CSE container.

Required key format in secrets.json file:
{"active":"secret-key","secrets":[{"name":"secret-key","value":"00000000000000000000000000000000"}]} 		/app/cse/secrets.json
HTTPS_PROXY / HTTP_PROXY If using an internal web proxy, enter proxy IP or FQDN and listening port for these values to have the container connect via proxy. https://myproxy-server.com:443
http://myproxy-server.com:80
DRIVE_LABELS Flag used to set if Drive Labels feature is being used true (default is false)
GOOGLE_APPLICATION_CREDENTIALS If DRIVE_LABELS flag is set to true, this points to the credentials file ./credentials.json (defaults to unset)
SERVICE_ACCOUNT_EMAIL If DRIVE_LABELS flag is set to true, this is set to the email of the owner used by the service account unset
DRIVE_TIME Time taken for Drive Cache to refresh (in seconds) 15 (default)
ADMIN_TIME Time taken for Admin Cache to refresh (in seconds) 15 (default)
DRIVE_LABELS_TIME Time taken for Drive Labels Cache to refresh (in seconds) 15 (default)
LOG_LEVEL Sets the logging verbosity level for the CSE application. Useful for debugging and troubleshooting. debug, info, warn, error (default is info)
CONTROL_CENTER_INFO Enables additional logging information for Virtru Control Center integration. true (default is false)

 

2.0 Kubernetes Helm Chart Values

This section covers configuration values specific to Kubernetes deployments using the Virtru CSE Helm chart. For installation instructions, see Virtru Private Keystore for Google Workspace CSE: Install - Kubernetes.

2.1 Image Configuration

Value Description Default
image.repository Container image repository containers.virtru.com/cse
image.pullPolicy Image pull policy IfNotPresent
image.tag Image tag. Defaults to Chart's appVersion if left blank ""

2.2 Deployment Settings

Value Description Default
replicaCount Number of pod replicas to deploy 1
nameOverride Override for resource names ""
fullnameOverride Full override for resource names ""
deployment.port Port exposed by the deployment 9000

2.3 Service Account

Value Description Default
serviceAccount.create Create a Kubernetes service account true
serviceAccount.annotations Annotations for the service account {}
serviceAccount.name Service account name (auto-generated if blank) ""

2.4 Pod Configuration

Value Description Default
podAnnotations Custom annotations for pods {}
podSecurityContext Security settings for the entire pod (e.g., fsGroup) {}
securityContext Security settings for containers (e.g., runAsNonRoot, readOnlyRootFilesystem) {}
testerPod.enabled Deploy a test pod false
testerPod.annotations Annotations for the test pod (includes Helm test hook) helm.sh/hook: test

Pod Security Context Example

podSecurityContext:
  fsGroup: 2000

securityContext:
  capabilities:
    drop:
    - ALL
  readOnlyRootFilesystem: true
  runAsNonRoot: true
  runAsUser: 1000

Recommendation

We encourage you to follow your organization's security policies for compliance and security when configuring these settings.

2.5 Service Configuration

Value Description Default
service.type Kubernetes service type LoadBalancer
service.port Service port 443
service.protocol Service protocol TCP
service.annotations Annotations for the service {}
service.loadBalancerIP Static IP address for LoadBalancer (optional) Not set

Service Example with Static IP

service:
  type: LoadBalancer
  annotations: {}
  loadBalancerIP: <your-static-ip-address>
  port: 443
  protocol: TCP

2.6 Ingress Configuration

Ingress is disabled by default. When disabled, a LoadBalancer service is created instead.

Value Description Default
ingress.enabled Enable ingress false
ingress.annotations Ingress annotations {}
ingress.hosts List of ingress hosts and paths See example below
ingress.tls TLS configuration for ingress []

Ingress Example

ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
    kubernetes.io/tls-acme: "true"
  hosts:
    - host: fqdn.yourdomain.com
      paths:
      - path: /*
        pathType: ImplementationSpecific
        backend:
          serviceName: cse
          servicePort: 9000
  tls:
    - secretName: cse-example-tls
      hosts:
        - fqdn.yourdomain.com

Note

Alternatively, appSecrets.ssl.privateKey and appSecrets.ssl.certificate can be used for TLS certificate configuration instead of an ingress TLS secret.

2.7 Probes Configuration

Readiness Probe

Readiness probes check if the pod is ready to receive traffic.

Value Description Default
probes.readiness.initialDelaySeconds Delay before first probe 30
probes.readiness.periodSeconds Probe interval 10
probes.readiness.timeoutSeconds Probe timeout 10
probes.readiness.failureThreshold Failures before marking unready 2
probes.readiness.successThreshold Successes before marking ready 1

Liveness Probe

Liveness probes restart the pod if it becomes unresponsive.

Value Description Default
probes.liveness.initialDelaySeconds Delay before first probe 40
probes.liveness.periodSeconds Probe interval 10
probes.liveness.timeoutSeconds Probe timeout 10
probes.liveness.failureThreshold Failures before restart 2
probes.liveness.successThreshold Successes before marking healthy 1

2.8 Resource Limits

Value Description Default
resources CPU and memory resource limits/requests {}

Resources Example

resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 100m
    memory: 128Mi

Note

We recommend not specifying default resources to increase flexibility across different environments. Adjust these values based on your expected workload and monitor resource usage after deployment.

2.9 Autoscaling

Horizontal Pod Autoscaling is disabled by default.

Value Description Default
autoscaling.enabled Enable horizontal pod autoscaling false
autoscaling.minReplicas Minimum number of replicas 1
autoscaling.maxReplicas Maximum number of replicas 100
autoscaling.targetCPUUtilizationPercentage CPU threshold for scaling 80
autoscaling.targetMemoryUtilizationPercentage Memory threshold for scaling (optional) Not set

Recommendation

We recommend adhering to your organization's policies for autoscaling configuration.

2.10 Scheduling Configuration

Value Description Default
nodeSelector Node labels for pod scheduling {}
tolerations Tolerations for tainted nodes []
affinity Node affinity rules {}

Scheduling Example

nodeSelector:
  kubernetes.io/os: linux

tolerations:
  - key: "dedicated"
    operator: "Equal"
    value: "cse"
    effect: "NoSchedule"

affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
      - matchExpressions:
        - key: topology.kubernetes.io/zone
          operator: In
          values:
          - us-east-1a
          - us-east-1b

2.11 External Secrets Integration

For organizations using external secret management solutions, you can integrate with the External Secrets Operator.

External Secrets Example

externalAppSecrets:
  - name: <external-secret-object-name>
    secretsPath: <path-of-secret-in-secret-store>
    secretStoreRef:
      kind: <SecretStore or ClusterSecretStore>
      name: <name-of-secret-store>
    refreshInterval: <reconciliation-interval>

Version Requirement

Beginning in CSE Helm chart v1.1.0, the ExternalSecret resource uses external-secrets.io/v1 APIs, which were fully promoted in v0.16.0 of the external-secrets operator. Ensure your in-cluster external-secrets operator is upgraded to v0.16.0+ before using this feature.

2.12 Volumes Configuration

Use volumes to mount secrets or configuration files. This is commonly used with Drive Labels integration.

Value Description Default
volumes List of volumes for mounting secrets or configurations []

Volumes Example for Drive Labels

volumes:
  - name: credentials-volume
    volume:
      secret:
        secretName: keyfile-secret
        items:
        - key: keyfile.json
          path: credentials.json
    volumeMount:
      mountPath: /app/cse/credentials.json
      subPath: credentials.json

Reference

For complete Drive Labels setup instructions, see Kubernetes: Google CSE Labels Integration.

2.13 Application Configuration

The appConfig section in the Helm chart maps to the environment variables used by the CSE application. These values configure how the CSE service connects to Virtru services and identity providers.

Value Description Default
appConfig.accountsUrl Virtru Accounts API URL https://api.virtru.com/accounts/api
appConfig.acmUrl Virtru ACM API URL https://api.virtru.com/acm/api
appConfig.jwksAuthnIssuers Base64-encoded map of accepted Authentication issuer IDs to their JWKS URLs. This corresponds to the JWKS_AUTHN_ISSUERS environment variable. See Section 1.3 for encoding instructions. User provided
appConfig.jwksAuthzIssuers Base64-encoded map of accepted Authorization issuer IDs to their JWKS URLs. This corresponds to the JWKS_AUTHZ_ISSUERS environment variable. The default value contains the required Google service accounts. Pre-filled with Google defaults
appConfig.jwtAud Base64-encoded JSON map of JWT audiences for authorization and authentication. This corresponds to the JWT_AUD environment variable. User provided
appConfig.jwtKaclsUrl The FQDN URL for your CSE service. This corresponds to the JWT_KACLS_URL environment variable. https://fqdn.yourdomain.com
appConfig.processNumberOverride Override for the number of worker processes 5
appConfig.useSsl Enable SSL for the CSE service. This corresponds to the USE_SSL environment variable. true
appConfig.useCks Enable connection to the Virtru CKS for key management. This corresponds to the USE_CKS environment variable. Set to true if integrating with a Virtru CKS. false
appConfig.cksUrl URL for the Virtru CKS if useCks is set to true. This corresponds to the CKS_URL environment variable. https://cks.yourdomain.com

Drive Labels Configuration

The following values configure the Google Drive Labels integration. For complete setup instructions, see Kubernetes: Google CSE Labels Integration.

Value Description Default
appConfig.driveLabels.enabled Enable or disable Drive Labels integration. This corresponds to the DRIVE_LABELS environment variable. false
appConfig.driveLabels.serviceAccountEmail The email of the admin user for the service account. This corresponds to the SERVICE_ACCOUNT_EMAIL environment variable. User provided
appConfig.driveLabels.driveTime Time interval for Drive cache refresh (in seconds). This corresponds to the DRIVE_TIME environment variable. 15
appConfig.driveLabels.driveLabelsTime Time interval for Drive Labels cache refresh (in seconds). This corresponds to the DRIVE_LABELS_TIME environment variable. 15
appConfig.driveLabels.adminTime Time interval for Admin cache refresh (in seconds). This corresponds to the ADMIN_TIME environment variable. 15

appConfig Example

appConfig:
  accountsUrl: "https://api.virtru.com/accounts/api"
  acmUrl: "https://api.virtru.com/acm/api"
  jwksAuthnIssuers: "eyAiaHR0cHM6Ly9hY2NvdW50cy5nb29nbGUuY29tIjogImh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92My9jZXJ0cyIgfQo="
  jwksAuthzIssuers: "eyAiZ3N1aXRlY3NlLXRva2VuaXNzdWVyLWRyaXZlQHN5c3RlbS5nc2VydmljZWFjY291bnQuY29tIjogImh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL3NlcnZpY2VfYWNjb3VudHMvdjEvandrL2dzdWl0ZWNzZS10b2tlbmlzc3Vlci1kcml2ZUBzeXN0ZW0uZ3NlcnZpY2VhY2NvdW50LmNvbSIsLi4ufQo="
  jwtAud: "eyAiYXV0aG4iOiAiMDAwMDAwMDAwMDAwMDAwMDAwLmFwcHMuZ29vZ2xldXNlcmNvbnRlbnQuY29tIiwgImF1dGh6IjoiY3NlLWF1dGhvcml6YXRpb24iIH0K"
  jwtKaclsUrl: "https://cse.yourdomain.com"
  processNumberOverride: "5"
  useSsl: "true"
  useCks: "false"
  cksUrl: "https://cks.yourdomain.com"
  driveLabels:
    enabled: "false"
    serviceAccountEmail: "admin@yourdomain.com"
    driveTime: "15"
    driveLabelsTime: "15"
    adminTime: "15"

2.14 Application Secrets

The appSecrets section contains sensitive configuration values for the CSE service. These include authentication credentials, encryption keys, and SSL certificates.

Security Note

Creating secrets directly in values.yaml is provided as a default option for simplicity. For production environments, we strongly recommend using a third-party secret management solution such as HashiCorp Vault, AWS Secrets Manager, or the External Secrets Operator (see Section 2.11). Always follow your organization's security policies for compliance.

HMAC Credentials

Value Description Default
appSecrets.hmac.tokenId HMAC token ID for Virtru SaaS authentication. This value is provided by Virtru and corresponds to the HMAC_TOKEN_ID environment variable. Provided by Virtru
appSecrets.hmac.tokenSecret HMAC token secret for Virtru SaaS authentication. This value is provided by Virtru and corresponds to the HMAC_TOKEN_SECRET environment variable. Provided by Virtru

Secret Key (Non-CKS Deployments)

Value Description Default
appSecrets.secretKey Required if NOT using Virtru CKS.

A named, base64-encoded encryption key for CSE. The format is keyname:base64encodedkey. This corresponds to the SECRET_KEY environment variable.

DO NOT LOSE THIS KEY - it is required to decrypt data encrypted by the CSE service.

Generate a key:
echo "my-key-name:$(openssl rand 32 | base64)" 2>&1 | tee cseSecret.txt 		User generated

Note

Comment out or remove appSecrets.secretKey if you are using the Virtru CKS for key management (appConfig.useCks: "true").

SSL Certificates

Value Description Default
appSecrets.ssl.privateKey Base64-encoded SSL private key for the CSE service.

Encode your key:
cat server.key | base64 -w 0 		User provided
appSecrets.ssl.certificate Base64-encoded SSL certificate (full chain) for the CSE service.

Encode your certificate:
cat server.cert | base64 -w 0 		User provided

CKS Credentials (Optional)

These values are only required if integrating with a Virtru CKS (appConfig.useCks: "true").

Value Description Default
appSecrets.cksHmac.tokenId CKS HMAC token ID. Found in the send_to_virtru.tar.gz file within the /var/virtru/cks directory on your CKS server. This corresponds to the CKS_HMAC_TOKEN_ID environment variable. From your CKS
appSecrets.cksHmac.tokenSecret CKS HMAC token secret. Found in the same location as the token ID. This corresponds to the CKS_HMAC_TOKEN_SECRET environment variable. From your CKS

Drive Labels Credentials (Optional)

This value is only required if using the Google Drive Labels integration (appConfig.driveLabels.enabled: "true").

Value Description Default
appSecrets.googleApplicationCredentials Path to the Google service account credentials JSON file inside the container. This corresponds to the GOOGLE_APPLICATION_CREDENTIALS environment variable. Used in conjunction with the volumes configuration to mount the credentials file. /app/cse/credentials.json

appSecrets Example

# Example: Without CKS (using local secret key)
appSecrets:
  hmac:
    tokenId: "your-token-id@tokens.virtru.com"
    tokenSecret: "your-token-secret"
  secretKey: "my-key-name:BASE64ENCODEDKEYVALUE=="
  ssl:
    privateKey: BASE64ENCODEDPRIVATEKEY==
    certificate: BASE64ENCODEDCERTIFICATE==
  # cksHmac: (commented out when not using CKS)
  #   tokenId: "from-your-cks"
  #   tokenSecret: "from-your-cks"
  googleApplicationCredentials: /app/cse/credentials.json
# Example: With CKS
appSecrets:
  hmac:
    tokenId: "your-token-id@tokens.virtru.com"
    tokenSecret: "your-token-secret"
  # secretKey: (commented out when using CKS)
  ssl:
    privateKey: BASE64ENCODEDPRIVATEKEY==
    certificate: BASE64ENCODEDCERTIFICATE==
  cksHmac:
    tokenId: "cks-token-id@tokens.virtru.com"
    tokenSecret: "cks-token-secret"
  googleApplicationCredentials: /app/cse/credentials.json

3.0 Additional Resources

Resource Description
Virtru Private Keystore for Google Workspace CSE: Install - Kubernetes Step-by-step Kubernetes installation guide
Virtru Private Keystore for Google Workspace CSE: Install - Linux Step-by-step Linux installation guide
Kubernetes: Google CSE Labels Integration Drive Labels integration setup guide
Reference: Drive Label Variables Complete reference for Drive Label configuration options
Reference: How Google CSE Labels Work Overview of Google CSE Labels functionality

Related articles