Before you start
- A Google Cloud organization, and the IAM Workforce Pool Admin role (
roles/iam.workforcePoolAdmin) or the Owner role on it. - The IAM and Resource Manager APIs enabled.
A SplitSecure identity provider, created in a threshold vault and approved by its Guardian Team. See Create an identity provider.
A second browser profile, signed in to the Web App, for the test sign-in. Start and finish the test in that same profile.
This guide makes a Google Cloud workforce pool a connected app of your SplitSecure identity provider, so a console session starts only when your Guardian Team, the group of devices that together approve each proposal, approves it. Workforce identity federation lets people outside Google’s own directory sign in to Google Cloud. You download the identity provider’s metadata in the Web App, create a pool in Google Cloud with SplitSecure as its SAML provider, grant roles to its users, and register the pool in the Web App.
Values you exchange
| Value | Where to find it | Where to paste it |
|---|---|---|
| SplitSecure metadata (XML) | The identity provider’s SAML endpoints card, Download metadata XML | Google Cloud, IDP metadata file (XML), in Add SplitSecure as a SAML provider |
| Pool ID | Google Cloud, in Create a workforce pool | The Web App, Workforce Pool ID, in Create the connected app |
| Provider ID | Google Cloud, in Add SplitSecure as a SAML provider | The Web App, Workforce Provider ID, in Create the connected app |
Collect the SplitSecure values
In the Web App
In the Web App, open Vaults, then your vault, then the identity provider. The SAML endpoints card shows three values:
- SAML IdP Entity ID
- SSO URL (HTTP-Redirect)
- SSO URL (HTTP-Post)
Under them, Download metadata XML saves the metadata file and Download Certificate offers the certificate in PEM format or DER format.
- Click Download metadata XML on the card and save the file.
Create the workforce pool
In the Google Cloud console
Select your organization.
Click Create Pool.
Fill in the fields.
Field Value Name SplitSecure PoolThe display namePool ID Generated from the nameKeep it. 6 to 63 characters: lowercase letters, digits and hyphens Description Optional Click Next.
You cannot change the pool ID later. It must be unique across all workforce identity pools in Google Cloud, not only in your organization, and it cannot start with gcp-.
In the Providers section, click Add Provider.
In Select a Provider vendor, choose Generic Identity Provider.
In Select an authentication protocol, choose SAML.
Click Continue.
Fill in the fields.
Field Value Name SplitSecure ProviderThe display nameProvider ID Generated from the nameKeep it. 4 to 32 characters Description Optional IDP metadata file (XML) Upload the SplitSecure fileThe metadata carries the entity ID, the sign-in URL and the certificate Enable provider On Click Continue.
Skip the Share your provider information with IdP card: the Web App derives these values from the pool ID and the provider ID.
SplitSecure sends the NameID as the SAML subject, and no other attribute. With the default NameID, the subject is the email of the person who signs in. Map the subject only.
| Google attribute | Assertion attribute | Notes |
|---|---|---|
google.subject | assertion.subject | The email of the person who signs in |
- Set the Attribute mapping as above.
- Optionally, add an attribute condition and turn on Detailed Logging.
- Click Submit.
Grant access to federated users
In the Google Cloud console
A federated user can open Google Cloud only after you grant them a role.
- Go to IAM & Admin → IAM.
- Select the project, folder or organization.
- Click Grant Access.
- In New principals, enter a principal identifier from the list below.
- In Select a role, choose the role, for example Viewer.
- Click Save.
One user, where USER_SUBJECT is that user’s email:
principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/USER_SUBJECTThe principal set below grants the role to every identity in the pool, now and in the future. Prefer one principal per user unless every pool user needs the role.
Every user of the pool:
principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/*With a grant to the whole pool, Google does not check who signs in. The connected app decides: each sign-in needs the Guardian Team’s approval, and Email must end with limits it to your email domain. Set that domain in Create the connected app below. Keep the default NameID, built from each person’s email, so that Cloud Audit Logs show who acted. Google cannot grant by group or by attribute here, because SplitSecure sends only the subject.
Google keys a user’s access to the subject. If a user’s email changes, the user loses access until you grant the role to the new email.
See Principal identifiers (opens in a new tab) for the other forms.
Connect Google Cloud to SplitSecure
In the Web App
In the Web App, open Vaults, then your vault, then the identity provider. Click New Connected App and pick the service provider’s card. Name is required, and the Threshold Identity Provider field is fixed to this provider.
Click the Google Cloud (SAML2) card.
Enter a Name, for example
Google Cloud.In Workforce Pool ID, paste the pool ID.
In Workforce Provider ID, paste the provider ID.
Check Entity ID and ACS URL. They are read-only, and generated from the two IDs.
Set the NameID. Google Cloud reads the subject as an opaque string, so the NameID format is your choice. Keep the default, Email Address. The email SplitSecure sends must equal the email in the principal you granted a role to.
Keep the default NameID value, Built from each person’s email. Its NameID template is
${user.email}, which SplitSecure fills with the email of the person who signs in. To accept only one email domain, enter it in Email must end with, for example@example.com. SplitSecure then refuses anyone whose email ends otherwise.Optionally, under Advanced Options, turn on Selective notifications so members can choose who gets notified for the Guardian Team’s proposals, set the Account Sensitivity banner shown on this connected app’s proposals (None, Low, Medium, High or Critical), and enter a Description or a Reason for creation.
Click Propose connected app. The Web App opens the proposal under Requests. The members of the Guardian Team approve it on their devices, in the mobile app. When the vote passes, the connected app appears under Connected Apps.
Test the sign-in
In the Web App
In the Web App, open Connected Apps, find the new connected app and click Log in. Some service providers, such as Iru, accept only a sign-in that starts on their side. For those, the Web App first sends you to the service provider, which sends you back. The Web App then shows the details of the connected app. If the page asks for a value, such as a NameID, enter it. To leave a note for the approvers, open Advanced Options and fill in Reason for access. Click Log in again. The members of the Guardian Team approve the sign-in on their devices, in the mobile app. When the vote passes, click Login on the proposal page to finish the sign-in at the service provider.
Only the browser profile that clicked Log in can show Login, and only once.
For Google Cloud, the Web App first sends you to Google’s workforce sign-in page for your pool, and Google sends you back to the Web App. With the default NameID, Built from each person’s email, you do not enter an email. SplitSecure sends the email of your own identity, so it must match the principal you granted a role to.
The Google Cloud console opens, signed in as the federated user, with the role you granted.
In the test profile, open the workforce sign-in page of your provider:
https://auth.cloud.google/signin/locations/global/workforcePools/POOL_ID/providers/PROVIDER_ID?continueUrl=https://console.cloud.google/The service provider sends you to the Web App, which opens the Log in page for the connected app. If the page asks for a value, enter it. Click Log in. The members of the Guardian Team approve the sign-in on their devices, in the mobile app. When the vote passes, click Login to return to the service provider, signed in.
The federated Google Cloud console opens at https://console.cloud.google/.
Troubleshooting
| Issue | Solution |
|---|---|
| Log in opens a Google error | The pool ID or provider ID is wrongCompare the connected app’s Entity ID with the pool and the provider in Google Cloud |
| The user cannot open any resource | No role is granted to the federated principalGrant a role in Grant a role to the federated principal |
| Google reports an attribute mapping error | The mapping uses an attribute SplitSecure does not sendMap google.subject to assertion.subject only |
| The user signs in without access | The identity’s email differs from the granted principalSign in to SplitSecure with the identity whose email has the role, or grant the role to that email |
| Google rejects the assertion | The provider holds outdated metadataDownload the metadata again from the SAML endpoints card and upload it to the provider |
| The session ends too early | The pool’s session duration is shortRaise the session duration in the pool settings |
External resources
- Configure workforce identity federation (opens in a new tab): User authentication configuration
- Workforce identity federation (opens in a new tab): Workforce identity federation overview
- Principal identifiers (opens in a new tab): IAM principal identifier formats