Authentication using Microsoft Entra ID

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.

1. View the description of the create federation command:

   yc organization-manager federation saml create --help
   

2. 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://sts.windows.net/<SAML_app_ID>/" \
       --sso-url "https://login.microsoftonline.com/<SAML_app_ID>/saml2" \
       --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 to enable 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.

     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 IdP 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 from the Microsoft Entra ID field on the SAML-based sign-on page in Entra ID. The link should have the following format:

     https://sts.windows.net/<SAML_app_ID>/
     

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

     Use the link from the Login URL field on the SAML-based sign-on page in Entra ID. The link should have the following format:

     https://login.microsoftonline.com/<SAML_app_ID>/saml2
     

     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.

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

1. 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 Microsoft Entra ID field on the SAML-based sign-on page in Entra ID. The link should have the following format:

     https://sts.windows.net/<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 redirects the user to for authentication.

     Use the link from the Login URL field on the SAML-based sign-on page in Entra ID. The link should have the following format:

     https://login.microsoftonline.com/<SAML_app_ID>/saml2
     

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

     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: Flag that indicates whether usernames are case-insensitive.
     If the option is enabled, the IDs of federated user names will be case-insensitive.

   • security_settings: Federation security settings:

     • encrypted_assertions: For signing authentication requests.
       If this option is enabled, all authentication requests 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://sts.windows.net/<SAML_app_ID>/"
    sso_url         = "https://login.microsoftonline.com/<SAML_app_ID>/saml2"
    sso_binding     = "POST"
    security_settings {
       encrypted_assertions = "true"
       }
   }
   

2. Make sure the configuration files are correct.

   1. In the command line, go to the folder where you created the configuration file.

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

3. Create a federation.

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

      terraform apply
      

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

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

   {
     "name": "my-federation",
     "organizationId": "<organization_ID>",
     "autoCreateAccountOnLogin": true,
     "cookieMaxAge":"43200s",
     "issuer": "https://sts.windows.net/<SAML_app_ID>/",
     "ssoUrl": "https://login.microsoftonline.com/<SAML_app_ID>/saml2",
     "ssoBinding": "POST",
     "securitySettings": {
       "forceAuthn": true
     }
   }
   

   Where:

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

   • organizationId: Organization ID.

   • autoCreateAccountOnLogin: Flag to enable 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.

     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 IdP 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 Microsoft Entra ID field on the SAML-based sign-on page in Entra ID. The link should have the following format:

     https://sts.windows.net/<SAML_app_ID>/
     

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

     Use the link from the Login URL field on the SAML-based sign-on page in Entra ID. The link should have the following format:

     https://login.microsoftonline.com/<SAML_app_ID>/saml2
     

     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 user re-authentication once a session expires in Yandex Cloud.

2. 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 request parameters in your request.

   Sample request:

   curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <IAM_token>" \
     -d '@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; make sure to save it, you will need it later.

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.

1. View a description of the add certificate command:

   yc organization-manager federation saml certificate create --help
   

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

Use the create method for the Certificate resource:

1. Generate the request body. In the data property, specify the contents of the certificate:

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

2. Send the add certificate request:

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

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.

1. View a description of the add user command:

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

2. 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: User name IDs.

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:

   {
     "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://organization-manager.api.cloud.yandex.net/organization-manager/v1/saml/federations/<federation_ID>:addUserAccounts