Skip to content

Setting up Google Secret Manager as a credential manager

Certificate Manager - SaaS can sign in to your machines with passwords and keys stored in Google Secret Manager. You create credentials that point to your secrets, and then assign those credentials to machines. Your VSatellites retrieve the secrets, so you need at least one VSatellite that can reach Google Cloud.

Each time a credential is used, the latest version of its secret is read. A password you change in Google Secret Manager takes effect the next time it's used, and you don't need to update the credential. The secret value is never stored, logged, or shown.

Looking for the Google Secret Manager machine integration?

To store certificates in your secrets and discover them there, see Create a new Google Secret Manager machine.

Google Secret Manager feature enablement

Only System Administrators can create the Google Secret Manager credential manager connection and credentials.

If you don't see the menu options mentioned in the steps below, contact your Palo Alto Networks representative.

Step 1: Deploy VSatellites in your datacenter

If you don't already have any VSatellites installed, you'll need to get those up and running first. VSatellite is the connector between Certificate Manager - SaaS and Google Secret Manager. You need a VSatellite even if every machine that uses the credentials is a cloud service.

The VSatellites need to reach these Google addresses over HTTPS, either directly or through the VSatellite's HTTP proxy:

  • oauth2.googleapis.com
  • secretmanager.googleapis.com
  • secretmanager.<region>.rep.googleapis.com, for each region that holds regional secrets, for example secretmanager.europe-west3.rep.googleapis.com

Follow our documentation to deploy VSatellites.

Step 2: Create a service account in Google Cloud

Certificate Manager - SaaS signs in to Google Cloud with a service account key. Use a dedicated service account that can only read secrets. For instructions on any of these settings, see the Google Cloud documentation.

  1. In the Google Cloud console, select the project that will own the service account. It can be a different project from the ones that hold your secrets.
  2. Create a service account for Certificate Manager - SaaS, for example cm-saas-secret-reader.
  3. On each project that holds secrets Certificate Manager - SaaS needs, give the service account the Secret Manager Viewer role (roles/secretmanager.viewer). Certificate Manager - SaaS needs it to test the connection and to report a disabled or destroyed secret version.

  4. Give the service account the Secret Manager Secret Accessor role (roles/secretmanager.secretAccessor) on each secret that Certificate Manager - SaaS needs to read, or on the project that holds them. Certificate Manager - SaaS needs it to read secret values.

    Important

    Don't give the service account roles that can change or delete secrets. Grant only the roles listed here.

  5. Make sure the Secret Manager API is turned on in each project that holds secrets.

  6. Create a JSON key for the service account, and download the key file. You'll upload it in the next step.

    Note

    Your organization might block service account key creation (iam.disableServiceAccountKeyCreation). If you can't create a key, ask an Organization Policy Administrator to make an exception for the project that owns the service account.

Keep the service account key current

If the key expires, or someone disables or deletes it, every Google Secret Manager credential that uses the connection stops working. When you replace the key, upload the new one to the Google Secret Manager credential manager connection in Certificate Manager - SaaS right away.

Step 3: Connect Certificate Manager - SaaS to Google Secret Manager as a credential manager

With the service account in place, you're ready to connect Certificate Manager - SaaS to Google Secret Manager.

Before you begin

  • The JSON key file of the service account from Step 2.
  • The IDs of the Google Cloud projects that hold your secrets.
  • The locations of your secrets, which can be global, the region names of any regional secrets, such as europe-west3, or both.

Performed by: System Administrator

  1. Sign in to Certificate Manager - SaaS.

  2. Click Integrations > Credential Managers.

  3. Click New, and then select Google Secret Manager.

  4. Under Secret Retrieval, complete the fields according to the following guidelines:

    • Configuration name: A name for this connection. It must be 3 to 250 characters, with no leading or trailing spaces.
    • Service Account Key (JSON): Paste the contents of the service account key file, or click Upload Key File and select the file. The key must be a service account key. Certificate Manager - SaaS doesn't accept other types of Google credentials, or keys created for endpoints other than Google's standard ones.
    • Project IDs: The IDs of the projects that hold your secrets. Press Enter after each project ID. A project ID is 6 to 30 lowercase letters, digits, or hyphens, and starts with a letter.
    • Locations: global, the region names of your regional secrets, or both. global is added by default. Press Enter after each location.
    • Choose a VSatellite: The VSatellites that can connect to Google Cloud. Choose at least one.

    The number of project IDs multiplied by the number of locations can't be more than 20, because Certificate Manager - SaaS checks each combination when it tests the connection. If you need more, create more than one connection.

    Certificate Manager - SaaS encrypts the service account key when you move out of its field. Test Access is unavailable until the encryption finishes.

  5. Click Test Access. Certificate Manager - SaaS confirms, through each VSatellite you chose, that Google accepts the service account key and that the service account can list secrets in every project and location you entered. The test doesn't read any secret values. Save stays unavailable until the test succeeds and every VSatellite you chose can reach Google Cloud.

    If your access is unsuccessful, check the troubleshooting tips below.

  6. Click Save.

