Administra el acceso a las cuentas de servicio

En esta página, se describe cómo otorgar, cambiar y revocar el acceso de una principal a una sola cuenta de servicio. Para administrar el acceso de una principal a todas las cuentas de servicio en un proyecto, organización o carpeta, administra su acceso a nivel de proyecto, organización o carpeta.

En Identity and Access Management (IAM), el acceso se administra a través de políticas de permisos, también conocidas como políticas de IAM. Una política de permisos se adjunta a un recurso de Google Cloud. Cada política de permisos contiene una colección de vinculaciones de roles que asocian una o más principales, como usuarios o cuentas de servicio, a un rol de IAM. Estas vinculaciones de roles otorgan los roles especificados a las principales, tanto en el recurso al que se adjunta la política de permisos como en todos los elementos subordinados de ese recurso. Para obtener más información sobre las políticas de permisos, consulta Comprende las políticas de permisos.

Las cuentas de servicio son recursos a los que otras cuentas principales pueden tener acceso y principales a las que se les puede otorgar acceso a otros recursos. En esta página, las cuentas de servicio se tratan como recursos y se describe cómo otorgar a otras cuentas principales acceso a ellas. Para obtener información sobre cómo otorgar a una cuenta de servicio acceso a otros recursos, consulta las siguientes guías:

Para otorgar a una cuenta de servicio acceso a un proyecto, organización o carpeta, consulta Administra el acceso a proyectos, carpetas y organizaciones.
Para otorgar a una cuenta de servicio acceso a otros recursos, consulta Administra el acceso a otros recursos.

En esta página, se describe cómo administrar el acceso a las cuentas de servicio con la consola de Google Cloud, Google Cloud CLI y la API de REST. También puedes administrar el acceso mediante las bibliotecas cliente de IAM.

Antes de comenzar

Enable the IAM API.
Enable the API
Obtén más información sobre las cuentas de servicio.

Roles obligatorios

Si deseas obtener los permisos que necesitas para administrar el acceso a una cuenta de servicio, pídele a tu administrador que te otorgue el rol de IAM de Administrador de cuenta de servicio (roles/iam.serviceAccountAdmin) en esta cuenta o el proyecto que posee la cuenta de servicio. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para administrar el acceso a una cuenta de servicio. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Los siguientes permisos son necesarios para administrar el acceso a una cuenta de servicio:

iam.serviceAccounts.get
iam.serviceAccounts.list
iam.serviceAccounts.getIamPolicy
iam.serviceAccounts.setIamPolicy

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Visualiza el acceso actual

En la siguiente sección, se muestra cómo usar la consola de Google Cloud, la CLI de gcloud y la API de REST para ver quién tiene acceso a una cuenta de servicio. También puedes ver el acceso mediante las bibliotecas cliente de IAM para obtener la política de permisos de la cuenta de servicio.

Console

En la consola de Google Cloud, ve a la página Cuentas de servicio.

Ir a Cuentas de servicio
Selecciona un proyecto
Haz clic en la dirección de correo electrónico de la cuenta de servicio.
Ve a la pestaña Permisos. En la sección Principales con acceso a esta cuenta de servicio, se enumeran todas las principales a las que se les otorgó una función en la cuenta de servicio.

En esta lista, se incluyen las principales cuyo acceso proviene de las funciones que se otorgan en los recursos superiores. Para obtener más información sobre la herencia de políticas, consulta La herencia de políticas y la jerarquía de recursos.
Opcional: Para ver las asignaciones de roles de los agentes de servicio, selecciona la casilla de verificación Incluir asignaciones de roles proporcionadas por Google.

gcloud

A fin de ver quién tiene acceso a tu cuenta de servicio, obtén la política de permisos para la cuenta de servicio. Para obtener información sobre cómo interpretar las políticas de permisos, consulta Comprende las políticas de permisos.

A fin de obtener la política de permisos para la cuenta de servicio, ejecuta el comando get-iam-policy de la cuenta de servicio:

gcloud iam service-accounts get-iam-policy SA_ID --format=FORMAT > PATH

Ingresa los siguientes valores:

