Get started
Yandex Identity and Access Management

Authentication using G Suite

If you have an identity federation, you can use Google's G Suite to authenticate in the cloud.

To set up authentication:

  1. Start to create an SAML app.
  2. Create an identity federation in the cloud.
  3. Add certificates to the federation.
  4. Get a console login link.
  5. Finish creating your SAML app.
  6. Add users to the cloud.
  7. Test the authentication process.

Before you start

To use the instructions in this section, you need:​

  1. The admin or resource-manager.clouds.owner role in the cloud.
  2. An activated domain that you're going to configure the SAML app in G Suite for.

Start creating an SAML app

Before you can create an identity federation in the cloud, you need to get information about the IdP (your SAML app in G Suite):

  1. Log in to the G Suite admin console .
  2. Click the Apps icon.
  3. Click on the SAML apps card.
  4. Click the add app button (the + icon in the lower-right corner of the page).
  5. At the bottom of the window that opens, click Set up my own custom app.
  6. The Google IdP Information page shows the IdP server data. Don't close this window: you need this data to create an identity federation and add a certificate.

Create a federation in the cloud

  1. Open the folder page in the management console.

  2. Select the Federations tab in the left menu.

  3. Click Create federation.

  4. Enter a name for the federation. The name must be unique within the folder.

  5. Add a description if necessary.

  6. In the Cookie lifetime field, specify the time before the browser asks the user to re-authenticate.

  7. Copy the link from the Entity ID field of the G Suite Google IdP Information page to the IdP Issuer field. This is a link in the format:

    https://accounts.google.com/o/saml2?idpid=<SAML app ID>

  8. Copy the link from the SSO URL field of the G Suite Google IdP Information page to the Link to the IdP login page field. This is a link in the format:

    https://accounts.google.com/o/saml2/idp?idpid=<SAML app ID>

  9. Enable Automatically create users to automatically add a new user to the cloud on successful authentication. This option simplifies the user setup process, but the user only has the resource-manager.clouds.member role and they can't do anything with the resources in the cloud. Exceptions are the resources that the allUsers or allAuthenticatedUsers system group roles are assigned to.

    If this option is disabled, users who aren't added to the cloud can't log in, even if they have authenticated on your server. This way you can create a white list of users that are allowed to use Yandex.Cloud.

