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

# Google Workspace - SSO Setup

> Configure Single Sign-On (SSO) for Ally Security with Google Workspace so members of your organization sign in using their Google Workspace credentials.

## Prerequisites

Before you begin, you'll need:

* Super administrator access to your Google Workspace Admin Console
* The SSO configuration details from Ally Security (we'll provide these after you request SSO setup)
* The email domain(s) that should be enabled for SSO

## Step 1: Create a New SAML App in Google Workspace

1. Navigate to the [Google Admin Console](https://admin.google.com/) and sign in with your administrator account.
2. In the Admin Console, navigate to **Apps** > **Web and mobile apps**.
3. Click **Add app** and select **Add custom SAML app**.

## Step 2: Enter App Details

1. Enter an **App name** (e.g., "Ally Security").
2. Optionally, upload an app icon and enter a description.
3. Click **Continue**.

## Step 3: Download IdP Metadata

On the **Google Identity Provider details** page:

1. Click **Download Metadata** to download the IdP metadata XML file. You will need to share this file with Ally Security.
2. Alternatively, you can copy the **SSO URL**, **Entity ID**, and **Certificate** individually if Ally Security requests these values separately.
3. Click **Continue**.

## Step 4: Configure Service Provider Details

You'll need to enter the following information that we (Ally Security) will provide to you:

1. **ACS URL**: Paste the ACS URL (Assertion Consumer Service URL) provided by Ally Security.
2. **Entity ID**: Paste the Entity ID provided by Ally Security.
3. **Start URL**: Leave this field empty unless Ally Security provides a specific value.
4. **Signed response**: Check this box if requested by Ally Security.
5. **Name ID format**: Select **EMAIL** from the dropdown.
6. **Name ID**: Select **Basic Information > Primary email** from the dropdown.
7. Click **Continue**.

## Step 5: Configure Attribute Mappings

Ally Security requires specific attributes in the SAML response. Configure the following attribute mappings:

1. Click **Add mapping** and add the following attributes:

   **Email address (required)**

   * **Google Directory attribute**: Select `Primary email`
   * **App attribute**: Enter `mail`

   **First name (optional)**

   * **Google Directory attribute**: Select `First name`
   * **App attribute**: Enter `firstName`

   **Last name (optional)**

   * **Google Directory attribute**: Select `Last name`
   * **App attribute**: Enter `lastName`

2. Click **Finish** to complete the app creation.

## Step 6: Enable the App for Users

After creating the app, you need to enable it for your users:

1. On the app details page, find the **User access** section.
2. Click **User access** to expand the settings.
3. To enable for all users:
   * Select **ON for everyone**.
4. To enable for specific organizational units:
   * Click on the specific organizational unit in the left panel.
   * Select **ON** for that organizational unit.
5. Click **Save**.

<Note>
  Changes may take up to 24 hours to propagate to all users, though they typically take effect within a few minutes.
</Note>

## Step 7: Share the IdP Metadata with Ally Security

After completing the setup in Google Workspace, provide Ally Security with your app's metadata:

1. Return to the app details page in Google Admin Console.
2. Click **Download metadata** to download the metadata XML file.
3. Send this metadata file to your Ally Security contact or support team.

Alternatively, provide the following information:

* **SSO URL**: The URL users will be redirected to for authentication
* **Entity ID**: The unique identifier for your Google Workspace as the identity provider
* **Certificate**: The X.509 certificate for verifying SAML assertions

## What to Provide to Ally Security

To complete the SSO setup, please provide the following information:

1. **IdP Metadata file**: The metadata XML downloaded from Google Admin Console (as described in Step 7)
2. **Email domain**: The email domain(s) that should be enabled for SSO (e.g., `@yourcompany.com`)
3. **Test user email** (optional): An email address of a test user that can be used to verify the SSO configuration

## After Setup Is Complete

Once Ally Security has configured SSO on our end:

* All users with email addresses ending in your configured domain will be redirected to Google for authentication
* Users will sign in using their Google Workspace credentials
* Existing users with matching email domains will need to use SSO to sign in

<Warning>
  If there are existing users with email domains that match the SSO configuration, they will be required to use SSO to sign in once it's enabled. Make sure to communicate this change to your team members.
</Warning>

## Troubleshooting

If you encounter issues during setup:

* **Verify attribute mappings**: Ensure that the attribute names (`mail`, `firstName`, `lastName`) match exactly as specified
* **Check user access settings**: Confirm that the app is enabled for the users who need to sign in
* **Verify domain configuration**: Ensure the email domain matches what was provided to Ally Security
* **Check the metadata file**: Ensure you've provided the complete, unmodified metadata XML file
* **Review Google Admin logs**: Check the Admin Console audit logs for any SAML-related errors
* **Contact support**: Reach out to Ally Security support if you need assistance with the configuration

## Additional Resources

* [Google Workspace Admin Help: Set up your own custom SAML application](https://support.google.com/a/answer/6087519)
* [Google Workspace Admin Help: Troubleshoot SAML app error messages](https://support.google.com/a/answer/6301076)