Assigning a role to a service account

Written by

Yandex Cloud

Improved by

ilya

Updated at September 23, 2026

View in Markdown

Assigning a role for a resource
Assigning a role for an organization

This section describes how to assign a role for a resource to a service account. To learn how to assign a role for a service account as a resource to another user, see Setting up service account access permissions.

You can assign roles to a service account for any resources in any cloud if these resources belong to the same organization as the service account. You can also assign roles for the entire organization.

Assigning a role for a resource

Child resources inherit access permissions from their parent resources. For example, if a service account gets a role for a cloud, it will also get the required permissions for all resources across the cloud's folders.

To assign a role for a resource, you need the admin or service-name.admin role, where service-name is the name of the service to which the resource belongs.

Learn which resources you can assign a role for.

To assign a role for a resource:

Management console

CLI

Terraform

API

Roles are assigned to a service account the same way as to a user account.

To assign a role for a cloud or folder to a service account:

In the management console, click or in the top panel and select the cloud or folder.
Navigate to the Access bindings tab.
Click Configure access.
In the window that opens, select Service accounts.
Select the service account from the list or use the search bar.
Click Add role and select the role from the list or use the search bar.
Click Save.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder used by default is the one specified when creating 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.

To assign a role for a cloud or folder to a service account, run this command:

yc resource-manager <resource_category> add-access-binding <resource_name_or_ID> \
  --role <role_ID> \
  --service-account-id <service_account_ID>

Where:

<resource_category>: cloud to assign a role for a cloud or folder to assign a role for a folder.
<resource_name_or_ID>: Name or ID of the resource to assign the role for.
--role: Role ID, e.g., viewer.
--service-account-id: ID of the service account you are assigning the role to.

For example, to assign a role for a folder to a service account:

Select a role to assign to the service account. For role descriptions, see the Yandex Cloud role reference in the Yandex Identity and Access Management documentation.

Get the ID of the service account by its name:

yc iam service-account get <service_account_name>

Result:

id: aje6o61dvog2********
folder_id: b1gvmob95yys********
created_at: "2018-10-15T18:01:25Z"
name: my-robot

If you do not know the name of your service account, get a list of service accounts with their IDs:

yc iam service-account list

Result:

+----------------------+------------------+-----------------+
|          ID          |       NAME       |   DESCRIPTION   |
+----------------------+------------------+-----------------+
| aje6o61dvog2******** | my-robot         | my description  |
+----------------------+------------------+-----------------+

Assign the role to the service account using its ID:
```
yc resource-manager folder add-access-binding <folder_name_or_ID> \
  --role <role> \
  --service-account-id <service_account_ID>
```
Where:
- --role: ID of the role to assign.
- --service-account-id: Service account ID. You can also use the --service-account-name parameter and specify the username instead of the ID.

If you do not have Terraform yet, install it and configure the Yandex Cloud provider.

To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), authenticate using the appropriate method.

In the configuration file, describe the resources you want to create:

Here is an example of the configuration file structure for assigning a role for a folder:

resource "yandex_resourcemanager_folder_iam_member" "admin-account-iam" {
  folder_id   = "<folder_ID>"
  role        = "<role>"
  member      = "serviceAccount:<service_account_ID>"
}

Where:

folder_id: Folder ID. This is a required setting.
role: Role. For role descriptions, see the Yandex Cloud role reference in the Yandex Identity and Access Management documentation. This is a required setting.

member: Subject getting the role. For a service account, specify serviceAccount:<service_account_ID>.

Subject designations

To indicate a subject, use a combination of its type and unique ID, i.e., <subject_type>:<ID>. Here is how you can designate a subject:

Subject type	Subject designation
`userAccount`	`userAccount:<user_ID>`
`serviceAccount`	`serviceAccount:<service_account_ID>`
`federatedUser`	`federatedUser:<user_ID>`
`group`	`group:<group_ID>`
`system`	`system:allAuthenticatedUsers` (`All authenticated users` group)
	`system:allUsers` (`All users` group)
	`system:group:organization:<organization_ID>:users` (`All users in organization X` group)
	`system:group:federation:<federation_ID>:users` (`All users in federation N` group)
	`system:group:userpool:<pool_ID>:users` (`All users in userpool P` group)

For more information about the resources you can create with Terraform, see this provider guide.

Create the resources:
1. In the terminal, navigate to the configuration file directory.
2. Make sure the configuration is correct using this command:
```
terraform validate
```
  If the configuration is valid, you will get this message:
```
Success! The configuration is valid.
```
3. Run this command:
```
terraform plan
```
  You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
4. Apply the configuration changes:
```
terraform apply
```
5. Type yes and press Enter to confirm the changes.
This will assign access permissions for the folder. You can check the role assignment using the management console or this CLI command:
```
yc resource-manager folder list-access-bindings <folder_name_or_ID>
```

