[Yandex Cloud documentation](../../../index.md) > [Yandex Identity Hub](../../index.md) > [Tutorials](../index.md) > [Managing identity federations](index.md) > Google Workspace authentication

# Google Workspace authentication

With an [identity federation](../../concepts/add-federation.md), you can use [Google Workspace](https://workspace.google.com/) to authenticate users in an organization.

Authentication setup includes the following steps:

1. [Creating and setting up a SAML application in Google Workspace](#gworkspace-settings).
1. [Creating and setting up a federation in Yandex Identity Hub](#yc-settings).
1. [Setting up single sign-on (SSO)](#sso-settings).
1. [Authentication](#test-auth).

## Getting started {#before-you-begin}

To follow the steps described in this section, you will need a subscription to Google Workspace services and a verified domain to set up your SAML application for.

## Creating and setting up a SAML application in Google Workspace {#gworkspace-settings}

### Create a SAML application and download a certificate {#create-app}

A SAML application in Google Workspace acts as an identity provider (IdP). Create a SAML application and download a certificate:

1. Open the [Google Workspace Admin Console](https://admin.google.com/).

1. In the left-hand panel, select **Mobile and web applications**.

1. Click **Add** → **Add a custom SAML app**.

1. Enter the name of the app, select the logo, and click **Continue**.

1. In the **Google IdP information** step, the IdP server data is shown. You will need this data when [setting up a federation in Yandex Identity Hub](#yc-settings).

{% note alert %}

Do not close the page where you create an app in Google Workspace: you will get the required configuration data for the **Service provider information** step in [further steps](#add-link).

{% endnote %}

## Creating and setting up a federation in Yandex Identity Hub {#yc-settings}

### Create a federation {#create-federation}

To create a federation:

{% list tabs group=instructions %}

- Cloud Center UI {#cloud-center}

  1. Go to [Yandex Identity Hub](https://center.yandex.cloud/organization).

  1. In the left-hand panel, select ![icon-federation](../../../_assets/console-icons/vector-square.svg) **Federations**.

  1. Click ![Circles3Plus](../../../_assets/console-icons/circles-3-plus.svg) **Create federation** in the top-right corner of the page. In the window that opens:

      1. Give your federation a name. It must be unique within the folder.

      1. You can also add a description, if required.

      1. In the **Cookie lifetime** field, specify the time before the browser asks the user to re-authenticate.
  
      1. In the **IdP Issuer** field, paste the link from the **Entity ID** field on the **Google IdP Information** page in Google Workspace. The link should have the following format:

          ```text
          https://accounts.google.com/o/saml2?idpid=<SAML_app_ID>
          ```

      1. In the **Link to the IdP login page** field, paste the link copied from the **SSO URL** field on the Google Workspace **Google IdP information** page. The link should have the following format:

          ```text
          https://accounts.google.com/o/saml2/idp?idpid=<SAML_app_ID>
          ```

          You can only use HTTP and HTTPS in a link.

      1. Enable **Automatically create users** to add authenticated users to your organization automatically. If you do not enable this option, you will need to [manually add](../../operations/add-account.md#add-user-sso) your federated users.

          A federated user is created automatically only when they log in to a cloud for the first time. If you removed a user from the federation, you can only add them back manually.

      1. Enable **Mandatory re-authentication (ForceAuthn) in IdP** to set [ForceAuthn](../../saml/api-ref/Federation/index.md) to `true` in the SAML authentication request. If enabled, the IdP will request the user to re-authenticate once the Yandex Cloud session expires. This is an optional parameter.

      1. Click **Create federation**.

- CLI {#cli}

    If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

    The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

    1. View the description of the create federation command:

        ```bash
        yc organization-manager federation saml create --help
        ```

    1. Create a federation:

        ```bash
        yc organization-manager federation saml create --name my-federation \
          --organization-id <organization_ID> \
          --auto-create-account-on-login \
          --cookie-max-age 12h \
          --issuer "https://accounts.google.com/o/saml2?idpid=<SAML_app_ID>" \
          --sso-url "https://accounts.google.com/o/saml2/idp?idpid=<SAML_app_ID>" \
          --sso-binding POST \
          --force-authn
        ```

        Where:

        * `--name`: Federation name. It must be unique within the folder.
        
        * `--organization-id`: [Organization ID](../../operations/organization-get-id.md).

        * `--auto-create-account-on-login`: Flag enabling the automatic creation of new cloud users after authenticating on the IdP server. 
        This option makes it easier to create users; however, users created this way will not be able to do anything with cloud resources. This does not apply to the resources for which roles are assigned to the `All users` or `All authenticated users` [public group](../../../iam/concepts/access-control/public-group.md).

            If this option is off, users not added to the organization will not be able to log in to the management console, even if authenticated on your server. In this case, you can manage a list of users allowed to use Yandex Cloud resources.

        * `--cookie-max-age`: Time before the browser asks the user to re-authenticate.
        
        * `--issuer`: ID of the IdP server to use for authentication.

            Use the link provided in the **Object ID** field on the **Google IdP information** page in Google Workspace. This is a link in the format:

            ```text
            https://accounts.google.com/o/saml2?idpid=<SAML_app_ID>
            ```

        * `--sso-url`: URL of the page the browser has to redirect the user to for authentication.

            Use the link from the **SSO URL** field on the Google Workspace **Google IdP information** page. The link should have the following format:

            ```text
            https://accounts.google.com/o/saml2/idp?idpid=<SAML_app_ID>
            ```

            You can only use HTTP and HTTPS in a link.

        * `--sso-binding`: Specify the single sign-on binding type. Most identity providers support the `POST` binding type.

        * `--force-authn`: Once the Yandex Cloud session expires, your IdP will prompt the user to re-authenticate. This is an optional parameter.

- Terraform {#tf}

  If you do not have Terraform yet, [install it and configure the Yandex Cloud provider](../../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform).
  
  
  To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), [authenticate](../../../terraform/authentication.md) using the appropriate method.

  1. Describe the federation parameters in the configuration file.

      Here is an example of the configuration file structure:

      ```hcl
      resource "yandex_organizationmanager_saml_federation" federation {
        name            = "my-federation"
        organization_id = "<organization_ID>"
        auto_create_account_on_login = "true"
        issuer          = "https://accounts.google.com/o/saml2?idpid=<SAML_app_ID>"
        sso_url         = "https://accounts.google.com/o/saml2/idp?idpid=<SAML_app_ID>"
        sso_binding     = "POST"
        security_settings {
          encrypted_assertions = "true"
        }
      }
      ```

      Where:

      * `name`: Federation name. It must be unique within the folder.
      * `description`: Federation description.
      * `organization_id`: [Organization ID](../../operations/organization-get-id.md). 
      * `labels`: Set of key/value label pairs assigned to the federation. This is an optional setting.
      * `issuer`: ID of the IdP server to use for authentication.

          Use the link from the **Object ID** field on the Google Workspace **Google IdP information** page. The link should have the following format:

          ```text
          https://accounts.google.com/o/saml2?idpid=<SAML_app_ID>
          ```

      * `sso_binding`: Specify the single sign-on binding type. Most identity providers support the `POST` binding type.
      * `sso_url`: URL of the page the browser has to redirect the user to for authentication.

          Use this as the destination when copying the link from the **SSO URL** field on the Google Workspace **Google IdP information** page. The link should have the following format:

          ```text
          https://accounts.google.com/o/saml2/idp?idpid=<SAML_app_ID>
          ```

          You can only use HTTP and HTTPS in a link.

      * `cookie_max_age`: Time in seconds before the browser asks the user to re-authenticate. The default value is `8 hours`. 
      * `auto_create_account_on_login`: Flag enabling the automatic creation of new cloud users after authenticating on the IdP server. 
      This option makes it easier to create users; however, users created this way will not be able to do anything with cloud resources. This does not apply to the resources for which roles are assigned to the `All users` or `All authenticated users` [public group](../../../iam/concepts/access-control/public-group.md).

          If this option is off, users not added to the organization will not be able to log in to the management console, even if authenticated on your server. In this case, you can manage a list of users allowed to use Yandex Cloud resources.

      * `case_insensitive_name_ids`: Toggles username case sensitivity.
          If this option is enabled, the IDs of federated user names will be case-insensitive.
      * `security_settings`: Federation security settings: 

          * `encrypted_assertions`: Sign authentication requests.
            
            If this option is enabled, all authentication requests from Yandex Cloud will have a digital signature.

          * `force-authn`: Once the Yandex Cloud session expires, your IdP will prompt the user to re-authenticate. This is an optional parameter.

      For more information about the `yandex_organizationmanager_saml_federation` resource parameters, see the [provider documentation](../../../terraform/resources/organizationmanager_saml_federation.md).

  1. Make sure the configuration files are correct.

      1. In the command line, navigate to the directory where you created the configuration file.
      1. Run a check using this command:

          ```bash
          terraform plan
          ```

      If the configuration is described correctly, the terminal displays the federation parameters. Terraform will show any errors in the configuration. 

  1. Create a federation.

      1. If the configuration does not contain any errors, run this command:

          ```bash
          terraform apply
          ```

      1. Confirm you want to create a federation.

      This will create a federation in the specified organization. You can check the new federation and its settings in the organization's [Federations](https://org.yandex.cloud/federations) section.

- API {#api}

    1. Create a file with the request body, e.g., `body.json`:

        ```json
        {
          "name": "my-federation",
          "organizationId": "<organization_ID>",
          "autoCreateAccountOnLogin": true,
          "cookieMaxAge":"43200s",
          "issuer": "https://accounts.google.com/o/saml2?idpid=<SAML_app_ID>",
          "ssoUrl": "https://accounts.google.com/o/saml2/idp?idpid=<SAML_app_ID>",
          "ssoBinding": "POST",
          "securitySettings": {
            "forceAuthn": true
          }
        }
        ```

        Where:
        
        * `name`: Federation name. It must be unique within the folder.

        * `organizationId`: [Organization ID](../../operations/organization-get-id.md). 

        * `autoCreateAccountOnLogin`: Flag enabling the automatic creation of new cloud users after authenticating on the IdP server. 
        This option makes it easier to create users; however, users created this way will not be able to do anything with cloud resources. This does not apply to the resources for which roles are assigned to the `All users` or `All authenticated users` [public group](../../../iam/concepts/access-control/public-group.md).

            If this option is off, users not added to the organization will not be able to log in to the management console, even if authenticated on your server. In this case, you can manage a list of users allowed to use Yandex Cloud resources.

        * `cookieMaxAge`: Time before the browser asks the user to re-authenticate.
        
        * `issuer`: ID of the IdP server to use for authentication.

            Use the link from the **Object ID** field on the Google Workspace **Google IdP information** page. The link should have the following format:

            ```text
            https://accounts.google.com/o/saml2?idpid=<SAML_app_ID>
            ```
        * `ssoUrl`: URL of the page the browser has to redirect the user to for authentication.

            Use this as the destination when copying the link from the **SSO URL** field on the Google Workspace **Google IdP information** page. The link should have the following format:

            ```text
            https://accounts.google.com/o/saml2/idp?idpid=<SAML_app_ID>
            ```

            You can only use HTTP and HTTPS in a link.

        * `ssoBinding`: Specify the single sign-on binding type. Most identity providers support the `POST` binding type.

        * `forceAuthn`: Parameter that requires the user to re-authenticate once their Yandex Cloud session expires. This is an optional parameter.

    1. To create a federation, use the [create](../../saml/api-ref/Federation/create.md) REST API method for the [Federation](../../saml/api-ref/Federation/index.md) resource or the [FederationService/Create](../../saml/api-ref/grpc/Federation/create.md) gRPC API call and provide a file with the query parameters in your query.
       
       Query example:
       
       ```bash
       curl \
         --request POST \
         --header "Content-Type: application/json" \
         --header "Authorization: Bearer <IAM_token>" \
         --data '@body.json' \
         https://organization-manager.api.cloud.yandex.net/organization-manager/v1/saml/federations
       ```
       
       Response example:
       
       ```bash
       {
        "done": true,
        "metadata": {
         "@type": "type.googleapis.com/yandex.cloud.organization-manager.v1.saml.CreateFederationMetadata",
         "federationId": "ajeobmje4dgj********"
        }
       ```
       
       The `federationId` property contains the ID of the federation you created. Save it for later use.

{% endlist %}

### Add certificates {#add-certificate}

While authenticating, the Yandex Identity Hub service should be able to verify the IdP server certificate. To enable this, download a certificate from the open Google Workspace **Google IdP Information** page and add it to the created federation:

{% list tabs group=instructions %}

- Cloud Center UI {#cloud-center}

  1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization).
  
  1. In the left-hand panel, select ![VectorSquare](../../../_assets/console-icons/vector-square.svg) **Federations**.
  
  1. Click the row with the federation you want to add a certificate to.
  
  1. Click **Adding a certificate** under **Certificates** at the bottom of the page.
  
  1. Enter certificate name and description.
  
  1. Choose how to add a certificate:
  
      * To add a certificate as a file, click **Choose a file** and specify the path to it.
      * To paste the contents of a copied certificate, select the **Text** method and paste the contents.
  
  1. Click **Add**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. View the description of the add certificate command:

      ```bash
      yc organization-manager federation saml certificate create --help
      ```

  1. Add a federation certificate by specifying the certificate file path:

      ```bash
      yc organization-manager federation saml certificate create --federation-id <federation_ID> \
        --name "my-certificate" \
        --certificate-file certificate.pem
      ```

- API {#api}

  Use the [create](../../saml/api-ref/Certificate/create.md) method for the [Certificate](../../saml/api-ref/Certificate/index.md) resource:

  1. Create a request body. In the `data` property, specify the contents of the certificate:

      ```json
      {
        "federationId": "<federation_ID>",
        "name": "my-certificate",
        "data": "-----BEGIN CERTIFICATE..."
      }
      ```

  1. Send the request to add the certificate:

      ```bash
      export IAM_TOKEN=CggaAT********
      curl \
        --request POST \
        --header "Content-Type: application/json" \
        --header "Authorization: Bearer ${IAM_TOKEN}" \
        --data '@body.json' \
        "https://organization-manager.api.cloud.yandex.net/organization-manager/v1/saml/certificates"
      ```

{% endlist %}

{% note tip %}

Make sure to reissue certificates and add them to a federation in a timely manner.

To keep track of when your certificate expires, [subscribe](../../operations/subscribe-user-for-notifications.md) to notifications from the organization. Subscribed users get notifications 60, 30, and 5 days before the certificate expires and after its expiration.

{% endnote %}


## Setting up single sign-on (SSO) {#sso-settings}

### Specify the redirect URL {#add-link}

Once you have created a federation, complete the creation of the SAML application in Google Workspace:

1. Go back to the SAML app creation page's **Google IdP information** step and click **Continue**.

1. In the **Service provider information** step, specify information about Yandex Cloud that acts as a service provider:

    * In the **ACS URL** and **Object ID** fields, enter the ACS URL to redirect users to after successful authentication.

      {% cut "How to get a federation ID" %}
   
      1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization).
      1. In the left-hand panel, select ![VectorSquare](../../../_assets/console-icons/vector-square.svg) **Federations**.
      1. Select the required federation and copy the **Identifier** field value on the federation info page.
   
      {% endcut %}

      
      {% cut "How to get the federation ACS URL" %}

      1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization).
      
      1. In the left-hand panel, select ![VectorSquare](../../../_assets/console-icons/vector-square.svg) **Federations**.
      
      1. Select the required federation and copy the **ACS URL** field value on the federation info page.

      {% endcut %}

    
    * Enable **Signed Response**.

1. Click **Continue**.

    
    {% note tip %}

    To enable the user to contact Yandex Cloud technical support from the [management console](https://center.yandex.cloud/support), in the **Mapping attributes** step, click **Add new mappings** and configure the provision of attributes:
    * **Primary email**.
    * **First name**.
    * **Last name**.

    User attributes supported by the Yandex Identity Hub services are listed in the [User attributes mapping](#claims-mapping) section.

    {% endnote %}


1. To complete the creation of the app, click **Ready**.

### Add users {#add-users}

1. On the app page, under **User access**, click **Disabled for everyone**. 

1. In the page that opens, select who can authenticate with this identity federation:

    * To enable access for all federation users, select **ON for everyone**.

    * To enable access for an individual organizational unit, select the unit from the list on the left and configure the service status for this unit. The child units inherit access settings from the parent units by default.

1. Click **Save**.

### Mapping user attributes {#claims-mapping}

User data | Comment | Application Attributes
------------------- | ----------- | -------------------
Unique user ID | Required attribute. Using an email address is recommended. | **Name ID** field in service provider settings
Surname | Displayed in Yandex Cloud services.<br> Value length limit: 64 characters. | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`
Name | Displayed in Yandex Cloud services.<br> Value length limit: 64 characters. | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`
Full name | Displayed in Yandex Cloud services.<br>Example: Ivan Ivanov.<br> Value length limit: 64 characters. | Attribute unavailable
Email | Used to send notifications from Yandex Cloud services.<br>Example: `ivanov@example.com`.<br> Value length limit: 256 characters. | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
Phone | Used to send notifications from Yandex Cloud services.<br>Example: +71234567890.<br> Value length limit: 64 characters. | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mobilephone`
Profile image | Displayed in Yandex Cloud services.<br> Value length limit: 204,800 characters. | Attribute unavailable

{% note warning %}

The `thumbnailPhoto` attribute value exceeding the length limit is ignored. If the value of a different attribute exceeds the limit, the value part that goes beyond the limit is truncated.

{% endnote %}

>Attribute mapping example:
>
>![image](../../../_assets/organization/google-saml-mapping.png)

### Add users to your organization {#add-users-to-org}

If you did not enable the **Automatically create users** option when [creating the federation](#yc-settings), you will have to add federated users to your organization manually.

To do this, you will need user name IDs. They are returned by the IdP server together with a response confirming successful authentication.

If the **Automatically create users** option is enabled, a federation will only add users logging in to a cloud for the first time. If a federated user has been deleted, they can only be added again manually.

A user can be added by the organization administrator (the `organization-manager.admin` role) or owner (the `organization-manager.organizations.owner` role). To learn how to grant a role to a user, see [Roles](../../security/index.md#add-role).

{% note info %}

To enable a user to access the [management console](https://console.yandex.cloud), assign them a role for the [cloud](../../security/index.md#access-binding-cloud) or [organization](../../security/index.md#access-binding-organization). For added security, you can assign one of the least priveleged roles, such as `resource-manager.clouds.member`. However, you may also assign other roles if you know which permissions you want to grant to the invited users.

To grant these permissions to all the organization users at once, assign the role to the `All users in organization X` [system group](../../../iam/concepts/access-control/system-group.md#allOrganizationUsers). When using the CLI or API, no additional roles are required.

{% endnote %}

{% list tabs group=instructions %}

- Cloud Center UI {#cloud-center}

  1. Go to [Yandex Identity Hub](https://center.yandex.cloud/organization).
  
  1. In the left-hand panel, select ![icon-users](../../../_assets/console-icons/person.svg) **Users**.
  
  1. In the top-right corner, click ![person-plus](../../../_assets/console-icons/person-plus.svg) **Add user** and select ![key](../../../_assets/console-icons/key.svg) **Add federated users** from the drop-down list.
  
  1. In the **Federation** field, select the identity federation you want to add users from.
  
  1. In the **Users** field, list the name IDs of users, separating them with spaces or line breaks.
  
  1. Click **Add**. This will give the users access to the organization.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. View the description of the add user command:

      ```bash
      yc organization-manager federation saml add-user-accounts --help
      ```

  1. Add users by listing their name IDs separated by a comma:

      ```bash
      yc organization-manager federation saml add-user-accounts --id <federation_ID> \
        --name-ids=alice@example.com,bob@example.com,charlie@example.com
      ```

      Where:

      * `--id`: Federation ID.
      * `--name-ids`: Name IDs of users.

- API {#api}

  To add identity federation users to the cloud:

  1. Create a file with the request body, e.g., `body.json`. In the request body, specify the array of name IDs of users you want to add:

      ```json
      {
        "nameIds": [
          "alice@example.com",
          "bob@example.com",
          "charlie@example.com"
        ]
      }
      ```
  1.  Send the request by specifying the federation ID in the parameters:

      ```bash
      curl \
        --request POST \
        --header "Content-Type: application/json" \
        --header "Authorization: Bearer <IAM_token>" \
        --data '@body.json' \
        https://organization-manager.api.cloud.yandex.net/organization-manager/v1/saml/federations/<federation_ID>:addUserAccounts
      ```

{% endlist %}

## Authentication {#test-auth}

When you finish configuring the server, test that everything works properly:

1. Open your browser in guest or private browsing mode.

1. Use this URL to log in to the management console:

   ```text
   https://console.yandex.cloud/federations/<federation_ID>
   ```

   {% cut "How to get a federation ID" %}

   1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization).
   1. In the left-hand panel, select ![VectorSquare](../../../_assets/console-icons/vector-square.svg) **Federations**.
   1. Select the required federation and copy the **Identifier** field value on the federation info page.

   {% endcut %}

   The browser will forward you to the Google authentication page.

1. Enter your credentials and click **Sign in**.

On successful authentication, the IdP server will redirect you back to the ACS URL you specified in the Google Workspace settings and then to the [management console](https://console.yandex.cloud) home page. In the top-right corner, you can see that you are logged in to the console as a federated user.

#### What's next {#what-is-next}

* [Assign roles to the new users](../../security/index.md#add-role).