# Google Workspace (https://docs.fuser.studio/docs/teams/sso/google)

Google Workspace connects to Fuser over **SAML 2.0** using a custom SAML app in the Google Admin console.

## Set up [#set-up]

    ### Create the SAML app [#create-the-saml-app]

    In the [Google Admin console](https://admin.google.com), go to **Apps** → **Web and mobile apps** → **Add app** → **Add custom SAML app**.

    Give it a name (for example, `Fuser`) and continue.

    ### Collect Google's details [#collect-googles-details]

    The **Google Identity Provider details** screen gives you everything Fuser needs:

    | Fuser field             | Google calls it                                                    |
    | ----------------------- | ------------------------------------------------------------------ |
    | **Sign-on URL**         | **SSO URL**                                                        |
    | **Issuer**              | **Entity ID**                                                      |
    | **Signing certificate** | **Certificate** — use **Download certificate** to get the PEM file |

    Open the downloaded certificate in a text editor and copy it whole, including the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines.

    ### Register the provider in Fuser [#register-the-provider-in-fuser]

    In Fuser, open **Settings** → **Workspace** → **Security** → **Single Sign-On**, choose **SAML**, enter your email domain and the three values above, and click **Add provider**.

    Return to the Google setup wizard's **Service provider details** screen and fill it in from Fuser's provider card:

    | Google field  | Paste from Fuser's provider card |
    | ------------- | -------------------------------- |
    | **ACS URL**   | **ACS URL**                      |
    | **Entity ID** | **Entity ID / Audience URI**     |

    Leave **Start URL** empty and leave **Signed response** unchecked. Set **Name ID format** to **EMAIL** and **Name ID** to **Basic Information > Primary email**.

    Fuser does not support IdP-initiated sign-in, so the Fuser tile in the Google app launcher will not work — members sign in from Fuser.

    ### Map the attributes [#map-the-attributes]

    On the next screen, **Attribute mapping**, add three mappings. The **App attribute** name on the right is what Fuser reads, and it is matched exactly:

    | Google Directory attribute | App attribute |
    | -------------------------- | ------------- |
    | **Primary email**          | `email`       |
    | **First name**             | `givenName`   |
    | **Last name**              | `surname`     |

    Only `email` is required, but without the two name attributes members show up under their email address instead of their name.

    Click **Finish**.

    ### Turn on user access [#turn-on-user-access]

    Open the app you just created and click **User access**. Google creates every SAML app **OFF for everyone** — until you change this, nobody can sign in.

    Set it to **ON for everyone**, or turn it on for the specific organizational units and groups that should have access, and save.

    > [!WARNING] Give the access change time to propagate
>
> Until access is on, Google rejects the sign-in with **app\_not\_enabled\_for\_user**. After you switch it on the change usually takes effect within minutes, but Google allows up to 24 hours, so wait and retry before changing anything else.

    ### Verify the domain and test [#verify-the-domain-and-test]

    Add the TXT record shown on Fuser's provider card, wait for the card to flip to **Verified — SSO active**, then sign in from Fuser with a Workspace address on that domain.

    See [Verifying the domain with DNS](https://docs.fuser.studio/docs/teams/sso.md#verifying-the-domain-with-dns) for the details.

## Rotating the signing certificate [#rotating-the-signing-certificate]

Google's SAML certificates belong to your Workspace account, not to an individual app: one default certificate serves every SAML app, with room for a second while you roll over. Fuser stores the copy you pasted at registration and never fetches updates.

So when you rotate the account certificate, every Fuser provider using it must be removed and re-added with the new value, or sign-in fails on signature validation.

Removing and re-adding mints new endpoint URLs and a new DNS record, so plan on re-pasting them in your IdP and verifying the domain again — see [Provider settings are final](https://docs.fuser.studio/docs/teams/sso.md#provider-settings-are-final).

## Troubleshooting [#troubleshooting]

    Despite the name, this is **not** an access problem. Google returns it when the issuer in Fuser's authentication request does not match the **Entity ID** in the app's **Service provider details** — and the comparison is case-sensitive.

    The usual cause is a stale value: removing and re-adding a provider in Fuser mints a new Entity ID, and Google keeps the old one until you paste the new one in. Copy **Entity ID / Audience URI** from Fuser's provider card into Google and compare it character for character.

    This is the access error. Check **User access** on the app, confirm the member's organizational unit is included, and allow time for the change to propagate. It comes from Google before any assertion reaches Fuser, so nothing in the Fuser configuration affects it.

    The certificate in Fuser is not the one the app is signing with. Google's certificates are **account-level**, not per-app — your Workspace account holds one default certificate used by all SAML apps, and may hold a second — so this normally means the account certificate was rotated, or the app was switched to the other one. Remove the provider in Fuser and re-add it with the certificate the app currently uses.

    Recreating a SAML app does not by itself issue a new certificate; the new app picks up the newest account-level certificate.

    Copy **Entity ID** from Google's identity provider details screen exactly. It looks like `https://accounts.google.com/o/saml2?idpid=…`, where `idpid` identifies your Workspace account rather than the individual app — so every SAML app in your account shares it, and seeing a familiar value does not confirm you copied it from the right app.

    The **First name** and **Last name** attribute mappings are missing. Add them as `givenName` and `surname` in the app's **Attribute mapping** screen.

## What's Next? [#whats-next]

  - [SSO overview](https://docs.fuser.studio/docs/teams/sso.md): Domain verification, enforcement, and what members see.

  - [Members](https://docs.fuser.studio/docs/teams/members.md): Roles, invitations, and seat management.