# Google SSO

{% stepper %}
{% step %}

## Create a custom attribute for Lenses groups <a href="#create-a-custom-attribute-for-lenses-groups" id="create-a-custom-attribute-for-lenses-groups"></a>

{% hint style="info" %}
Google doesn't expose the groups, or organization unit, of a user to a SAML app. This means we must set up a custom attribute for the Lenses groups that each user belongs to.
{% endhint %}

Open the [Google Admin console](https://admin.google.com/) from an administrator account.

* Click the **Users** button
* Select the **More** dropdown and choose **Manage custom attributes**
* Click the **Add custom attribute** button
* Fill the form to add a **Text, Multi-value** field for **Lenses Groups**, then click **Add**

Learn more about [Google custom attributes](https://support.google.com/a/answer/6208725?hl=en#zippy=%2Cadd-a-new-custom-attribute)
{% endstep %}

{% step %}

## Assign Lenses groups attributes to Google users <a href="#assign-lenses-groups-attributes-to-google-users" id="assign-lenses-groups-attributes-to-google-users"></a>

{% hint style="info" %}
The attribute values should correspond exactly with the names of groups created within Lenses.
{% endhint %}

Open the [Google Admin console](https://admin.google.com/) from an administrator account.

* Click the **Users** button
* Select the **user** to update
* Click **User information**
* Click the **Lenses Groups** attribute
* Enter one or more groups and click Save
  {% endstep %}

{% step %}

## Add Google custom SAML app <a href="#add-google-custom-saml-app" id="add-google-custom-saml-app"></a>

Learn more about [Google custom SAML apps](https://support.google.com/a/answer/6087519?hl=en)

* Open the [Google Admin console](https://admin.google.com/) from an administrator account.
* Click the **Apps** button
* Click the **SAML** *apps* button
* Select the **Add App** dropdown and choose **Add custom SAML app**
* Run through the below steps

### App Details

* Enter a descriptive name for the Lenses installation
* Upload a [Lenses icon](https://lenses.io/logos/)

{% hint style="info" %}
This will appear in the Google apps menu once the app is enabled
{% endhint %}
{% endstep %}

{% step %}

## Configure SAML

### Service provider details <a href="#service-provider-details" id="service-provider-details"></a>

Given the base URL of the Lenses installation, e.g. **<https://lenses-dev.example.com>**, fill out the settings:

| Setting         | Value                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ACS URL         | <p>Use the <strong>base url</strong> with the callback path<br>e.g. <strong><https://lenses-dev.example.com/api/v2/auth/saml/callback?client_name=SAML2Client></strong></p> |
| Entity ID       | <p>Use the <strong>base url</strong><br>e.g. <https://lenses-dev.example.com></p>                                                                                           |
| Start URL       | Leave empty                                                                                                                                                                 |
| Signed Response | Leave unchecked                                                                                                                                                             |
| Name ID format  | Leave as **UNSPECIFIED**                                                                                                                                                    |
| Name ID         | Leave as **Basic Information > Primary Email**                                                                                                                              |

### Attribute mapping <a href="#attribute-mapping" id="attribute-mapping"></a>

* Add a mapping from the custom attribute for Lenses groups to the app attribute **groups**

### Enable the app <a href="#enable-the-app" id="enable-the-app"></a>

* From the newly added app details screen, select **User** *access*
* Turn on the service

{% hint style="info" %}
Lenses will reject any user that doesn't have the groups attribute set, so enabling the app for all users in the account is a good option to simplify ongoing administration.
{% endhint %}

Download the Federation Metadata XML file with the Google IdP details.
{% endstep %}

{% step %}

## Download SAML Certificates <a href="#create-a-custom-attribute-for-lenses-groups" id="create-a-custom-attribute-for-lenses-groups"></a>

Click **Download Metadata** and save the metadata file for configuring Lenses.Configure SAML in HQ.
{% endstep %}

{% step %}

## Configure SAML in HQ <a href="#configure-saml-in-hq" id="configure-saml-in-hq"></a>

SAML configuration is set in HQ's **config.yaml** file. See [here ](https://docs.lenses.io/hub/install/6.0/deployment/configuration/hq#samlconfig)for more details.
{% endstep %}
{% endstepper %}