Authentication using Google Workspace
With an identity federation, you can use Google Workspace
Authentication setup includes the following steps:
-
Creating and setting up a SAML application in Google Workspace.
-
Creating and setting up a federation in Yandex Cloud Organization.
Getting started
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
Create a SAML application and download a certificate
A SAML application in Google Workspace acts as an identity provider (IdP). Create a SAML application and download a certificate:
-
Open the Google Workspace Admin Console
. -
In the left-hand panel, select Mobile and web applications.
-
Click Add → Add a custom SAML app.
-
Enter the name of the app, select the logo, and click Continue.
-
In the Google IdP information step, the IdP server data is shown. You will need this data when setting up a federation in Yandex Cloud Organization.
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.
Creating and setting up a federation in Yandex Cloud Organization
Create a federation
To create a federation:
-
Go to Yandex Cloud Organization
. -
In the left-hand panel, select
Federations. -
Click
Create federation in the top-right corner of the page. In the window that opens:-
Give your federation a name. It must be unique within the folder.
-
You can also add a description, if required.
-
In the Cookie lifetime field, specify the time before the browser asks the user to re-authenticate.
-
In the IdP Issuer field, enter the link from the Object ID field on the Google Workspace Google IdP information page. The link should have the following format:
https://accounts.google.com/o/saml2?idpid=<SAML_app_ID>
-
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:
https://accounts.google.com/o/saml2/idp?idpid=<SAML_app_ID>
You can only use HTTP and HTTPS in a link.
-
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 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.
-
Enable Mandatory re-authentication (ForceAuthn) in IdP to set
true
for the ForceAuthn parameter in a SAML authentication request. If enabled, the IdP will request the user to re-authenticate once the Yandex Cloud session expires. -
Click Create federation.
-
If you do not 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.
-
View the description of the create federation command:
yc organization-manager federation saml create --help
-
Create a federation:
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. -
--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 theAll users
orAll authenticated users
public group.If this option is disabled, users who are not added to the organization cannot log in to the management console, even if they authenticate with 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:
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:
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 thePOST
binding type. -
(Optional)
force-authn
: When the session in Yandex Cloud expires, the identity provider will ask the user to re-authenticate.
-
If you don't have Terraform, install it and configure the Yandex Cloud provider.
-
Specify the federation parameters in the configuration file:
-
name
: Federation name. It must be unique within the folder. -
description
: Federation description. -
organization_id
: Organization ID. -
labels
: Set of key/value label pairs assigned to the federation. -
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:
https://accounts.google.com/o/saml2?idpid=<SAML_app_ID>
-
sso_binding
: Specify the single sign-on binding type. Most identity providers support thePOST
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:
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 is8 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 theAll users
orAll authenticated users
public group.If this option is disabled, users who are not added to the organization cannot log in to the management console, even if they authenticate with 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
: For signing authentication queries.
If this option is enabled, all authentication queries from Yandex Cloud will have a digital signature. You will need to download and install a Yandex Cloud certificate.
Here is an example of the configuration file structure:
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" } }
-
-
Make sure the configuration files are correct.
-
In the command line, go to the folder where you created the configuration file.
-
Run a check using this command:
$ terraform plan
If the configuration is described correctly, the terminal displays the federation parameters. If the configuration contains any errors, Terraform will point them out.
-
-
Create a federation.
-
If the configuration does not contain any errors, run this command:
$ terraform apply
-
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
section. -
-
Create a file with the request body, e.g.,
body.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. -
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 theAll users
orAll authenticated users
public group.If this option is disabled, users who are not added to the organization cannot log in to the management console, even if they authenticate with 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:
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:
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 thePOST
binding type. -
forceAuthn
: Parameter that requires user re-authentication once a session expires in Yandex Cloud.
-
-
To create a federation, use the create REST API method for the Federation resource or the FederationService/Create gRPC API call and provide a file with the query parameters in your query.
Query example:
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:
{ "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.
Add certificates
While authenticating, the Cloud Organization 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:
-
Log in to Yandex Cloud Organization
. -
In the left-hand panel, select
Federations. -
Click the row with the federation you want to add a certificate to.
-
Click Adding a certificate under Certificates at the bottom of the page.
-
Enter certificate name and description.
-
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.
-
Click Add.
If you do not 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.
-
View a description of the add certificate command:
yc organization-manager federation saml certificate create --help
-
Add a federation certificate by specifying the certificate file path:
yc organization-manager federation saml certificate create --federation-id <federation_ID> \ --name "my-certificate" \ --certificate-file certificate.pem
Use the create method for the Certificate resource:
-
Generate the query body. In the
data
property, specify the contents of the certificate:{ "federationId": "<federation_ID>", "name": "my-certificate", "data": "-----BEGIN CERTIFICATE..." }
-
Send the add certificate query:
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"
Tip
To make sure authentication is not interrupted when the certificate expires, we recommend adding multiple certificates to your federation, i.e., the current one and those to use afterwards. If one certificate goes invalid, Yandex Cloud will try another one to verify the signature.
Setting up single sign-on (SSO)
Specify the redirect URL
Once you have created a federation, complete the creation of the SAML application in Google Workspace:
-
Go back to the SAML app creation page's Google IdP information step and click Continue.
-
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:
https://console.cloud.yandex.ru/federations/<federation_ID>
How to get a federation ID
-
Log in to Yandex Cloud Organization
. -
In the left-hand panel, select
Federations. -
Select the required federation and copy the Identifier field value on the federation info page.
How to get the federation ACS URL
-
Log in to Yandex Cloud Organization
. -
In the left-hand panel, select
Federations. -
Select the required federation and copy the ACS URL field value on the federation info page.
-
-
Enable Signed Response.
-
-
Click Continue.
Tip
To enable the user to contact Yandex Cloud technical support from the management console
, 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 Yandex Cloud Organization services are listed in Mapping user attributes.
-
To complete the creation of the app, click Ready.
Add users
-
On the app page, under User access, click Disabled for everyone.
-
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.
-
-
Click Save.
Mapping user attributes
User data | Comment | Application Attributes |
---|---|---|
Unique user ID | Required attribute. Using an email address is recommended. | Name ID field in service provider settings |
Last name | Displayed in Yandex Cloud services. Value length limit: 64 characters. |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname |
Name | Displayed in Yandex Cloud services. Value length limit: 64 characters. |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname |
Full name | Displayed in Yandex Cloud services. Example: Ivan Ivanov. Value length limit: 64 characters. |
Attribute unavailable |
Used to send notifications from Yandex Cloud services. Example: ivanov@example.com .Value length limit: 256 characters. |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress |
|
Phone | Used to send notifications from Yandex Cloud services. Example: +71234567890. Value length limit: 64 characters. |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mobilephone |
Profile image | Displayed in Yandex Cloud services. Value length limit: 204800 characters. |
Attribute unavailable |
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.
Attribute mapping example:
Add users to your organization
If you did not enable the Automatically create users option when creating the federation, 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 removed, 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 roles to a user, see Roles.
-
Go to Yandex Cloud Organization
. -
In the left-hand panel, select
Users. -
In the top-right corner, click More
and select Add federated users. -
Select the identity federation to add users from.
-
List the name IDs of users, separating them with spaces or line breaks.
-
Click Add. This will give the users access to the organization.
If you do not 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.
-
View a description of the add user command:
yc organization-manager federation saml add-user-accounts --help
-
Add users by listing their name IDs separated by a comma:
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.
-
To add identity federation users to the cloud:
-
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:{ "nameIds": [ "alice@example.com", "bob@example.com", "charlie@example.com" ] }
-
Send the request by specifying the Federation ID in the parameters:
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
Authentication
When you finish configuring the server, test that everything works properly:
-
Open your browser in guest or private browsing mode.
-
Use this URL to log in to the management console:
https://console.yandex.cloud/federations/<federation_ID>
How to get a federation ID
-
Log in to Yandex Cloud Organization
. -
In the left-hand panel, select
Federations. -
Select the required federation and copy the Identifier field value on the federation info page.
The browser will forward you to the Google authentication page.
-
-
Enter your credentials and click Sign in.
On successful authentication, the IdP server will redirect you back to the ACS URL that you specified in the Google Workspace settings, and then, to the management console