SA_ID: El ID de la cuenta de servicio. Puede ser la dirección de correo electrónico de la cuenta de servicio con el formato SA_NAME@PROJECT_ID.iam.gserviceaccount.com o el ID numérico único de la cuenta de servicio.

Nota: Si deseas identificar una cuenta de servicio justo después de crearla, usa el ID numérico en lugar de la dirección de correo electrónico para asegurarte de que se identifique de manera confiable.
FORMAT: Es el formato de la política. Usa json o yaml
PATH: Es la ruta a un nuevo archivo de salida de la política.

Por ejemplo, con el siguiente comando, se obtiene la política para la cuenta de servicio my-service-account y se guarda en tu directorio principal en formato JSON:

gcloud iam service-accounts get-iam-policy my-service-account --format json > ~/policy.json

REST

El método serviceAccounts.getIamPolicy obtiene la política de permisos de una cuenta de servicio.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

PROJECT_ID: El ID del proyecto de Google Cloud Los ID de proyecto son strings alfanuméricas, como my-project.
SA_ID: El ID de la cuenta de servicio. Puede ser la dirección de correo electrónico de la cuenta de servicio con el formato SA_NAME@PROJECT_ID.iam.gserviceaccount.com o el ID numérico único de la cuenta de servicio.

Nota: Para identificar una cuenta de servicio justo después de su creación, usa el ID numérico en lugar de la dirección de correo electrónico.
POLICY_VERSION: Es la versión de la política que se mostrará. Las solicitudes deben especificar la versión de política más reciente, que es la versión de política 3. Consulta Especifica una versión de política cuando obtienes una política para obtener más detalles.

Método HTTP y URL:

POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID:getIamPolicy

Cuerpo JSON de la solicitud:

