Skip to main content

SAML SSO with Google Workspace

Google Workspace federates as a custom SAML app. It is the simplest setup of any provider documented here and the most limited: Google signs assertions and nothing else — no assertion encryption, no Single Logout, and no group claim unless you build one. Before you start
  • KnoxCall: a Pro or Enterprise plan, the owner or admin role, and at least one domain verified for single sign-on — a domain you verified for sending mail is a different proof and does not admit a login.
  • Google: a super administrator, at admin.google.com.
Configured KnoxCall before 8 September 2026? Re-check the values below. KnoxCall now signs AuthnRequests (RSA-SHA256), publishes an encryption key, and publishes a Single Logout endpoint. Google ignores all three — it does not verify signed AuthnRequests, does not offer assertion encryption for custom SAML apps, and publishes no single-logout endpoint for one — so a Google-federated workspace loses nothing by having been configured earlier. Confirm the ACS URL and entity ID below still match your metadata document exactly, and if you federate a second, more capable IdP as well, re-upload our metadata there. See the overview for what changed.

1. Create the app

admin.google.com → Apps → Web and mobile apps → Add app → Add custom SAML app. Name it (for example KnoxCall), add a logo if you like, and continue.

2. Copy Google’s IdP details first

Google shows them on the next screen, before it asks you for anything. Take all three now — you paste them into KnoxCall in step 5:
  • SSO URL — https://accounts.google.com/o/saml2/idp?idpid=<idpid>
  • Entity ID — https://accounts.google.com/o/saml2?idpid=<idpid>
  • Certificate — download it, or copy the PEM

3. Service provider details

Replace acme with your workspace slug. The authoritative copy of these values is your own metadata document at https://acme.knoxcall.com/sso/acme/google-workspace/metadata, which is public — fetch it in a browser and read them off it rather than assembling them by hand. KnoxCall’s SP entity ID is its metadata URL. That is what the metadata document says; do not shorten it to the origin, or Google’s audience will not match the one KnoxCall enforces and every assertion will be rejected. There is no box for the test reply URL. KnoxCall’s connection test asks to be answered at its own reply URL, https://acme.knoxcall.com/sso/acme/google-workspace/test-acs, so that a test can never sign anyone in. Google takes one ACS URL per app, and Google’s SAML app error reference documents that it refuses a sign-in request naming a different ACS URL. So a test sign-in through Google Workspace is refused at Google, before KnoxCall sees it, and the connection Test tab cannot report on a Google Workspace connection. So the setup’s test step passes on Google’s details instead. Once the connection holds Google’s sign-in URL and a signing certificate that has not expired — step 6, or the setup wizard’s Connect step — the test step is complete without a test sign-in, and you can turn the connection on once a domain is proven. The first real sign-in is then the check: if it is refused, the person sees a generic error, and the reason is listed under Refused sign-ins on the connection’s Setup tab. The Name ID should be a stable identifier. Google’s own guide says “The default Name ID is the primary email”, and a primary email changes when a person is renamed — which gives them a second KnoxCall account, because KnoxCall recognises people by their NameID (choosing the NameID). Google lets you create custom attributes, in the Admin console or through the Admin SDK, and map the Name ID to one. Put a value there that stays the same when a person is renamed — an employee number you already keep, for example — and fill it in for everyone who will sign in. If you cannot, the primary email still works: sign-ins succeed, the connection shows its NameID notice, and a rename will create a second account. The connection Test tab cannot show you what Google sends (see above). Once people sign in, the connection page shows its NameID notice if what Google sent is an address. These are the values for a connection whose handle is google-workspace, which is the handle the setup wizard gives a new Google Workspace connection: /sso/<workspace>/<handle>/{metadata,acs,login,slo}. Step 2 of the wizard shows your connection’s own values, each with a copy button, and so does the connection’s Certificates tab. A workspace set up before the wizard may have a default connection instead, whose values are the /saml/<workspace>/… alias — https://acme.knoxcall.com/saml/acme/acs and its three siblings. See more than one identity provider.
Google has no field for a KnoxCall Single Logout URL, because Google Workspace does not implement SAML SLO for custom SAML apps. Leave the KnoxCall connection’s Single Logout URL empty — empty means “this connection does not do SP-initiated Single Logout”, and it never falls back to the sign-in URL. Signing a person out of KnoxCall still ends their KnoxCall session; it does not end their Google session, and suspending them in Google is what stops the next sign-in.

