# Google Workspace

> Connect By Dawn to Google Workspace with OIDC (recommended) or SAML, so your people sign in with their Google work account.

This page helps you connect By Dawn to Google Workspace. At the end, people at your company sign in to
By Dawn with their Google work account, through your organization's own connection.

You'll work in two places at once: Google (the Google Cloud console for OIDC, the Google Admin
console for SAML), and **Settings › Organization › Single sign-on** in By Dawn.
[Single sign-on](https://docs.bydawn.com/sso/#add-a-connection) explains the By Dawn side once, so this page
only says which value goes where.

> **Isn't this the same as Sign in with Google?** No. By Dawn's **Continue with Google** button works for any Google account and doesn't involve your
> organization. An SSO connection is yours: you choose who it lets in, it can add people to your organization
> on their first sign-in, and it's offered first to everyone at your verified domains. When you switch someone off
> in Google, they can't sign in to By Dawn through it again.

## Before you start

- [Verify your email domain](https://docs.bydawn.com/sso-domains/) in By Dawn. Use the domains your Google Workspace
  accounts use.
- You need to be the organization's owner in By Dawn. For OIDC you need a Google Cloud project you can
  edit, inside your Workspace organization. For SAML you need to be a Google Workspace super
  administrator.

## Set up OIDC (recommended)

1. In By Dawn, under **How does your identity provider connect?**, pick **OpenID Connect (OIDC)**, name the
   connection `Google Workspace` and choose **Create draft**. Keep the page open, because you'll need its
   **Redirect URI (sign-in redirect / callback URL)**.

2. In the [Google Cloud console](https://console.cloud.google.com/), pick or create a project
   that belongs to your Workspace organization, then open **Google Auth Platform**.

3. Under **Audience**, set the **User type** to **Internal**. This is what keeps the client to
   your own Workspace accounts: Google itself turns away anyone outside your organization. Fill
   in the app name and support email that Google asks for under **Branding**.

4. Under **Clients**, choose **Create client**:
   - **Application type**: **Web application**.
   - **Name**: `SAW`.
   - **Authorized redirect URIs**: add By Dawn's **Redirect URI**.

   Choose **Create**. Copy the **Client ID** into By Dawn's **Client ID**, and paste the **Client secret** into
   By Dawn's client secret box and choose **Save secret**.

5. For By Dawn's **Issuer URL**, use `https://accounts.google.com`. Every Google account has that
   same issuer, which is why the **Internal** user type in step 3 matters. Choose **Save changes**.

6. In By Dawn, choose **Test connection**, then **Activate**.

Google's issuer is shared by every Google account, so two things keep outsiders out. Google
refuses accounts outside your Workspace because the client is **Internal**, and By Dawn refuses any
email that isn't at one of your verified domains ([the email rule](https://docs.bydawn.com/sso/#the-email-rule)).

## Set up SAML

1. In By Dawn, pick **SAML 2.0**, name the connection and choose **Create draft**. Keep the page open, because
   you'll need its **ACS URL (single sign-on URL)** and **SP entity ID (audience)**.

2. In the Google Admin console, go to **Apps › Web and mobile apps**, choose **Add app**, then
   **Add custom SAML app**. Name it `SAW` and choose **Continue**.

3. On **Google Identity Provider details**, choose **Download metadata** under **IdP metadata**.
   In By Dawn, paste the file's contents into **Paste your IdP's metadata XML (optional)**, choose **Fill in from
   metadata**, check the fields and choose **Save changes**. Back in Google, choose **Continue**.

4. On **Service provider details**, fill in:

   | Google field | Value |
   | --- | --- |
   | ACS URL | By Dawn's **ACS URL** |
   | Entity ID | By Dawn's **SP entity ID** |
   | Start URL | leave empty |
   | Signed response | leave unticked. Google always signs the assertion, which is what By Dawn requires. |
   | Name ID format | `EMAIL` |
   | Name ID | **Basic Information › Primary email** |

   Choose **Continue**.

5. Under **Attribute mapping**, you can map **First name** to
   `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` and **Last name** to
   `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` if you'd like By Dawn to fill in people's
   names. Choose **Finish**.

6. Open the app's **User access** and turn it **On for everyone**, or on for the organizational
   units or groups who should use By Dawn. The app starts **off**, so nobody can sign in until you do
   this. Google says the change can take up to 24 hours, though it's usually quicker.

7. In By Dawn, choose **Test connection**, then **Activate**.

Don't use Google's **Test SAML login** button. It starts the sign-in from Google, which By Dawn
refuses (see [How your people sign in](https://docs.bydawn.com/sso/#how-your-people-sign-in)). Use **Test
connection** in By Dawn instead. For the same reason, the By Dawn tile in your people's Google app
launcher won't sign them in, so point them to your organization's SSO address instead.

### When Google's certificate changes

Google's SAML certificate lasts five years. Before it expires, add a new certificate for the app
in the Admin console. In By Dawn, choose **Add a second certificate**, paste the new one and choose **Save
changes**. By Dawn then trusts both, so nobody is turned away when you switch Google to the new one. Once it's in
use, remove the old one in By Dawn.

## If something goes wrong

| What happens | What to check |
| --- | --- |
| Google says `org_internal`, or that the app is restricted to users in its organization | The person is signing in with an account outside your Workspace, such as a personal Gmail. They need their work account. |
| Google says `redirect_uri_mismatch` | The authorized redirect URI must match By Dawn's **Redirect URI** exactly. Copy it again. |
| Google says `app_not_configured_for_user`, or that the service isn't configured for the person | The SAML app isn't on for this person. Check **User access**, and allow time for the change. |
| By Dawn says Google "signed you in with an email address outside this organization's verified domains" | The person's primary email isn't at one of your verified domains. [Verify that domain](https://docs.bydawn.com/sso-domains/), including any secondary domain in your Workspace. |
| By Dawn "couldn't accept the identity provider's response" for a SAML app | By Dawn has an old certificate. Download the metadata again and paste it into By Dawn, or add the new certificate. |

## Where to go next

- [SCIM provisioning](https://docs.bydawn.com/scim/): keep By Dawn's members in step with your directory.

Source: https://docs.bydawn.com/sso-google-workspace/