{
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID:getIamPolicy"

PowerShell (Windows)

Nota: El siguiente comando supone que accediste a la CLI de gcloud con tu cuenta de usuario mediante la ejecución de gcloud init o gcloud auth login. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID:getIamPolicy" | Select-Object -Expand Content

Explorador de APIs (navegador)

Copia el cuerpo de la solicitud y abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Pega el cuerpo de la solicitud en esta herramienta, completa cualquier otro campo obligatorio y haz clic en Ejecutar.

La respuesta contiene la política de permisos de la cuenta de servicio. Por ejemplo:

{
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

Otorga o revoca un solo rol

Puedes usar la consola de Google Cloud y gcloud CLI a fin de otorgar o revocar con rapidez un solo rol para una sola principal, sin editar directamente la política de permisos de la cuenta de servicio. Los tipos comunes de principales incluyen Cuentas de Google, cuentas de servicio, Grupos de Google y dominios. Para obtener una lista de todos los tipos de principales, consulta Conceptos relacionados con la identidad.

En general, los cambios en las políticas entran en vigor en un plazo de 2 minutos. Sin embargo, en algunos casos, pueden tardar 7 minutos o más en propagarse por todo el sistema.

Si necesitas ayuda para identificar el rol predefinido más adecuado, consulta Elige funciones predefinidas.

Otorga una sola función

Para otorgar una sola función a una principal, sigue estos pasos:

Console

En la consola de Google Cloud, ve a la página Cuentas de servicio.

Ir a Cuentas de servicio
Selecciona un proyecto
Haz clic en la dirección de correo electrónico de la cuenta de servicio.
Ve a la pestaña Permisos y busca la sección Principales con acceso a esta cuenta de servicio.
Selecciona una principal para otorgarle una función:
- Para otorgar un rol a una principal que ya tenga otros roles en la cuenta de servicio, busca una fila que contenga la principal y haz clic en Editar principal en ella y, luego, haz clic en Agregar otro rol.
  
  Para otorgar un rol a un agente de servicio, selecciona la casilla de verificación Incluir asignaciones de roles proporcionadas por Google para ver su dirección de correo electrónico.
  
  Nota: No puedes editar las funciones heredadas cuando administras el acceso a las cuentas de servicio. Para editar las funciones heredadas, ve al recurso en el que se otorgó la función.
- Para otorgar un rol a una principal que aún no tenga otros roles en el recurso, haz clic en Otorgar acceso y, luego, ingresa la dirección de correo electrónico de la principal o algún otro identificador.
Selecciona una función para otorgar de la lista desplegable. Para una mejor seguridad, elige una función que incluya solo los permisos que necesita tu principal.
Opcional: Agrega una condición a la función.
Haz clic en Guardar. La función se otorgó a la principal en la cuenta de servicio.

gcloud

Para otorgarle una función a una principal con rapidez, ejecuta el comando add-iam-policy-binding:

gcloud iam service-accounts add-iam-policy-binding SA_ID \
    --member=PRINCIPAL --role=ROLE_NAME \
    --condition=CONDITION

Ingresa los siguientes valores:

SA_ID: El ID de la cuenta de servicio. Puede ser la dirección de correo electrónico de la cuenta de servicio con el formato SA_NAME@PROJECT_ID.iam.gserviceaccount.com o el ID numérico único de la cuenta de servicio.

Nota: Si deseas identificar una cuenta de servicio justo después de crearla, usa el ID numérico en lugar de la dirección de correo electrónico para asegurarte de que se identifique de manera confiable.
PRINCIPAL: Un identificador para la principal o el miembro, que suele tener el siguiente formato: PRINCIPAL-TYPE:ID. Por ejemplo, user:my-user@example.com. Si deseas obtener una lista completa de los valores que PRINCIPAL puede tener, consulta la referencia sobre la vinculación de políticas.

Para el tipo de principal user, el nombre de dominio en el identificador debe ser un dominio de Google Workspace o de Cloud Identity. Para obtener información sobre cómo configurar un dominio de Cloud Identity, consulta la descripción general de Cloud Identity.
ROLE_NAME: El nombre del rol que deseas otorgar. Usa uno de los siguientes formatos:
- Roles predefinidos: roles/SERVICE.IDENTIFIER
- Roles personalizados a nivel de proyecto: projects/PROJECT_ID/roles/IDENTIFIER
- Roles personalizados a nivel de la organización: organizations/ORG_ID/roles/IDENTIFIER
Para obtener una lista de roles predefinidos, consulta Cómo entender los roles.
CONDITION: Opcional La condición que se agregará a la vinculación de función. Para obtener más información sobre las condiciones, consulta la descripción general de las condiciones.

Por ejemplo, a fin de otorgar la función de usuario de cuenta de servicio al usuario my-user@example.com para la cuenta de servicio my-service-account@my-project.iam.gserviceaccount.com, ejecuta el siguiente comando:

gcloud iam service-accounts add-iam-policy-binding my-service-account@my-project.iam.gserviceaccount.com \
    --member=user:my-user@example.com --role=roles/iam.serviceAccountUser

Revoca una sola función

Para revocar una sola función de una principal, haz lo siguiente:

Console

En la consola de Google Cloud, ve a la página Cuentas de servicio.

Ir a Cuentas de servicio
Selecciona un proyecto
Haz clic en la dirección de correo electrónico de la cuenta de servicio.
Ve a la pestaña Permisos y busca la sección Principales con acceso a esta cuenta de servicio.
Busca la fila con la dirección de correo electrónico de la principal cuyo acceso deseas revocar. Luego, haz clic en Editar principal en esa fila.

Nota: No puedes editar las funciones heredadas cuando administras el acceso a las cuentas de servicio. Para editar las funciones heredadas, ve al recurso en el que se otorgó la función.
Haz clic en el botón Borrar para el rol que deseas revocar y, luego, haz clic en Guardar.

gcloud

Para revocar una función de un usuario, ejecuta el comando remove-iam-policy-binding:

gcloud iam service-accounts remove-iam-policy-binding SA_ID \
    --member=PRINCIPAL --role=ROLE_NAME

Ingresa los siguientes valores:

SA_ID: El ID de la cuenta de servicio. Puede ser la dirección de correo electrónico de la cuenta de servicio con el formato SA_NAME@PROJECT_ID.iam.gserviceaccount.com o el ID numérico único de la cuenta de servicio.

Nota: Si deseas identificar una cuenta de servicio justo después de crearla, usa el ID numérico en lugar de la dirección de correo electrónico para asegurarte de que se identifique de manera confiable.
PRINCIPAL: Un identificador para la principal o el miembro, que suele tener el siguiente formato: PRINCIPAL-TYPE:ID. Por ejemplo, user:my-user@example.com. Si deseas obtener una lista completa de los valores que PRINCIPAL puede tener, consulta la referencia sobre la vinculación de políticas.

Para el tipo de principal user, el nombre de dominio en el identificador debe ser un dominio de Google Workspace o de Cloud Identity. Para obtener información sobre cómo configurar un dominio de Cloud Identity, consulta la descripción general de Cloud Identity.
ROLE_NAME: El nombre del rol que deseas revocar. Usa uno de los siguientes formatos:
- Roles predefinidos: roles/SERVICE.IDENTIFIER
- Roles personalizados a nivel de proyecto: projects/PROJECT_ID/roles/IDENTIFIER
- Roles personalizados a nivel de la organización: organizations/ORG_ID/roles/IDENTIFIER
Para obtener una lista de roles predefinidos, consulta Cómo entender los roles.

Por ejemplo, para revocar la función de usuario de cuenta de servicio del usuario my-user@example.com en la cuenta de servicio my-service-account@my-project.iam.gserviceaccount.com, ejecuta este comando:

gcloud iam service-accounts remove-iam-policy-binding my-service-account@my-project.iam.gserviceaccount.com \
    --member=user:my-user@example.com --role=roles/iam.serviceAccountUser

Otorga o revoca varios roles con la consola de Google Cloud

Puedes usar la consola de Google Cloud a fin de otorgar y revocar varios roles para una sola principal:

En la consola de Google Cloud, ve a la página Cuentas de servicio.

Ir a Cuentas de servicio
Selecciona un proyecto.
Haz clic en la dirección de correo electrónico de la cuenta de servicio.
Ve a la pestaña Permisos y busca la sección Principales con acceso a esta cuenta de servicio.
Selecciona la principal cuyos roles deseas modificar:
- Para modificar los roles de una principal que ya tiene roles en la cuenta de servicio, busca una fila que contenga la principal y haz clic en Editar principal en ella. Luego, haz clic en Agregar otro rol.
  
  Para modificar los roles de un agente de servicio, selecciona la casilla de verificación Incluir asignaciones de roles proporcionadas por Google para ver su correo electrónico.
  
  Nota: No puedes editar las funciones heredadas cuando administras el acceso a las cuentas de servicio. Para editar las funciones heredadas, ve al recurso en el que se otorgó la función.
- Para otorgar un rol a una principal que aún no tiene otros roles existentes en la cuenta de servicio, haz clic en Otorgar acceso y, luego, ingresa la dirección de correo electrónico de la principal o algún otro identificador.
Modifica los roles de la principal:
- Para otorgar un rol a una principal que aún no tenga otros roles en el recurso, haz clic en Seleccionar un rol y, luego, selecciona un rol para otorgar de la lista desplegable.
- Para otorgar un rol adicional a la principal, haz clic en Agregar otro rol y, luego, selecciona un rol para otorgar de la lista desplegable.
- Para reemplazar uno de los roles de la principal por un rol diferente, haz clic en el rol existente y, luego, elige un rol diferente para otorgar de la lista desplegable.
- Para revocar uno de los roles de la principal, haz clic en el botón Borrar en cada rol que deseas revocar.
También puedes agregar una condición a un rol, modificar la condición de un rol o quitar la condición de un rol.
Haz clic en Guardar.

Otorga o revoca varios roles de manera programática

Para realizar cambios de acceso a gran escala que implican otorgar y revocar varios roles para varias principales, usa el patrón lectura-modificación-escritura a fin de actualizar la política de permisos de la cuenta de servicio:

Para leer la política de permisos actual, llama a getIamPolicy().
Edita de la política de permisos, ya sea mediante el uso de un editor de texto o de manera programática, para agregar o quitar vinculaciones de roles o principales.
Para escribir la política de permisos actualizada, llama a setIamPolicy().

En esta sección, se muestra cómo usar la CLI de gcloud y la API de REST para actualizar la política de permisos. También puedes actualizar la política mediante las bibliotecas cliente de IAM.

En general, los cambios en las políticas entran en vigor en un plazo de 2 minutos. Sin embargo, en algunos casos, pueden tardar 7 minutos o más en propagarse por todo el sistema.

Obtén la política de permisos actual

gcloud

A fin de obtener la política de permisos para la cuenta de servicio, ejecuta el comando get-iam-policy de la cuenta de servicio:

gcloud iam service-accounts get-iam-policy SA_ID --format=FORMAT > PATH

Ingresa los siguientes valores:

SA_ID: El ID de la cuenta de servicio. Puede ser la dirección de correo electrónico de la cuenta de servicio con el formato SA_NAME@PROJECT_ID.iam.gserviceaccount.com o el ID numérico único de la cuenta de servicio.

Nota: Si deseas identificar una cuenta de servicio justo después de crearla, usa el ID numérico en lugar de la dirección de correo electrónico para asegurarte de que se identifique de manera confiable.
FORMAT: El formato deseado para la política permisos. Usa json o yaml
PATH: Es la ruta a un nuevo archivo de salida de la política de permisos.

Por ejemplo, con el siguiente comando, se obtiene la política de permisos para la cuenta de servicio my-service-account y se guarda en tu directorio principal en formato JSON:

gcloud iam service-accounts get-iam-policy my-service-account --format json > ~/policy.json

REST

El método serviceAccounts.getIamPolicy obtiene la política de permisos de una cuenta de servicio.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

PROJECT_ID: El ID del proyecto de Google Cloud Los ID de proyecto son strings alfanuméricas, como my-project.
SA_ID: El ID de la cuenta de servicio. Puede ser la dirección de correo electrónico de la cuenta de servicio con el formato SA_NAME@PROJECT_ID.iam.gserviceaccount.com o el ID numérico único de la cuenta de servicio.

Nota: Para identificar una cuenta de servicio justo después de su creación, usa el ID numérico en lugar de la dirección de correo electrónico.
POLICY_VERSION: Es la versión de la política que se mostrará. Las solicitudes deben especificar la versión de política más reciente, que es la versión de política 3. Consulta Especifica una versión de política cuando obtienes una política para obtener más detalles.

Método HTTP y URL:

POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID:getIamPolicy

Cuerpo JSON de la solicitud:

{
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID:getIamPolicy"

PowerShell (Windows)

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID:getIamPolicy" | Select-Object -Expand Content

Explorador de APIs (navegador)

La respuesta contiene la política de permisos de la cuenta de servicio. Por ejemplo:

{
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

Guarda la respuesta en un archivo del tipo adecuado (json o yaml).

Java

Para obtener más obtener información sobre cómo instalar y usar la biblioteca cliente de IAM, consulta Bibliotecas cliente de IAM. Para obtener más información, consulta la documentación de referencia de la API de IAM Java.

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.


import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.ServiceAccountName;
import com.google.iam.v1.GetIamPolicyRequest;
import com.google.iam.v1.Policy;
import java.io.IOException;

public class GetServiceAccountPolicy {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    // TODO: Replace with your project ID.
    String projectId = "your-project-id";
    // TODO: Replace with your service account name.
    String serviceAccount = "your-service-account";
    getPolicy(projectId, serviceAccount);
  }

  // Gets a service account's IAM policy.
  public static Policy getPolicy(String projectId, String serviceAccount) throws IOException {

    // Construct the service account email.
    // You can modify the ".iam.gserviceaccount.com" to match the name of the service account
    // whose allow policy you want to get.
    String serviceAccountEmail = serviceAccount + "@" + projectId + ".iam.gserviceaccount.com";

    // Initialize client that will be used to send requests.
    // This client only needs to be created once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      GetIamPolicyRequest request = GetIamPolicyRequest.newBuilder()
              .setResource(ServiceAccountName.of(projectId, serviceAccountEmail).toString())
              .build();
      Policy policy = iamClient.getIamPolicy(request);
      System.out.println("Policy retrieved: " + policy.toString());
      return policy;
    }
  }
}

Python

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

from google.cloud import iam_admin_v1
from google.iam.v1 import iam_policy_pb2, policy_pb2


def get_service_account_iam_policy(project_id: str, account: str) -> policy_pb2.Policy:
    """
    Get policy for service account.
    project_id: ID or number of the Google Cloud project you want to use.
    account: ID or email which is unique identifier of the service account.
    """

    iam_client = iam_admin_v1.IAMClient()
    request = iam_policy_pb2.GetIamPolicyRequest()
    request.resource = f"projects/{project_id}/serviceAccounts/{account}"

    policy = iam_client.get_iam_policy(request)
    return policy

Modifica la política de permisos

De manera programática o mediante un editor de texto, modifica la copia local de la política de permisos de tu cuenta de servicio para que refleje los roles que deseas otorgar o revocar para ciertos usuarios.

Para asegurarte de no reemplazar otros cambios, no edites ni quites el campo etag de la política de permisos. El campo etag identifica el estado actual de la política de permisos. Cuando configuras la política de permisos actualizada, IAM compara el valor de etag en la solicitud con el etag existente y solo escribe la política de permisos si los valores coinciden.

Para editar los roles que otorga una política de permisos, debes editar las vinculaciones de roles en la política de permisos. Las vinculaciones de roles tienen el siguiente formato:

{
  "role": "ROLE_NAME",
  "members": [
    "PRINCIPAL_1",
    "PRINCIPAL_2",
    ...
    "PRINCIPAL_N"
  ],
  "conditions:" {
    CONDITIONS
  }
}

Los marcadores de posición tienen los siguientes valores:

ROLE_NAME: El nombre del rol que deseas otorgar. Usa uno de los siguientes formatos:
- Roles predefinidos: roles/SERVICE.IDENTIFIER
- Roles personalizados a nivel de proyecto: projects/PROJECT_ID/roles/IDENTIFIER
- Roles personalizados a nivel de la organización: organizations/ORG_ID/roles/IDENTIFIER
Para obtener una lista de roles predefinidos, consulta Cómo entender los roles.
PRINCIPAL_1, PRINCIPAL_2, ...PRINCIPAL_N: Los identificadores de las principales a las que deseas otorgar los roles.

Los identificadores principales suelen tener el siguiente formato: PRINCIPAL-TYPE:ID. Por ejemplo, user:my-user@example.com. Si deseas obtener una lista completa de los valores que PRINCIPAL puede tener, consulta la referencia sobre la vinculación de políticas.

Para el tipo de principal user, el nombre de dominio en el identificador debe ser un dominio de Google Workspace o de Cloud Identity. Para obtener información sobre cómo configurar un dominio de Cloud Identity, consulta la descripción general de Cloud Identity.
CONDITIONS: Opcional Cualquier condición que especifique cuándo se otorgará el acceso.

Otorga una función

Para otorgar roles a las principales, modifica las vinculaciones de roles en la política de permisos. Para obtener información sobre qué roles puedes otorgar, consulta Comprende los roles o consulta los roles asignables para la cuenta de servicio. Si necesitas ayuda para identificar el rol predefinido más adecuado, consulta Elige roles predefinidos.

De forma opcional, puedes usar condiciones para otorgar funciones solo cuando se cumplan ciertos requisitos.

Para otorgar un rol que ya está incluido en la política de permisos, agrega la principal a una vinculación de rol existente:

gcloud

Edita la política de permisos y agrega la principal a una vinculación de rol existente. Ten en cuenta que este cambio no se hará efectivo hasta que configures la política de permisos actualizada.

Por ejemplo, imagina que la política de permisos contiene la siguiente vinculación de rol, que otorga el rol Service Account User (roles/iam.serviceAccountUser) a kai@example.com:

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:kai@example.com"
  ]
}

