Skip to content

Create a new Google Secret Manager machine

Creating a new machine is the initial step in enabling Certificate Manager - SaaS to connect directly to application keystores for certificate management. Once you have created machines, you can move on to provisioning certificates to those machines.

A Google Secret Manager machine connects to Google Cloud with a service account key. Certificate Manager - SaaS stores each provisioned certificate, its private key, and its chain as a secret in Google Secret Manager, and can also discover certificates that are already stored there. One machine can reach every project the service account has access to. You choose the project, location, and secret for each installation.

Looking for Google Secret Manager as a credential manager?

To use passwords and keys stored in your secrets to sign in to your machines, see Setting up Google Secret Manager as a credential manager.

Before you begin

  • A Google Cloud service account, and a JSON key for it.

    Note

    Your organization might block service account key creation (iam.disableServiceAccountKeyCreation). If it does, you need an organization policy exception on the project that holds the service account.

  • The Secret Manager API (secretmanager.googleapis.com) enabled on each project where you want to discover or provision certificates.

  • A custom IAM role granted to the service account on each of those projects, with the permissions for the operations you use:

    Operation Permissions
    Test Access secretmanager.locations.list
    Discovery secretmanager.secrets.list
    secretmanager.versions.access
    Provisioning secretmanager.locations.list
    secretmanager.secrets.get
    secretmanager.secrets.create
    secretmanager.secrets.update
    secretmanager.versions.access
    secretmanager.versions.add
    secretmanager.versions.get
    secretmanager.versions.list
    secretmanager.versions.disable

    Important

    Grant a custom role with only these permissions, and grant it only on the projects you want Certificate Manager - SaaS to manage. Avoid roles/secretmanager.admin, and avoid granting the role on a folder or organization, because a grant there lets every installation and discovery on this machine reach any project below it.

    Provisioned private keys are protected by the project's IAM policy, not by Certificate Manager - SaaS. Anyone with secretmanager.versions.access on the project or the secret can read them, so review who holds that permission.

    Discovery reads the latest version of each secret that matches its filters, but secretmanager.versions.access isn't limited to those secrets. The service account can read the value of any secret in the project. Keep certificates in projects that don't hold unrelated secrets, or add an IAM condition on the secret name, for example resource.name.startsWith("projects/<number>/secrets/tls-"). IAM conditions can't use secret labels.

Note

Certificate Manager - SaaS connects to Google Cloud directly, so a Google Secret Manager machine doesn't need a VSatellite.

  1. In Service Account Key (JSON), paste the entire contents of the service account's JSON key file.

    Only service account keys are accepted, and only keys that use Google Cloud's own token endpoint (oauth2.googleapis.com). Other Google Cloud credential types, such as user credentials and workload identity federation, aren't supported.

    Warning

    Remember to store your username and password securely when creating a new machine. For security reasons, you will not be able to modify the fields under the "Access" tab without these credentials. This ensures that only authorized individuals can modify these fields.

  2. (Optional) In Default Project ID, enter the ID of the project that Test Access checks. Discovery also scans this project when you don't list any projects. If you leave it empty, Certificate Manager - SaaS uses the project that the service account key belongs to.

  3. (Optional) In Allowed Project IDs, enter a comma-separated list of the only projects that Test Access, installations, and discovery on this machine can use. Certificate Manager - SaaS rejects a request for any other project before it contacts Google Cloud. Leave the field empty to allow every project the service account can access.

    If you set this field, include the Default Project ID project in the list. If Default Project ID is empty, include the project that the service account key belongs to. Otherwise, Test Access fails.

    Note

    Allowed Project IDs guards against misconfigured installations, but it doesn't replace IAM. Anyone who can edit the machine can change the list, so the IAM grants on the service account remain the real limit.

  4. Leave Use Self-Signed JWT on, which is the default. With this setting on, Certificate Manager - SaaS signs its own authentication token and doesn't call a token endpoint. Turn it off only if Google Cloud rejects self-signed tokens for this service account. Certificate Manager - SaaS then exchanges the key for an OAuth 2.0 access token instead.

  5. Click Test Access, then click Continue. Note that Continue is only enabled if the Test Access is successful.

    Note

    Test Access lists the Secret Manager locations of the Default Project ID project. This confirms that the key is valid, that the Secret Manager API is enabled, and that the service account has the secretmanager.locations.list permission there. It doesn't check the permissions that discovery and provisioning need, or access to any other project. Problems with those first appear when you discover or provision certificates.

    Test Access failed. What does the message mean?
    Message begins with What to do
    ServiceAccountKey must be a valid json string The value isn't JSON. Paste the whole, unmodified JSON key file that you downloaded from Google Cloud.
    invalid service account key The value isn't a complete service account key. Paste the whole, unmodified JSON key file that you downloaded from Google Cloud.
    Google rejected the service account key The key or the service account was deleted or disabled. Create a new key for an enabled service account, and update the machine.
    no project to test against Enter a Default Project ID.
    project <ID> does not exist, or the service account has no access to it Check the project ID, and check the service account's role bindings on that project.
    the Secret Manager API is not enabled on project Enable secretmanager.googleapis.com on the project.
    the service account lacks permission Add the permission named in the message to the service account's role.
    the call to project <ID> was blocked by a VPC Service Controls perimeter The project is inside a VPC Service Controls perimeter. Add an ingress rule for the service account, or manage projects outside the perimeter.
    could not reach Google Cloud from the connector A network, proxy, or firewall problem between Certificate Manager - SaaS and *.googleapis.com. Try again, and if the problem persists, contact support.
    project <ID> is not in the Allowed Project IDs of this connection Add the project to Allowed Project IDs, or clear the field.

    If Test Access fails only when Use Self-Signed JWT is on, turn it off and try again.

    Tip

    When you edit an existing Google Secret Manager machine, click Test Access before you save. If the connection fails when you save, Certificate Manager - SaaS shows only a generic error, while Test Access shows the message from the table above.

Discovery options for Google Secret Manager

When you configure discovery for this machine, the following options control which secrets Certificate Manager - SaaS examines. See Create a new machine for the rest of the discovery settings.

  1. In the Project IDs field, enter a comma-separated list of the projects to scan. If you leave it empty, discovery scans the Default Project ID project.

  2. In the Locations field, enter a comma-separated list of the locations to scan, which can include global, one or more regions such as europe-west1, or both. The default is global, so regional secrets are found only if you add their regions. Discovery scans every location in every listed project.

  3. In the Label Filter field, enter the one label, as key=value, that discovered secrets must carry. The default is venafi-managed=true, which is the label Certificate Manager - SaaS applies to every secret it creates. To discover secrets that Certificate Manager - SaaS didn't create, enter a label those secrets carry, or add the venafi-managed=true label to them in Google Cloud.

  4. (Optional) In the Name Filter field, enter text that a secret's name must contain. The text can use letters, digits, underscores, and hyphens.

  5. Enable Exclude Expired Certificates to omit certificates that have already expired from the discovery results.

Note

  • Discovery reads only the latest version of each secret. Older versions aren't inventoried, and a secret whose latest version is disabled or destroyed is skipped.
  • Discovery automatically detects whether a secret is stored as JSON, Kubernetes TLS, PEM, PKCS#12, or Java KeyStore (JKS). It imports the certificate and its chain, and discards any private key it reads.
  • Discovery has no keystore password. It finds a PKCS#12 secret only if the secret's password is empty. It reads a JKS secret without checking the keystore's integrity.
  • Discovery skips secrets it can't read or that hold no certificate. It also skips any project or location where the service account can't list secrets.
  • Discovery fails if a listed project isn't in the machine's Allowed Project IDs, or if a location isn't a valid region.

What's next?

Refer back to Create a new machine to finish setting up your new machine by configuring Discovery and Provisioning scheduling.

For existing machines: