Google Workspace SAML single sign-on

Before you start

• Super administrator rights in the Google Admin console
• An Enterprise plan on CCTVplanner, with an active subscription
• Owner or administrator access to the CCTVplanner organization console at cctvplanner.io/organization
• The ability to publish a DNS TXT record for each e-mail domain you will claim
• A second factor enrolled on the owner account, if you intend to make single sign-on required

Steps

1. 1

   Verify your e-mail domains in the CCTVplanner console

   Open cctvplanner.io/organization and add every domain your people sign in with. Google Workspace secondary and alias domains count as separate domains here.

   The console lists each claimed domain together with the DNS TXT record to publish for it. Publish the record, then run the check in the console.

   Verification is a precondition, not a formality. A connection is bound to your verified domains, and an assertion carrying an address outside them is refused with SSO_EMAIL_OUTSIDE_DOMAIN, at sign-in and again at every token refresh.

   The record shape is in the table below. The console is authoritative for the token.

   Record typeTXT

   Name_cctvplanner-challenge. followed by your domain

   Valuecctvplanner-verify= followed by the token the console shows

   If a person signs in as [email protected], alias.example needs its own record and its own verification, or that person gets SSO_EMAIL_OUTSIDE_DOMAIN.

2. 2

   Create the custom SAML app in Google

   In the Google Admin console, go to Menu, then Apps, then Web and mobile apps.

   Choose Add app, then Add custom SAML app.

   Give it a name your people will recognize on Google's app screens, for example CCTVplanner.

   An icon is optional and changes nothing about the protocol.

3. 3

   Take the Google identity provider metadata

   The next page is Google Identity Provider details. Option 1 is Download the IDP metadata. Option 2 is the SSO URL and Entity ID as text, with the Certificate as a separate download and a SHA-256 fingerprint alongside.

   Download the IDP metadata and keep the XML file. That one file carries the SSO URL, the issuer and the signing certificate.

   Our console accepts either a metadata URL or pasted metadata XML for a connection. Prefer the URL where you have one: re-saving the connection re-reads it, while a pasted document has to be replaced by hand. Google's documentation for a custom SAML app offers a download and does not document a metadata URL, so plan on pasting the XML.

   You do not need the SHA-256 fingerprint. It is there for service providers that ask for a fingerprint instead of a certificate.

4. 4

   Fill in the service provider details

   Press Continue to reach Service provider details.

   Copy the ACS URL and Entity ID out of the CCTVplanner console with the copy buttons there. The console is authoritative for both. The values in the table below are so you recognize them.

   Leave Start URL empty unless you want Google's app launcher to land people somewhere specific. Start URL sets RelayState, and the redirect target has to be on our allow list.

   Set Name ID format and Name ID before you save.

   ACS URLhttps://auth.cctvplanner.io/auth/v1/sso/saml/acs

   Entity IDhttps://auth.cctvplanner.io/auth/v1/sso/saml/metadata

   Start URLleave empty

   Signed responseunchecked

   Name ID formatEMAIL

   Name IDBasic Information > Primary email

   We read the e-mail attribute names first, in the order shown in the attribute table near the end of this page, and fall back to the Name ID only when no e-mail attribute arrives. So a Name ID on a non-address value does not by itself break a connection that maps an e-mail attribute. Map the e-mail attribute in the next step either way.

5. 5

   Map the attributes

   Press Continue to reach Attribute mapping, then use Add mapping once per row in the table below.

   On the left pick the Google Directory attribute. On the right type the App attribute exactly as written, including the capital letter in firstName and lastName, and with no spaces.

   Google's group membership mapping is a separate, optional row. We read a groups claim but do not use it to set roles, so leave it out unless you want it in the assertion for your own audit reasons. Google caps group membership mapping at 75 groups.

   Press Finish.

   Basic Information > Primary emailemail

   Basic Information > First namefirstName

   Basic Information > Last namelastName

   Use the names exactly as in the table. We match the attribute name literally.

6. 6

   Turn the app on for the right people

   Back on the app page, open User access.

   Select On for everyone, or pick an organizational unit or group and set its service status to On.

   Press Save. Google's own wording on timing: changes can take up to 24 hours but typically happen more quickly.

   Anyone the app is off for never reaches us. Google shows its own error page and no assertion is issued.

7. 7

   Create the connection in CCTVplanner and set the policy

   In the organization console, create the connection: a display name, the provider template, and the metadata. Paste the XML from step three, or give the metadata URL if you have one.

   A new connection starts in testing. While it is testing, ordinary sign-ins through it are refused with SSO_CONNECTION_TESTING. That is a different state from disabled, which refuses with SSO_PROVIDER_DISABLED.

   Choose whether just-in-time provisioning is on. With it on, a first successful sign-in from a verified domain creates the account at the role you pick, if a seat is free. With it off, people have to exist here first.

   Set the sign-in policy. Optional lets passwords and single sign-on coexist. Required stops password sign-in for everyone at your verified domains.

   Set the session cap if 24 hours is longer than you want. Access tokens live fifteen minutes regardless.

   Required keeps one escape hatch: the owner may still use a password, but only with a verified second factor. Enrol that factor before you switch to Required, or you will meet SSO_OWNER_MFA_REQUIRED and will have to get back in through single sign-on to change the policy.

8. 8

   Test the connection, then switch it on

   Run the test on the connection in the organization console. The ordered flow, and what it does to your own session, is in the proof list below.

   A connection can only be switched on after its test passes.

   Switch it on, have one real person sign in, and only then move the sign-in policy to Required if you want it.

9. 9

   Plan for the certificate rotation

   Google X.509 certificates for SAML apps have a five-year lifetime, and you can hold two at a time. They live under Menu, Security, Authentication, SSO with SAML applications, which is a page separate from the app itself.

   A daily job on our side reads the identity provider's signing certificate expiry out of the connection's metadata and e-mails the organization owner before it lapses. The metadata itself is not refreshed for you.

   When Google rotates the certificate, select the new certificate for this app in its Service provider details, then open the connection in our console and save it again, which re-reads the metadata URL. If the metadata was pasted as XML, paste the new document.

   Google's own wording on timing: after you replace a certificate, it may take up to 24 hours for the new certificate to be available for use by your SAML applications.

   Editing an active connection's metadata puts it back into testing, so sign-ins through it are refused with SSO_CONNECTION_TESTING until you run the test again and switch the connection on. Do the rotation in a window where that is acceptable.

Name ID and attribute mapping

Prove it works

1. Leave the connection in testing. Until it is switched on, anyone signing in through it is refused with SSO_CONNECTION_TESTING, so nobody is caught by a half-finished mapping.
2. In the organization console, open the connection and press the test button. Do this as the owner, in the session you already have.
3. The console opens Google in a new browser tab. Sign in there with your own Workspace account.
4. That sign-in creates a twin account: a second, separate CCTVplanner account at your own address, held by Google. It occupies no seat, because an SSO identity is never linked to an existing password account.
5. The test tab confirms the result, signs that twin account out again and hands the outcome back to the console tab you started from, which restores your own session.
6. Read the outcome in the console. If the test failed, fix it in Google or in the connection, save, and run the test again.
7. Switch the connection on. Only a passed test allows that.
8. Have one person at a verified domain sign in for real at cctvplanner.io and confirm their name and address are right. If just-in-time provisioning is off, add that person in the console first, or they are refused with SSO_JIT_DISABLED.
9. Only when a real sign-in works should you move the sign-in policy to Required.

When sign-in fails

Worth knowing

• Google Workspace cannot drive our SCIM endpoint. Google documents automated provisioning only for apps in its catalog, and a custom SAML app offers no provisioning settings. On Google, plan on just-in-time provisioning plus the console for joiners and leavers, or point a directory that does speak SCIM at our endpoint. Provisioning tokens are created in the organization console.
• Identity provider initiated sign-in is accepted. What you control is the redirect target, which has to be on our allow list. Google's Start URL field is what sets that target.
• A sign-in through Google never joins an existing password account at the same address. The identity provider holds its own account, so a person who already had a CCTVplanner password account ends up with two accounts at one address. Decide which one your people are meant to use before you switch the connection on.
• The organization console also shows the service provider values with copy buttons, your claimed and verified domains, the connection with its display name, provider template, entity id and certificate expiry, the sign-in policy, the provisioning tokens, and an audit list with an export button.
• Things we do not have, so you can plan around them: no OpenID Connect, no IP allow list, no SIEM streaming, no group to role mapping, no SCIM Groups, no uptime SLA, no SOC 2 or ISO 27001, and no third-party penetration test report.