Para otorgar esa misma función a raha@example.com, agrega raha@example.com a la vinculación de función existente:

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:kai@example.com",
    "user:raha@example.com"
  ]
}

REST

Edita la política de permisos y agrega la principal a una vinculación de rol existente. Ten en cuenta que este cambio no se hará efectivo hasta que configures la política de permisos actualizada.

Por ejemplo, imagina que la política de permisos contiene la siguiente vinculación de rol, que otorga el rol Service Account User (roles/iam.serviceAccountUser) a kai@example.com:

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:kai@example.com"
  ]
}

Para otorgar esa misma función a raha@example.com, agrega raha@example.com a la vinculación de función existente:

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:kai@example.com",
    "user:raha@example.com"
  ]
}

Para otorgar un rol que aún no está incluido en la política de permisos, agrega una nueva vinculación de rol:

gcloud

Edita la política de permisos y agrega una nueva vinculación de rol que otorgue el rol a la principal. Este cambio no se hará efectivo hasta que establezcas la política de permisos actualizada.

Por ejemplo, para otorgar el rol Service Account Token Creator (roles/iam.serviceAccountTokenCreator) a raha@example.com, agrega la siguiente vinculación de rol al array bindings de la política de permisos:

{
  "role": "roles/iam.serviceAccountTokenCreator",
  "members": [
    "user:raha@example.com"
  ]
}

