> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SAML SSO with Google Workspace

> Connect Google Workspace to KnoxCall over SAML 2.0 — the custom SAML app, ACS and entity ID, attribute mapping, what Google does not send, and certificate rotation.

# 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](/sso/domains) — 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.

<Warning>
  **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 does not implement SAML Single Logout — 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](/sso/overview) for what changed.
</Warning>

## 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/saml/acme/metadata`, which is public — fetch it in a browser and read them off it rather than assembling them by hand.

| Google field        | Value                                                                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **ACS URL**         | `https://acme.knoxcall.com/saml/acme/acs`                                                                                             |
| **Entity ID**       | `https://acme.knoxcall.com/saml/acme/metadata`                                                                                        |
| **Start URL**       | `https://acme.knoxcall.com/saml/acme/login`                                                                                           |
| **Signed response** | leave unchecked — Google signs the assertion either way, which is what KnoxCall requires                                              |
| **Name ID format**  | the email-address format, matching the `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` that KnoxCall's sign-in request names |
| **Name ID**         | a custom attribute holding a stable identifier — see below                                                                            |

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](/sso/overview#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](/sso/overview#more-than-one-identity-provider).

<Note>
  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.
</Note>

## 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:

| Google directory attribute        | App attribute |
| --------------------------------- | ------------- |
| Basic Information → Primary email | `email`       |
| Basic Information → First name    | `firstName`   |
| Basic Information → Last name     | `lastName`    |

`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:

```http theme={"dark"}
POST /admin/saml/connections/<id>/metadata
{ "xml": "<EntityDescriptor …>" }
```

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](/sso/overview#importing-your-idps-metadata). 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:

| KnoxCall field                                     | Where it is                            | Google value                                                                                       |
| -------------------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **IdP sign-in URL**                                | Connection tab                         | the **SSO URL** from step 2                                                                        |
| **IdP entity ID (optional)**                       | Connection tab                         | the **Entity ID** from step 2                                                                      |
| **Single Logout URL (optional)**                   | Connection tab                         | leave empty — Google does not support SLO                                                          |
| **Only admit specific domains**                    | Connection tab                         | leave it off to admit every domain you have proven for single sign-on; tick it to narrow to a list |
| **Create accounts automatically on first sign-in** | Connection tab                         | on, unless you invite everyone by hand                                                             |
| **Default role**                                   | Attributes & groups tab                | `member` or `readonly`                                                                             |
| **IdP signing certificate**                        | Certificates tab → *Add a certificate* | the certificate you downloaded, with or without the BEGIN/END lines                                |

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: open `https://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](/sso/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 with `saml_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**:

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 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."*