Connect Google Cloud Identity using a JSON key

A service account key file + the same read-only admin role — works everywhere, with the key-handling responsibility that implies.

1. 1Before you begin. You need: • Access to a Google Cloud project with permission to create service accounts and keys. • A Google Workspace Super Administrator account. • Access to Cybermatic's Connections page. • Your organization's primary Google Workspace domain. • A secure password manager or secrets vault for temporarily protecting the downloaded JSON file. Google recommends Workload Identity Federation instead of service-account keys whenever the external application supports it. JSON keys are long-lived credentials and, unless an expiration policy is configured, do not expire automatically.
2. 2Step 1 — Select the correct project. 1. Open the Google Cloud Console. 2. Click the project selector at the top. 3. Select the project you want to connect to Cybermatic. 4. Confirm that the correct project name appears at the top.
3. 3Step 2 — Confirm "Disable service account key creation" is off or not enforced. 1. Go to: Navigation menu → IAM & Admin → Organization Policies. 2. Click View Constraints. 3. In the Name column, find "Disable service account key creation". This corresponds to iam.disableServiceAccountKeyCreation in the ID column. It may also be shown under iam.managed.disableServiceAccountKeyCreation. 4. If it shows Inactive in the Status column, skip to the next step. 5. If it shows Active, click "Disable service account key creation", then click Manage policy. 6. Under Policy source, select: Override parent's policy. 7. Click Add a rule if a rule is not already displayed. 8. Under Enforcement, select: Off. 9. Click Done, then Set policy. The intended configuration is: Policy source: Override parent's policy Enforcement: Off 10. Return to the policy details page and verify that the effective policy for the project says something similar to "Not enforced" or "Enforcement: Off".
4. 4Step 3 — Enable all required APIs. Enable all five APIs below to avoid connector failures. 1. Go to APIs & Services → Library. 2. Search for and enable each API: 1. Admin SDK API 2. IAM API 3. IAM Service Account Credentials API 4. Security Token Service API 5. Cloud Resource Manager API 3. Confirm that each API shows API enabled. The Admin SDK supports the Directory API, while Google's setup guidance calls for the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.
5. 5Step 4 — Create the service account. 1. Open the Google Cloud navigation menu. 2. Go to IAM & Admin → Service Accounts. 3. Confirm that the intended project is displayed at the top. 4. Select Create service account. 5. Enter: Service account name: cybermatic-identity-scanner Service account ID: allow Google to generate it automatically, normally cybermatic-identity-scanner Description: Read-only Google Workspace directory access for Cybermatic identity scanning 6. Select Create and continue. 7. On Grant this service account access to project, do not add a Google Cloud IAM role unless Cybermatic specifically requires one for another purpose. 8. Select Continue or Done. 9. Do not add users under the optional service-account-user section. 10. Return to the Service Accounts page. The resulting email will have this format: cybermatic-identity-scanner@PROJECT-ID.iam.gserviceaccount.com Copy the entire email address and save it temporarily. You will assign the Workspace admin role to this address later. Google Cloud service accounts are principals and can receive permissions independently of their project-level permissions.
6. 6Step 5 — Create the JSON key. 1. On IAM & Admin → Service Accounts, select the email address of the new service account. 2. Open the Keys tab. 3. Select Add key. 4. Select Create new key. 5. Under Key type, select JSON. 6. Select Create. 7. Your browser downloads the JSON file automatically. 8. Move the file immediately to an approved encrypted location, password manager, or secrets vault. The key can only be downloaded when it is created. The private portion is not downloadable again later. Creating or deleting keys requires permissions such as those in Service Account Key Admin. Do not do any of the following: • Do not email the JSON file. • Do not paste it into Slack, Teams, a ticket, or chat. • Do not upload it to Google Drive or a shared file location. • Do not commit it to GitHub, GitLab, Azure DevOps, or another repository. • Do not rename it to make it look like a normal configuration file. • Do not retain unnecessary copies in your Downloads folder or browser download history.
7. 7Step 6 — Create the Google Workspace read-only role. This step is performed in the Google Admin console, not the Google Cloud console. 1. Sign in to the Google Admin console as a Super Administrator. 2. Go to Account → Admin roles. 3. Select Create new role. 4. Enter: Name: Cybermatic Read Only Description: Read-only Google Workspace directory access for the Cybermatic identity scanner 5. Select Continue. 6. Find and expand Groups. 7. Select only: Read 8. Find and expand Organization Units. 9. Select only: Read 10. Find and expand Users. 11. Select only: Read 12. Select Continue. 13. Review the privileges. 14. Select Create role. (If you already created the Cybermatic Read Only role for the keyless method, skip to the next step.)
8. 8Step 7 — Assign the Workspace role to the service account. Use the dedicated service-account assignment workflow rather than the normal user-member workflow. 1. In Account → Admin roles, locate Cybermatic Read Only. 2. Point to the role and select Assign admin. 3. Select Assign service accounts. 4. Enter the complete service-account email: cybermatic-identity-scanner@PROJECT_ID.iam.gserviceaccount.com 5. Select Add. 6. Select Assign role. 7. Verify that the service account appears as an assigned administrator. Google Workspace explicitly supports assigning any prebuilt or custom role except Super Admin directly to a service account. Changes normally occur quickly but can take up to 24 hours.
9. 9Step 8 — Locate your primary Workspace domain. 1. In the Google Admin console, go to: Account → Domains → Manage domains. 2. Find the entry labeled Primary domain. 3. Copy only the domain name, for example: yourcompany.com Do not enter: • https://yourcompany.com • www.yourcompany.com • admin@yourcompany.com • Your Google Cloud project ID • The service-account email address
10. 10Step 9 — Connect Cybermatic. 1. Sign in to Cybermatic. 2. Open Connections. 3. Under Identity providers, select Google Cloud Identity. 4. Change the authentication method to JSON key. 5. Open the downloaded JSON file using a trusted text editor. 6. Select and copy the entire JSON document, including the opening and closing braces. 7. Paste the entire JSON content into Cybermatic's service-account-key field (it stays masked). 8. Enter the primary Workspace domain, for example: yourcompany.com 9. Select Connect. 10. Allow the initial scan to begin. Important security warning. The downloaded JSON file contains a private key. Treat it like a password. Do not: • Email it. • Upload it to Slack or Teams. • Place it in a public folder. • Commit it to GitHub or another source-control repository. • Paste it into a support ticket. • Edit individual values inside it.
11. 11Troubleshooting. "reading users was denied (403)" — the admin role assignment from Step 7 is missing or still propagating (usually minutes, up to 24 hours). Confirm the Cybermatic Read Only role lists the service account as an assigned administrator. "Google Cloud Identity auth failed" — the key JSON is malformed or the key was deleted in the Cloud console; create a new key and use Connections → Update credentials. 2SV status shows Unknown for everyone — some Workspace editions gate the security-report fields behind additional privileges; edit the custom role and additionally grant the security-related read privilege under Users, then rescan. Connections created before role assignment existed — older connections set up with an administrator email continue working through domain-wide delegation. To move one to the cleaner model, use Connections → Update credentials, paste the key, and enter your primary domain (completing Steps 6–7 first). Rotating the key — create a new JSON key on the same service account, update it in Cybermatic (Connections → Update credentials), then delete the old key in the Cloud console. The role assignment doesn't change. Prefer never rotating again? Switch to the keyless method any time: complete its pool steps, then use Connections → Update credentials and choose Keyless (WIF).

Tip: Whether you use the key or keyless method, the Cybermatic Read Only role is the whole security story: three read privileges and nothing else. The only difference is how the service account proves who it is.