REST

Edita la política de permisos y agrega una nueva vinculación de rol que otorgue el rol a la principal. Este cambio no se hará efectivo hasta que establezcas la política de permisos actualizada.

{
  "role": "roles/iam.serviceAccountTokenCreator",
  "members": [
    "user:raha@example.com"
  ]
}

Revoca una función

Para revocar una función, quita la principal de la vinculación de función. Si no hay otras principales en la vinculación de rol, quita toda la vinculación de rol de la política de permisos.

gcloud

Edita la política de permisos y quita la principal o toda la vinculación de rol. Este cambio no se hará efectivo hasta que configures la política de permisos actualizada.

Por ejemplo, imagina que la política de permisos contiene la siguiente vinculación de rol, que otorga a kai@example.com y raha@example.com el rol Service Account User (roles/iam.serviceAccountUser):

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:kai@example.com",
    "user:raha@example.com"
  ]
}

Para revocar la función de kai@example.com, quita kai@example.com de la vinculación de la función:

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:raha@example.com"
  ]
}

Para revocar el rol de kai@example.com y raha@example.com, quita la vinculación de rol de la política de permisos.

REST

Edita la política de permisos y quita la principal o toda la vinculación de rol. Este cambio no se hará efectivo hasta que configures la política de permisos actualizada.

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:kai@example.com",
    "user:raha@example.com"
  ]
}