To change a connection later, open it from the list. The Service Account Key (JSON) field appears empty. Leave it blank to keep the current key, or enter a new key to replace it.

Step 4: Create Google Secret Manager credentials in Certificate Manager - SaaS

With the credential manager connection in place, you can create credentials in Certificate Manager - SaaS. Google Secret Manager credentials in Certificate Manager - SaaS are references to secrets stored in Google Secret Manager.

Before you begin

  • Set up a team in Certificate Manager - SaaS that will be allowed to use the credential. The team assigned to the credential should be the same team that will be assigned to the machine in Step 5 below.

  • Find the ID of the secret in Google Secret Manager, and the project and location that hold it.

  • Decide how the secret stores the credential. A secret can hold either of these values:

    • A JSON object with the username and the password as string fields, for example {"username":"admin","password":"..."}.
    • Plain text that holds only the password or key.

Performed by: System Administrator

  1. Click Inventory > Credentials.

  2. Click New > Google Secret Manager Credential. Complete the fields on the Add a New Credential screen according to the following guidelines:

    • Name: A name for the credential. It must be at least 3 characters, with no leading or trailing spaces.
    • Configuration: The Google Secret Manager credential manager connection you set up in Step 3.
    • Owning Teams: The teams that can use this credential.
    • Access Type: Choose what Certificate Manager - SaaS reads from the secret:
      • Username and Password: (Default) Both the username and the password. Use this for any pair of values that a machine signs in with, such as a client ID and client secret.
      • Password Only: Only the password. Use this for a password, API key, or token that a machine uses without a username.
    • Secret ID: The ID of the secret in Google Secret Manager. It can contain only letters, digits, hyphens, and underscores, up to 255 characters. Certificate Manager - SaaS always uses the latest version of the secret.
    • Project ID: (Optional) The project that holds the secret. It must be one of the projects in the connection. Leave it blank to use the first project in the connection.
    • Location: (Optional) The location of the secret. It must be one of the locations in the connection. Leave it blank for global, or enter the region of a regional secret.
    • Username Field: (Optional, Username and Password only) The JSON field of the secret that holds the username. The default is username.
    • Password Field: (Optional) The JSON field of the secret that holds the password. The default is password. Certificate Manager - SaaS ignores it when the secret is plain text.
    • Static Username: (Optional, Username and Password only) The username to use when the secret is plain text and holds only the password. It can be up to 256 characters. Certificate Manager - SaaS ignores it when the secret is JSON.

    The following table shows how Certificate Manager - SaaS reads the username and password from the secret. Certificate Manager - SaaS treats the secret as JSON only if its value is a JSON object. Any other value is plain text.

    Access Type Secret value Username Password
    Username and Password JSON object The value of the Username Field The value of the Password Field
    Username and Password Plain text The Static Username The whole secret value
    Password Only JSON object None The value of the Password Field
    Password Only Plain text None The whole secret value

    Note

    When the secret is plain text, Certificate Manager - SaaS removes one trailing line break from the value, because tools such as gcloud often add one. Certificate Manager - SaaS doesn't change the value in any other way. When the secret is JSON and has no username field, Certificate Manager - SaaS doesn't fall back to the Static Username. The credential fails instead.

    You can't change Access Type after you save the credential.

  3. Click Save. The Credentials page opens with your new credential listed.

  4. You can now test the credential you just created. Click the credential to open its details, and then click Test Access.

    Test Access reads the latest version of the secret and confirms that Certificate Manager - SaaS can get the values the credential needs. Certificate Manager - SaaS discards the value. Because the test reads the secret, Google Cloud audit logs record an access each time you test.

    If Certificate Manager - SaaS was unable to access the credential, see the troubleshooting tips below.

Step 5: Assign the credential to a machine

Performed by: Resource Owner or higher