To assign a role for a cloud or folder to a service account, use the updateAccessBindings REST API method for the Cloud or Folder resource:

Select a role to assign to the service account. For role descriptions, see the Yandex Cloud role reference in the Yandex Identity and Access Management documentation.
Get the ID of the folder with service accounts.
Get an IAM token for authentication in the Yandex Cloud API.

Get a list of service accounts in the folder to find out their IDs:

export FOLDER_ID=<folder_ID>
export IAM_TOKEN=<IAM_token>
curl \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  "https://iam.api.cloud.yandex.net/iam/v1/serviceAccounts?folderId=${FOLDER_ID}"

Result:

{
 "serviceAccounts": [
  {
   "id": "ajebqtreob2d********",
   "folderId": "b1gvmob95yys********",
   "createdAt": "2018-10-18T13:42:40Z",
   "name": "my-robot",
   "description": "my description"
  }
 ]
}

Create a request body, e.g., in the body.json file. Specify ADD in the action property:

{
  "accessBindingDeltas": [{
    "action": "ADD",
    "accessBinding": {
      "roleId": "<role>",
      "subject": {
        "id": "<service_account_ID>",
        "type": "serviceAccount"
      }
    }
  }]
}

Where:

roleId: Role.

subject: Subject getting the role.

Subject designations

To indicate a subject, use a combination of its type and unique ID in the subject.type and subject.id fields of the request. Here are possible combinations:

subject.type	subject.id
`userAccount`	`<user_ID>`
`serviceAccount`	`<service_account_ID>`
`federatedUser`	`<user_ID>`
`group`	`<group_ID>`
`system`	`allAuthenticatedUsers` (`All authenticated users` group)
	`allUsers` (`All users` group)
	`group:organization:<organization_ID>:users` (`All users in organization X` group)
	`group:federation:<federation_ID>:users` (`All users in federation N` group)
	`group:userpool:<pool_ID>:users` (`All users in userpool P` group)

Assign a role to a service account, e.g., for the folder with the b1gvmob95yys******** ID:

export FOLDER_ID=b1gvmob95yys********
export IAM_TOKEN=CggaAT********
curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --data '@body.json' \
  "https://resource-manager.api.cloud.yandex.net/resource-manager/v1/folders/${FOLDER_ID}:updateAccessBindings"

Assigning a role for an organization

All resources created within an organization inherit access permissions assigned to that organization. For example, if a service account gets a role for an organization, it will also get the required permissions for all resources across the organization's clouds.

To grant organization access permissions to a service account, you need the organization-manager.admin role or higher.

Cloud Center UI

CLI

Terraform

API

Log in to Yandex Identity Hub using an administrator or organization owner account.
In the left-hand panel, select Access bindings.
In the Account type filter, select Service accounts.
If the service account you need already has at least one role assigned, click in the row with that service account and select Assign roles.

If the service account is not on the list, click Assign roles in the top-right corner. In the window that opens, go to Service accounts and select the account from the list or use the search bar to locate it.
Click Add role and select a role to assign to the service account. You can assign multiple roles.

For descriptions of available roles, see the Yandex Cloud role reference in the Yandex Identity and Access Management documentation.
Click Save.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

To assign a role for an organization to a service account, run this command:

yc organization-manager organization add-access-binding <organization_name_or_ID> \
  --role <role_ID> \
  --service-account-id <service_account_ID>

Where:

<organization_name_or_ID>: Technical name or ID of the organization.
--role: Role ID, e.g., viewer.
--service-account-id: ID of the service account you are assigning the role to.

For example, to assign the viewer role for the MyOrg organization to a service account:

Select a role to assign to the service account. For role descriptions, see the Yandex Cloud role reference in the Yandex Identity and Access Management documentation.

Get a list of available organizations to find out their IDs and technical names:

yc organization-manager organization list

Result:

+---------------------------------+---------------------------------+----------------------+
|               ID                |              NAME               |        TITLE         |
+---------------------------------+---------------------------------+----------------------+
| bpf1smsil5q0********            | hdt5j5uw********                | MyOrg                |
+---------------------------------+---------------------------------+----------------------+

The organization's technical name is in the NAME column, and its ID, in the ID column.

Get the ID of the service account by its name:

yc iam service-account get my-robot

Result:

id: aje6o61dvog2********
folder_id: b1gvmob95yys********
created_at: "2018-10-15T18:01:25Z"
name: my-robot

If you do not know the name of your service account, get a full list of service accounts with their IDs:

yc iam service-account list

Result:

+----------------------+------------------+-----------------+
|          ID          |       NAME       |   DESCRIPTION   |
+----------------------+------------------+-----------------+
| aje6o61dvog2******** | my-robot         | my description  |
+----------------------+------------------+-----------------+