Para revocar la función de kai@example.com, quita kai@example.com de la vinculación de la función:

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:raha@example.com"
  ]
}

Para revocar el rol de kai@example.com y raha@example.com, quita la vinculación de rol de la política de permisos.

Establece la política de permisos

Después de modificar la política de permisos para otorgar y revocar roles, llama a setIamPolicy() con el fin de realizar las actualizaciones.

gcloud

A fin de configurar la política de permisos del recurso, ejecuta el comando set-iam-policy en la cuenta de servicio:

gcloud iam service-accounts set-iam-policy SA_ID PATH

Ingresa los siguientes valores:

SA_ID: El ID de la cuenta de servicio. Puede ser la dirección de correo electrónico de la cuenta de servicio con el formato SA_NAME@PROJECT_ID.iam.gserviceaccount.com o el ID numérico único de la cuenta de servicio.

Nota: Si deseas identificar una cuenta de servicio justo después de crearla, usa el ID numérico en lugar de la dirección de correo electrónico para asegurarte de que se identifique de manera confiable.
PATH: Es la ruta a un archivo que contiene la política de permisos nueva.

La respuesta contiene la política de permisos actualizada:

Por ejemplo, con el siguiente comando, se establece la política de permisos almacenada en policy.json como la política de permiso de la cuenta de servicio my-service-account@my-project.iam.gserviceaccount.com:

gcloud iam service-accounts set-iam-policy my-service-account@my-project.iam.gserviceaccount.com \
    ~/policy.json

REST

Mediante el método serviceAccounts.setIamPolicy, se configura una política de permisos actualizada para la cuenta de servicio.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

PROJECT_ID: El ID del proyecto de Google Cloud Los ID de proyecto son strings alfanuméricas, como my-project.
SA_ID: El ID de la cuenta de servicio. Puede ser la dirección de correo electrónico de la cuenta de servicio con el formato SA_NAME@PROJECT_ID.iam.gserviceaccount.com o el ID numérico único de la cuenta de servicio.

Nota: Para identificar una cuenta de servicio justo después de su creación, usa el ID numérico en lugar de la dirección de correo electrónico.

POLICY: Es una representación JSON de la política que deseas establecer. Para obtener más información sobre el formato de una política, consulta Referencia de políticas.

Por ejemplo, para establecer la política de permisos que se muestra en el paso anterior, reemplaza policy por lo siguiente:

{
  "version": 1,
  "etag": "BwUqLaVeua8=",
  "bindings": [
    {
      "role": "roles/iam.serviceAccountUser",
      "members": [
        "user:robin@example.com"
      ]
    },
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

Método HTTP y URL:

POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID:setIamPolicy

Cuerpo JSON de la solicitud:

{
  "policy": POLICY
}

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID:setIamPolicy"

PowerShell (Windows)

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID:setIamPolicy" | Select-Object -Expand Content

Explorador de APIs (navegador)

La respuesta contiene la política de permisos actualizada:

Java

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.ServiceAccountName;
import com.google.iam.v1.Policy;
import com.google.iam.v1.SetIamPolicyRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;
import java.util.Arrays;
import java.util.List;

public class SetServiceAccountPolicy {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    // TODO: Replace with your project ID.
    String projectId = "your-project-id";
    // TODO: Replace with your service account name.
    String serviceAccount = "your-service-account";
    // TODO: Replace with your policy, GetPolicy.getPolicy(projectId, serviceAccount).
    Policy policy = Policy.newBuilder().build();

    setServiceAccountPolicy(policy, projectId, serviceAccount);
  }

  // Sets a service account's policy.
  public static Policy setServiceAccountPolicy(Policy policy, String projectId,
                                               String serviceAccount) throws IOException {

    // Construct the service account email.
    // You can modify the ".iam.gserviceaccount.com" to match the name of the service account
    // whose allow policy you want to set.
    String accountEmail = String.format("%s@%s.iam.gserviceaccount.com", serviceAccount, projectId);

    // Initialize client that will be used to send requests.
    // This client only needs to be created once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      List<String> paths = Arrays.asList("bindings", "etag");
      SetIamPolicyRequest request = SetIamPolicyRequest.newBuilder()
              .setResource(ServiceAccountName.of(projectId, accountEmail).toString())
              .setPolicy(policy)
              // A FieldMask specifying which fields of the policy to modify. Only
              // the fields in the mask will be modified. If no mask is provided, the
              // following default mask is used:
              // `paths: "bindings, etag"`
              .setUpdateMask(FieldMask.newBuilder().addAllPaths(paths).build())
              .build();

      return iamClient.setIamPolicy(request);
    }
  }
}

Python

Para autenticarte en IAM, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

from google.cloud import iam_admin_v1
from google.iam.v1 import iam_policy_pb2, policy_pb2


def set_service_account_iam_policy(
    project_id: str, account: str, policy: policy_pb2.Policy
) -> policy_pb2.Policy:
    """
    Set policy for service account. Pay attention that previous state will be completely rewritten.
    If you want to update only part of the policy follow the approach read->modify->write.
    For more details about policies check out https://cloud.google.com/iam/docs/policies

    project_id: ID or number of the Google Cloud project you want to use.
    account: ID or email which is unique identifier of the service account.
    policy: Policy which has to be set.
    """

    # Same approach as for policies on project level, but client stub is different.
    iam_client = iam_admin_v1.IAMClient()
    request = iam_policy_pb2.SetIamPolicyRequest()
    request.resource = f"projects/{project_id}/serviceAccounts/{account}"

    # request.etag field also will be merged which means you are secured from collision,
    # but it means that request may fail and you need to leverage exponential reties approach
    # to be sure policy has been updated.
    request.policy.MergeFrom(policy)

    policy = iam_client.set_iam_policy(request)
    return policy

¿Qué sigue?

Obtén información sobre qué roles otorgar para permitir que las principales se autentiquen como cuentas de servicio.
Descubre cómo elegir las funciones predefinidas más adecuadas.
Revisa las Prácticas recomendadas para trabajar con cuentas de servicio a fin de obtener información sobre cómo usar cuentas de servicio de forma segura.
Obtén más información para administrar el acceso a proyectos, carpetas y organizaciones.
Conoce los pasos generales para administrar el acceso a otros recursos.
Obtén más información sobre cómo hacer que el acceso de una principal sea condicional con vinculaciones de funciones condicionales.

Pruébalo tú mismo

Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

Comenzar gratis