If you don't have the Yandex.Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

  1. See the description of the create federation command:

    $ yc iam federation create --help

  2. Create a federation:

    $ yc iam federation create --name my-federation \
    --auto-create-account-on-login \
    --cookie-max-age 12h \
    --issuer "https://accounts.google.com/o/saml2?idpid=C03xolm0y" \
    --sso-binding POST \
    --sso-url "https://accounts.google.com/o/saml2/idp?idpid=C03xolm0y"

    Where:

    • name: Federation name. The name must be unique within the folder.

    • auto-create-account-on-login: Flag for automatically creating new users in the cloud after authenticating on the IdP server. This option simplifies the user setup, but users created this way are only assigned the resource-manager.clouds.member role by default: they can't do anything with cloud resources. Exceptions are the resources that the allUsers or allAuthenticatedUsers system group roles are assigned to.

      If this option is disabled, users who aren't added to the cloud can't log in to the management console, even if they authenticate with your server. In this case, you can manage the white list of users who are allowed to use Yandex.Cloud.

    • cookie-max-age: Time before the browser asks the user to re-authenticate.

    • issuer: IdP server ID to be used for authentication.

      Copy here the link from the Entity ID field of the G Suite Google IdP Information page. This is a link in the format:

      https://accounts.google.com/o/saml2?idpid=<SAML app ID>

    • sso-url: URL of the page that the browser redirects the user to for authentication.

      Copy here the link from the SSO URL field of the G Suite Google IdP Information page. This is a link in the format:

      https://accounts.google.com/o/saml2/idp?idpid=<SAML app ID>

    • sso-binding: Specify the Single Sign-on binding type. Most Identity Providers support the POST binding type.

  1. Get the ID of the folder to create your federation in.

  2. Create a file with the request body (for example, body.json):

    {
  "folderId": "<folder ID>",
  "name": "my-federation",
  "autocreateUsers": true,
  "cookieMaxAge":"43200s",
  "issuer": "https://accounts.google.com/o/saml2?idpid=C03xolm0y",
  "ssoUrl": "https://accounts.google.com/o/saml2/idp?idpid=C03xolm0y",
  "ssoBinding": "POST"
}

    Where:

    • folderId: ID of the folder.

    • name: Federation name. The name must be unique within the folder.

    • autocreateUsers: Flag for automatically creating new users in the cloud after authenticating on the IdP server. This option simplifies the user setup, but users created this way are only assigned the resource-manager.clouds.member role by default: they can't do anything with cloud resources. Exceptions are the resources that the allUsers or allAuthenticatedUsers system group roles are assigned to.

      If this option is disabled, users who aren't added to the cloud can't log in to the management console, even if they authenticate with your server. In this case, you can manage the white list of users who are allowed to use Yandex.Cloud.

    • cookieMaxAge: Time before the browser asks the user to re-authenticate.

    • issuer: IdP server ID to be used for authentication.

      Copy here the link from the Entity ID field of the G Suite Google IdP Information page. This is a link in the format:

      https://accounts.google.com/o/saml2?idpid=<SAML app ID>

    • ssoUrl: URL of the page that the browser redirects the user to for authentication.

      Copy here the link from the SSO URL field of the G Suite Google IdP Information page. This is a link in the format:

      https://accounts.google.com/o/saml2/idp?idpid=<SAML app ID>

    • ssoBinding: Specify the Single Sign-on binding type. Most Identity Providers support the POST binding type.

  3. Create a federation using the create method:

    $ curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <IAM token>" \
  -d '@body.json' \
  https://iam.api.cloud.yandex.net/iam/v1/saml/federations
{
 "done": true,
 "metadata": {
  "@type": "type.googleapis.com/yandex.cloud.iam.v1.saml.CreateFederationMetadata",
  "federationId": "ajeobmje4dgj0belagb9"
 },
 ...

    The federationId property of the response contains the federation ID to save. You'll need this ID in the next steps.

Specify certificates for the identity federation

When the Identity Provider (IdP) informs Yandex.Cloud that a user passed authentication, they sign the message with their certificate. To enable Yandex.Cloud to verify this certificate, add it to the federation in IAM.

Tip

To ensure that authentication isn't interrupted when the certificate expires, we recommend adding several certificates to the federation: the current one and the ones that will be used after. If a certificate is invalid, Yandex.Cloud tries to verify the signature with a different one.

Download the certificate from the Google IdP Information page open in G Suite. Add this certificate to the federation created.

To add a certificate to a federation:

  1. Open the folder page in the management console.
  2. Select the Federations tab in the left menu.
  3. Click the name of the federation you want to add a certificate to.
  4. Click Add certificate at the bottom of the page.
  5. Choose how to add the 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.

If you don't have the Yandex.Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

  1. View a description of the add certificate command:

    $ yc iam certificate create --help

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

    $ yc iam certificate create --federation-name my-federation \
  --name "my-certificate" \
  --certificate-file test.pem

To add the certificate, use the create method for the Certificate resource:

  1. Create a request body by specifying the contents of the certificate's data property:

    {
  "federationId": "<federation ID>",
  "name": "my-certificate",
  "data": "MII...=="
}

  2. Send the add certificate request:

    $ export IAM_TOKEN=CggaATEVAgA...
$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${IAM_TOKEN}" \
    -d '@body.json' \
    "https://iam.api.cloud.yandex.net/iam/v1/saml/certificates"

When you set up federation authentication, users can log in to the management console from a link containing the federation ID. You must specify the same link when configuring the authentication server.

Obtain and save this link:

  1. Get the federation ID:

    1. Open the folder page in the management console.
    2. Select the Federations tab in the left menu.
    3. Copy the ID of the federation you're configuring access for.

  2. Generate a link using this ID:

    https://console.cloud.yandex.com/federations/<federation ID>

Finish creating your SAML app

Having created a federation and obtained a console login link, finish creating the SAML app in G Suite:

  1. Re-open the SAML app creation window and click Next.

  2. Enter a name for your SAML app, like yandex-cloud-federation. Add a description and upload a logo if necessary. Click Next.

  3. Enter information about Yandex.Cloud that acts as a Service Provider (SP):

    • In the ACS URL and Entity ID fields, enter the previously obtained console login link.

    • Enable Signed Response.

    • In the Name ID field, specify what the server will return as Name ID (the unique ID of the identity federation user).

      Select Basic Information and Primary Email next to it.

    • The other fields are optional, so you can skip them and click Next.

    image

  4. For the user to contact Yandex.Cloud technical support from the management console, click Add new mappings and configure the server to pass the user's email address. We also recommend that it passes the user's first and last name. Then click Finish.

    image

  5. On the next page, you can check the data entered for your SAML app.

  6. Enable your SAML app by clicking Edit service.

  7. 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.

Add users to the cloud

If you enabled the Automatically create users option when creating an identity federation, this step is optional. If you didn't enable it, you must add users to the cloud manually.

To add identity federation users to the cloud:

  1. Open the Access management page for the selected cloud. If necessary, switch to another cloud.

  2. Click the arrow next to the Add user button.
  3. Select Add federated users.
  4. Select the identity federation to add users from.
  5. List the Name IDs of users, separating them with line breaks.

If you don't have the Yandex.Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

  1. View a description of the add user command:

    $ yc iam federation add-user-accounts --help

  2. Add users by listing their Name IDs separated by a comma:

    $ yc iam federation add-user-accounts --name my-federation \
  --name-ids=alice@example.com,bob@example.com,charlie@example.com

To add identity federation users to the cloud:

  1. Create a file with the request body (for example, body.json). In the request body, specify the array of Name IDs of users you want to add:

    {
  "nameIds": [
    "alice@example.com",
    "bob@example.com",
    "charlie@example.com"
  ]
}

  2. Send the request by specifying the Federation ID in the parameters:

    $ curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <IAM token>" \
  -d '@body.json' \
  https://iam.api.cloud.yandex.net/iam/v1/saml/federations/<federation ID>:addUserAccounts

Test the authentication process

When you finish configuring the server, you can test that everything is up and running:

  1. Open the browser in guest or incognito mode to protect your work done in the console from your Yandex account.
  2. Follow the console login link obtained earlier. The browser forwards you to the Google authentication page.
  3. Enter your authentication data. By default, enter your UPN and password. After that, click Sign in.
  4. If the authentication is successful, the server redirects you back to the console login link and then to the management console home page. In the upper-right corner, you can see that you are logged in to the console as a federated user.

What's next

In this article: