SAML SSO with Google Workspace
Google Workspace federates as a custom SAML app. It is the simplest of the four providers to set up 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: an 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.
1. Create the app
admin.google.com → Apps → Web and mobile apps → Add app → Add custom SAML app. Name it (for exampleKnoxCall), 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
Replaceacme with your workspace slug. The authoritative copy of these values is your own metadata document at https://acme.knoxcall.com/saml/acme/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.
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.
Once step 6 is done, run a sign-in from the connection’s Test tab in KnoxCall and read the NameID in the verdict to confirm what Google actually sends.
These are the
default connection’s values — the connection every workspace starts with, and the one the /saml/<workspace>/… alias resolves to. If Google Workspace is a second identity provider for this workspace, it gets its own connection with its own handle, and its values are /sso/<workspace>/<handle>/{metadata,acs,login,slo} — for a handle of google, https://acme.knoxcall.com/sso/acme/google/acs and its three siblings. Open that connection under Settings → Single sign-on and its Certificates tab lists all five, each with a copy button. 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 IdP 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
Theemail 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 namegroups. 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:
"apply": true; what the preview reports and every refusal it can answer with are on the overview. Google’s document carries no SingleLogoutService, because Google does not implement SAML Single Logout — 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.
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: openhttps://acme.knoxcall.com/saml/acme/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.
The Google app tile
Clicking KnoxCall in Google’s app launcher uses the Start URL you set in step 3, so it is an ordinary SP-initiated sign-in and works with IdP-initiated login switched off. That is one reason to fill the Start URL in: leave it blank and the tile produces an unsolicited assertion instead, which KnoxCall refuses withsaml_idp_initiated_disabled unless you have deliberately opted 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:- In the Google admin console, open the app and add a second certificate. Leave the first in place.
- 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 verifies.
- Switch Google over to the new certificate.
- Retire the old certificate in KnoxCall.