4. Attribute mapping

The email mapping is required. With a stable Name ID from step 3, it is the only place KnoxCall finds the person’s address — and admission is decided by that address’s domain: email is on KnoxCall’s default list and is read without configuration. Display name. Google has no single “display name” directory attribute to map, so KnoxCall will not find one — the account is created with the local part of the email address as its name, and the person can change it in their profile. If you keep a full name in a custom schema, map that attribute and name it displayName, which is on KnoxCall’s default list.

5. Group claims: Google sends none by default

There is no group claim in a Google Workspace SAML assertion unless you add one, and even then Google only emits the groups you explicitly list on the app. Groups are not needed for sign-in — they only decide whether a new person lands as member or readonly — so the simplest correct configuration is to skip them and set a default role on the KnoxCall connection. If you do want them: in the app’s SAML attribute mapping, add a Group membership mapping, select the groups it should report, and give the app attribute the name groups. groups is on KnoxCall’s default list. Whatever Google emits for each group is what you type as the keys of the group map on the KnoxCall connection. The map’s values are bounded either way: a group mapped to anything but member or readonly is refused at save time, because “…an IdP group may only map to member or readonly…” — those two and no others. Owner and admin are granted by a human on the team page and by nothing else — no Google group, however named, can produce one.

6. Take the Google values back to KnoxCall

Import the metadata Google gave you

Google’s SAML app screen offers the same values as a metadata download, and that document is one KnoxCall’s importer accepts: a single <EntityDescriptor> in the SAML 2.0 metadata namespace carrying an <IDPSSODescriptor>, which is exactly what it requires. Paste its contents:
The call previews by default and writes nothing until you send it again with "apply": true; what the preview reports and every refusal it can answer with are on the overview. Google’s document carries no SingleLogoutService — its custom-SAML-app setup hands over an SSO URL, an entity ID and a certificate, and nothing else — the import leaves KnoxCall’s single-logout field exactly as it found it rather than reading that absence as an instruction.

Or type the values

In KnoxCall, Settings → Single sign-on → your connection: Saving needs a re-authentication in the last five minutes; that is expected. One re-authentication then covers every SSO save you make from the same signed-in session for fifteen minutes after it, so adding a certificate, claiming a domain and starting a test do not each ask again. Another browser or device asks for its own.

7. Turn the app on, then test

Back in the Google admin console, User access → turn the service ON for everyone, or on for the organisational units and groups that should have KnoxCall. Google’s own changes can take a few minutes to reach the sign-in servers. Test with one account: open https://acme.knoxcall.com/sso/acme/google-workspace/login, sign in, and check the person lands in the workspace with the role you expected. If it fails, the login page names the cause — every message and code is in troubleshooting — and the reason is listed under Refused sign-ins on the connection’s Setup tab. For Google Workspace this sign-in is the connection’s first end-to-end check, because Google cannot run KnoxCall’s test sign-in (step 3).

The Google app tile

Clicking KnoxCall in Google’s app launcher is an IdP-initiated sign-in: Google posts an unsolicited assertion, with the Start URL as its RelayState, and has no setting that starts the tile at KnoxCall instead. IdP-initiated sign-in is off unless you turn it on, so with it off the person is bounced back to the login page with saml_idp_initiated_disabled. People who start at https://acme.knoxcall.com/sso/acme/google-workspace/login are unaffected. See IdP-initiated sign-in for how to switch it on and what it costs; with it on, a Start URL such as /secrets opens that page after the tile signs the person in.

Rotating the Google certificate

Google lets an app hold two SAML certificates at once, which is exactly the overlap this needs. Rotate add-first:
  1. In the Google admin console, open the app and add a second certificate. Leave the first in place.
  2. Copy the new certificate into the KnoxCall connection. Pasting a certificate adds it — a connection can hold several active certificates, and an assertion signed by any of them that has not expired verifies.
  3. Switch Google over to the new certificate.
  4. Retire the old certificate in KnoxCall.
Retiring the only active certificate is refused: “This is the connection’s only active IdP certificate. Add the new certificate first, then retire this one.”