Now that the credential is in Certificate Manager - SaaS, you can assign it to a machine. Pay attention to the following when creating a new machine that you want to use this credential:

  • The Owning Team on the machine configuration must match one of the Owning Teams on the credential.
  • During machine configuration, set Credential Type to Select Credentials, and then select your Google Secret Manager credential under Credential.
  • The Credential list shows only credentials whose Access Type matches what the machine needs. A machine that signs in with a username and password lists only Username and Password credentials, and a machine that needs only a password or key lists only Password Only credentials.

Certificate Manager - SaaS reads the latest version of the secret each time the machine uses the credential, for example during discovery or provisioning. If the latest version is disabled or destroyed, the operation fails. Certificate Manager - SaaS never falls back to an older version.

Limitations

  • Only service account keys are supported. Certificate Manager - SaaS can't sign in with the VSatellite's own Google identity or with other types of Google credentials. If your organization blocks service account key creation, you need a policy exception.
  • Certificate Manager - SaaS always reads the latest version of a secret. You can't choose or pin a version, and Certificate Manager - SaaS doesn't fall back to an older version.
  • A credential refers to a secret by its ID only. You can't browse secrets or find them by name or label.
  • Only a username and a password are returned. API keys and secrets, and client IDs and secrets, use these two values. SSH keys with a passphrase aren't supported.
  • A connection can have at most 20 project and location combinations.
  • Custom private endpoints aren't supported. The VSatellites must reach Google's standard addresses, directly or through a proxy.

Troubleshooting

Use these tips to troubleshoot common errors. Each error message starts with a short reason, followed by details such as the project, the secret, or the service account. Messages never include the service account key or a secret value.

Google Secret Manager credential manager connection errors

These errors appear when you test access on a Google Secret Manager credential manager connection.

Error Resolution
Unsupported Google credential type The key isn't a service account key. Create a JSON key for a service account, as described in Step 2.
Unsupported service account key The key was created for endpoints other than Google's standard ones. Use a standard Google Cloud service account key.
Invalid service account key The key file is incomplete or was edited. Download a new key.
Service account key rejected by Google The key is invalid, disabled, deleted, or expired, or the service account was deleted. Create a new key and upload it.
Google Secret Manager unreachable Check that the VSatellite can reach the Google addresses listed in Step 1, and check the VSatellite's proxy, firewall, and IP allow lists.
Google Secret Manager did not respond in time Check the VSatellite's network connection, and then test again.
Secret Manager API is disabled Turn on the Secret Manager API in the project that the message names.
Request blocked by a VPC Service Controls perimeter Add an ingress rule to the perimeter for the VSatellite or the service account. The message includes Google's violation ID.
Permission denied Give the service account the Secret Manager Viewer role on the project. The message can include a link to Google's troubleshooter.
Google Secret Manager quota exceeded Test again later. The message names the project that Google charged, or both possible projects if Google doesn't say which one.
Too many project and location combinations Use 20 or fewer combinations of project IDs and locations, or split them across more than one connection.
Google Secret Manager error Google returned an error that Certificate Manager - SaaS doesn't recognize. The message includes Google's status and description. Test again, and if the error persists, contact support.

Google Secret Manager credential errors

These errors appear when you test access on a Google Secret Manager credential. When a machine can't retrieve the credential, the machine shows a general error instead. To see the reason, test access on the credential.

Error Resolution
Invalid credential Check that the project ID and location are among those in the connection, and that the secret ID is valid.
Secret has no username The secret is plain text, and the credential has no static username. Enter a Static Username, or store the secret as a JSON object with username and password fields.
Field missing from secret The JSON secret doesn't have the field that the message names. Check the Username Field and Password Field, or the secret.
Field has unsupported type The JSON field isn't a string. Store the value as a JSON string.
Secret value is not text The secret value isn't valid text. Store the password as text.
Secret value is empty The secret holds no password. Store the password in the secret.
Secret data corrupted in transit The secret value didn't match its checksum. Test again.
Secret not found Check the secret ID, project ID, and location. The secret might also have no versions. Add a version.
Permission denied Give the service account the Secret Manager Secret Accessor role on the secret. Google returns the same error when the secret doesn't exist, so also check the secret ID, project ID, and location.
Latest version of the secret is disabled Turn on the latest version, or add a new version. Certificate Manager - SaaS doesn't use older versions.
Latest version of the secret is destroyed Add a new version of the secret.
Google Secret Manager error Google returned an error that Certificate Manager - SaaS doesn't recognize. The message includes Google's status and description. Test again, and if the error persists, contact support.