Create a Google Secret Manager machine¶
Create a Google Secret Manager machine so Certificate Manager - SaaS can discover the certificates stored in your secrets and provision certificates to them as secrets. The machine connects to Google Cloud with a service account key and can reach every project the service account has access to, and you choose the project, location, and secret for each installation.
Note
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¶
- The System Administrator, PKI Administrator, or Resource Owner role. If you have the Resource Owner role, you must own or belong to at least one team.
-
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 Identity and Access Management (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.listDiscovery secretmanager.secrets.listsecretmanager.versions.accessProvisioning secretmanager.locations.listsecretmanager.secrets.getsecretmanager.secrets.createsecretmanager.secrets.updatesecretmanager.versions.accesssecretmanager.versions.addsecretmanager.versions.getsecretmanager.versions.listsecretmanager.versions.disableImportant
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.accesson 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.accessisn'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 exampleresource.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.
To create a Google Secret Manager machine¶
- Sign in to Certificate Manager - SaaS.
- Click Installations > Machines.
- Click New, and then select Google Secret Manager.
- On the Properties step, in Name, enter a name for the machine.
- For Owning Team, choose the team that owns the machine. System Administrators and PKI Administrators can choose any team. Resource Owners can choose only a team they own or belong to.
-
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.Note
Certificate Manager - SaaS encrypts the credentials you enter and doesn't display them again. On the machine's Properties tab, they appear masked. To keep a stored credential when you edit the machine, leave its masked value unchanged. Keep your own secure record of the credentials in case you need them again.
-
(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.
-
(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 it empty to allow every project the service account can access.
If you set Allowed Project IDs, 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.
-
(Optional) Disable Use Self-Signed JWT only if Google Cloud rejects self-signed tokens for this service account. It's enabled by default, so Certificate Manager - SaaS signs its own authentication token and doesn't call a token endpoint. When it's disabled, Certificate Manager - SaaS exchanges the key for an OAuth 2.0 access token instead.
-
Click Test Access. After the connection succeeds, click Continue. The Discovery step opens.
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.listpermission 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.If Test Access fails, find the start of its message in the following table.
Message begins with What to do ServiceAccountKey must be a valid json stringThe value isn't JSON. Paste the whole, unmodified JSON key file that you downloaded from Google Cloud. invalid service account keyThe 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 keyThe 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 againstEnter a Default Project ID. project <ID> does not exist, or the service account has no access to itCheck the project ID, and check the service account's role bindings on that project. the Secret Manager API is not enabled on projectEnable secretmanager.googleapis.comon the project.the service account lacks permissionAdd the permission named in the message to the service account's role. the call to project <ID> was blocked by a VPC Service Controls perimeterThe 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 connectorA 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 connectionAdd the project to Allowed Project IDs, or clear it. If Test Access fails only when Use Self-Signed JWT is enabled, disable it 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.
-
(Optional) In Project IDs, enter a comma-separated list of the projects to scan. If you leave it empty, discovery scans the Default Project ID project. Discovery fails if a listed project isn't in the machine's Allowed Project IDs.
- (Optional) In Locations, enter a comma-separated list of the locations to scan, which can include
global, one or more regions such aseurope-west1, or both. The default isglobal, so regional secrets are found only if you add their regions. Discovery scans every location in every listed project, and it fails if a location isn't a valid region. - (Optional) In Label Filter, enter the one label, as
key=value, that discovered secrets must carry. The default isvenafi-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 thevenafi-managed=truelabel to them in Google Cloud. - (Optional) In Name Filter, enter text that a secret's name must contain. The text can use letters, digits, underscores, and hyphens.
-
(Optional) To skip certificates that have already expired, enable Exclude Expired Certificates.
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.
-
(Optional) To discover certificates on a schedule, enable Schedule. For Repeat every, choose Day, Week, or Month, and then in At, enter the time. For Week, select the days of the week. For Month, enter the days in Day of month. Times are in Coordinated Universal Time (UTC).
- Click Continue. The Provisioning step opens.
-
(Optional) To provision certificates on a schedule, enable Schedule. For Repeat every, choose Day, Week, or Month, and then in At, enter the time. For Week, select the days of the week. For Month, enter the days in Day of month. Times are in Coordinated Universal Time (UTC).
Scheduled provisioning pushes only certificates that are queued for deployment, such as renewed certificates, so renewals install during the window you choose.
-
Click Finish.
What's next?¶
After you create the machine, provision a certificate to it. You can also run discovery on the machine at any time to track the certificates stored in your secrets.