Assign the my-robot service account the viewer role for the organization with the bpf1smsil5q0******** ID:

yc organization-manager organization add-access-binding bpf1smsil5q0******** \
  --role viewer \
  --service-account-id aje6o61dvog2********

If you do not have Terraform yet, install it and configure the Yandex Cloud provider.

To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), authenticate using the appropriate method.

In the configuration file, describe the resources you want to create:

Here is an example of the configuration file structure:
```
resource "yandex_organizationmanager_organization_iam_binding" "editor" {
  organization_id   = "<organization_ID>"
  role              = "<role>"
  members           = ["serviceAccount:<service_account_ID>",]
}
```
Where:
- organization_id: Organization ID. This is a required setting.
- role: Role. For role descriptions, see the Yandex Cloud role reference in the Yandex Identity and Access Management documentation. For each role, you can only use one yandex_organizationmanager_organization_iam_binding resource. This is a required setting.
- members: List of subjects getting the role. This is a required setting.
For more on the properties of the yandex_organizationmanager_organization_iam_binding resource, see this provider guide.
Make sure the settings are correct.
1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
2. Run this command:
```
terraform validate
```
  Terraform will show any errors found in your configuration files.
Assign the role.
1. Run this command to view the planned changes:
```
terraform plan
```
  If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
2. If everything looks correct, apply the changes:
  1. Run this command:
```
terraform apply
```
  2. Confirm updating the resources.
  3. Wait for the operation to complete.
This will assign access permissions for the organization. You can check the role assignment using the management console or this CLI command:
```
yc organization-manager organization list-access-bindings <organization_name_or_ID>
```

To assign a role for an organization to a service account, use the updateAccessBindings REST API method for the Organization resource or the OrganizationService/UpdateAccessBindings gRPC API call:

Select a role to assign to the service account. For role descriptions, see the Yandex Cloud role reference in the Yandex Identity and Access Management documentation.
Get the ID of the folder with service accounts.
Get an IAM token for authentication in the Yandex Cloud API.

Get a list of service accounts in the folder to find out their IDs:

export FOLDER_ID=<folder_ID>
export IAM_TOKEN=<IAM_token>
curl \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  "https://iam.api.cloud.yandex.net/iam/v1/serviceAccounts?folderId=${FOLDER_ID}"

Result:

{
 "serviceAccounts": [
  {
   "id": "ajebqtreob2d********",
   "folderId": "b1gvmob95yys********",
   "createdAt": "2018-10-18T13:42:40Z",
   "name": "my-robot",
   "description": "my description"
  }
 ]
}

Get a list of organizations to find out their IDs:

export IAM_TOKEN=<IAM_token>
curl \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --request GET \
  "https://organization-manager.api.cloud.yandex.net/organization-manager/v1/organizations"

Result:

{
 "organizations": [
  {
   "id": "bpfaidqca8vd********",
   "createdAt": "2023-04-07T08:11:54.313033Z",
   "name": "xvdq9q22********",
   "title": "MyOrg"
  }
 ]
}

Create a request body, e.g., in the body.json file. Specify ADD in the action property:

body.json:

{
  "accessBindingDeltas": [{
    "action": "ADD",
    "accessBinding": {
      "roleId": "<role>",
      "subject": {
        "id": "<service_account_ID>",
        "type": "serviceAccount"
      }
    }
  }]
}

Where:

roleId: Role.

subject: Subject getting the role.

Subject designations

To indicate a subject, use a combination of its type and unique ID in the subject.type and subject.id fields of the request. Here are possible combinations:

subject.type	subject.id
`userAccount`	`<user_ID>`
`serviceAccount`	`<service_account_ID>`
`federatedUser`	`<user_ID>`
`group`	`<group_ID>`
`system`	`allAuthenticatedUsers` (`All authenticated users` group)
	`allUsers` (`All users` group)
	`group:organization:<organization_ID>:users` (`All users in organization X` group)
	`group:federation:<federation_ID>:users` (`All users in federation N` group)
	`group:userpool:<pool_ID>:users` (`All users in userpool P` group)

Assign the role to the service account:

export ORGANIZATION_ID=<organization_ID>
export IAM_TOKEN=<IAM_token>
curl \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --data '@body.json' \
  --request POST \
  "https://organization-manager.api.cloud.yandex.net/organization-manager/v1/organizations/${ORGANIZATION_ID}:updateAccessBindings"

Assigning a role to a service account

Assigning a role for a resource

Assigning a role for an organization

What's next

Was the article helpful?

Assigning a role to a service account

Assigning a role for a resourceAssigning a role for a resource

Assigning a role for an organizationAssigning a role for an organization

What's nextWhat's next

Was the article helpful?

Assigning a role for a resource

Assigning a role for an organization

What's next