En esta página, se explica cómo usar los límites de acceso a credenciales para crear un token de acceso de OAuth 2.0 con permisos de Cloud Storage reducidos.
El proceso para crear un token con permisos reducidos incluye los siguientes pasos:
- Otorga los roles de IAM adecuados a una cuenta de usuario o de servicio.
- Define un límite de acceso a las credenciales que establezca un límite superior en los permisos que están disponibles para el usuario o la cuenta de servicio.
- Crea un token de acceso de OAuth 2.0 para el usuario o la cuenta de servicio.
- Intercambia el token de acceso de OAuth 2.0 por un token nuevo que respete el límite de acceso a credenciales.
Luego, puedes usar el nuevo token de acceso de OAuth 2.0 de alcance reducido para autenticar las solicitudes a Cloud Storage.
Antes de comenzar
Antes de usar los límites de acceso a las credenciales, asegúrate de cumplir con los siguientes requisitos:
Debes disminuir el alcance de los permisos solo para Cloud Storage, no para otros servicios deGoogle Cloud .
Si necesitas disminuir el alcance de los permisos para servicios adicionales de Google Cloud, puedes crear varias cuentas de servicio y otorgar un conjunto diferente de roles a cada una.
Puedes usar los tokens de acceso de OAuth 2.0 para la autenticación. Otros tipos de credenciales de corta duración no admiten límites de acceso a las credenciales.
Además, debes habilitar las API requeridas:
-
Enable the IAM and Security Token Service APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin
), which contains theserviceusage.services.enable
permission. Learn how to grant roles.
Asigna roles de IAM
Un límite de acceso a las credenciales establece un límite superior en los permisos disponibles para un recurso. Puede quitar permisos a una principal, pero no puede agregar permisos que esta aún no tiene.
Como resultado, también debes otorgarle funciones a la principal que proporcionen los permisos que necesita, ya sea en un bucket de Cloud Storage o en un recurso de nivel superior, como el proyecto.
Por ejemplo, supongamos que necesitas crear una credencial de corta duración de alcance reducido que permita que una cuenta de servicio cree objetos en un bucket:
- Como mínimo, debes otorgar una función a la cuenta de servicio que incluya el permiso
storage.objects.create
, como la función de creador de objetos de Store (roles/storage.objectCreator
). El límite de acceso a las credenciales también debe incluir este permiso. - También puedes otorgar una función que incluya más permisos, como la función de administrador de objetos de Storage (
roles/storage.objectAdmin
). La cuenta de servicio solo puede usar los permisos que aparecen en la asignación de funciones y en el límite de acceso a las credenciales.
Para obtener información sobre las funciones predefinidas de Cloud Storage, consulta Funciones de Cloud Storage.
Define el límite de acceso a las credenciales
Un límite de acceso a las credenciales es un objeto que contiene una lista de reglas de límites de acceso. Las reglas se componen de parámetros que especifican el límite superior de los permisos que están disponibles para el usuario o la cuenta de servicio. Para definir un límite de acceso a las credenciales, crea un objeto JSON que enumere las reglas de límites de acceso y sus parámetros.
A continuación, se muestra un ejemplo de un límite de acceso a las credenciales:
{
"accessBoundary": {
"accessBoundaryRules": [
{
"availablePermissions": [
"inRole:ROLE_ID"
],
"availableResource": "//storage.googleapis.com/projects/_/buckets/BUCKET_NAME"
"availabilityCondition": {
"expression" : "CONDITION"
}
]
}
}
Reemplaza lo siguiente:
ROLE_ID
: Es el ID de un rol predefinido o personalizado que define el límite superior de los permisos disponibles para el recurso. Por ejemplo,roles/storage.objectViewer
Para especificar varios roles, agrega una línea nueva con un prefijoinRole:
seguido del ID del rol. Solo estarán disponibles los permisos de los roles especificados.BUCKET_NAME
: Es el nombre del bucket de Cloud Storage al que se aplica la regla.CONDITION
: Opcional Es una expresión de condición que especifica los objetos de Cloud Storage en los que están disponibles los permisos. Por ejemplo, la siguiente condición permite que los permisos estén disponibles para los objetos cuyo nombre comience concustomer-a
:resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a')
Para obtener más información sobre cómo crear y personalizar límites de acceso a las credenciales, consulta Componentes de un límite de acceso a las credenciales.
Para ver ejemplos de posibles casos de uso de los límites de acceso a las credenciales, consulta Ejemplos de límites de acceso a las credenciales.
Crea un token de acceso de OAuth 2.0
Antes de crear una credencial de corta duración de alcance reducido, debes crear un token de acceso de OAuth 2.0 normal. A continuación, puedes intercambiar la credencial normal por una credencial de alcance reducido. Cuando crees el token de acceso, usa el permiso de OAuth 2.0 https://www.googleapis.com/auth/cloud-platform
.
Si deseas crear un token de acceso para una cuenta de servicio, puedes completar el flujo de OAuth 2.0 de servidor a servidor o puede usar la API de credenciales de la cuenta de servicio a fin de generar un token de acceso de OAuth 2.0.
Si deseas crear un token de acceso para un usuario, consulta Obtén tokens de acceso de OAuth 2.0. También puedes usar OAuth 2.0 Playground a fin de crear un token de acceso para tu propia Cuenta de Google.
Intercambia el token de acceso de OAuth 2.0
Después de crear un token de acceso de OAuth 2.0, puedes intercambiarlo por un token de alcance reducido que respete el límite de acceso a las credenciales. Este proceso suele implicar un agente de tokens y un consumidor de tokens:
El agente de tokens es responsable de definir el límite de acceso a las credenciales y de intercambiar un token de acceso por un token de alcance reducido.
El agente de tokens puede usar una biblioteca de autenticación compatible para intercambiar tokens de acceso de forma automática, o bien llamar al servicio de tokens de seguridad para intercambiar tokens de forma manual.
El consumidor de tokens solicita un token de acceso de alcance reducido desde el agente de tokens y, luego, lo usa para realizar otra acción.
El consumidor de tokens puede usar una biblioteca de autenticación compatible para actualizar automáticamente los tokens de acceso antes de que venzan. Como alternativa, puede actualizar tokens de forma manual o permitir que los tokens venzan sin actualizarlos.
Existen dos formas de intercambiar el token de acceso por un token de alcance reducido:
Intercambio de tokens del cliente (recomendado): Los clientes obtienen materiales criptográficos del servidor de la API del servicio de tokens de seguridad. Los materiales criptográficos permiten que los clientes generen tokens de alcance reducido con diferentes reglas de límites de acceso a las credenciales de forma independiente en el cliente durante un período determinado (por ejemplo, 1 hora). Este enfoque reduce la latencia y mejora la eficiencia, en especial para los clientes que requieren actualizaciones frecuentes de las reglas del límite de acceso a credenciales. También es más eficiente para las aplicaciones que necesitan generar muchos tokens únicos con alcance reducido. Este es el enfoque recomendado porque proporciona un mejor rendimiento, escalabilidad y compatibilidad con funciones futuras.
Intercambio de tokens del servidor: Los clientes solicitan un nuevo token de alcance reducido al servidor de la API de Security Token Service cada vez que cambia una regla del límite de acceso a credenciales. Este enfoque es sencillo, pero requiere un viaje de ida y vuelta al servidor de la API del servicio de tokens de seguridad para cada solicitud de token con alcance reducido. Este enfoque solo se recomienda para los clientes que requieren una biblioteca cliente que no admita el intercambio de tokens del cliente, debido al viaje de ida y vuelta a la API del servicio de token de seguridad para cada solicitud de token con alcance reducido.
Intercambio de tokens del cliente
Si creas el agente de tokens y el consumidor de tokens con el siguiente lenguaje, puedes usar la biblioteca de autenticación de Google para intercambiar y actualizar tokens de forma automática a través del enfoque del cliente.
Java
Para Java, puedes intercambiar y actualizar tokens de forma automática con la versión 1.32.1 (o una posterior) del artefacto com.google.auth:google-auth-library-cab-token-generator
.
Para verificar la versión de tu artefacto, ejecuta el siguiente comando de Maven en el directorio de tu aplicación:
mvn dependency:list -DincludeArtifactIds=google-auth-library-cab-token-generator
En el siguiente ejemplo, se muestra cómo un agente de tokens puede generar tokens de alcance reducido:
En el siguiente ejemplo, se muestra cómo un consumidor de tokens puede usar un controlador de actualización para obtener y actualizar automáticamente los tokens de alcance reducido:
Intercambio de tokens del servidor
En esta sección, se describen los siguientes métodos que puedes usar para intercambiar tokens a través del enfoque del servidor:
- Intercambia y actualiza el token de acceso de forma automática
- Intercambia y actualiza el token de acceso de forma manual
Intercambia y actualiza el token de acceso automáticamente con el enfoque del servidor
Si creas el agente de tokens y el consumidor de tokens con uno de los siguientes lenguajes, puedes usar la biblioteca de autenticación de Google para intercambiar y actualizar tokens de forma automática con el enfoque de generación de tokens del servidor:
Go
Para Go, puedes intercambiar y actualizar tokens de forma automática con la versión v0.0.0-20210819190943-2bc19b11175f (o una posterior) del paquete golang.org/x/oauth2
.
Para verificar la versión de tu paquete, ejecuta el siguiente comando en el directorio de tu aplicación:
go list -m golang.org/x/oauth2
En el siguiente ejemplo, se muestra cómo un agente de tokens puede generar tokens de alcance reducido:
En el siguiente ejemplo, se muestra cómo un consumidor de tokens puede usar un controlador de actualización para obtener y actualizar automáticamente los tokens de alcance reducido:
Java
Para Java, puedes intercambiar y actualizar tokens de forma automática con la versión 1.1.0 (o una posterior) del artefacto com.google.auth:google-auth-library-oauth2-http
.
Para verificar la versión de tu artefacto, ejecuta el siguiente comando de Maven en el directorio de tu aplicación:
mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
En el siguiente ejemplo, se muestra cómo un agente de tokens puede generar tokens de alcance reducido:
En el siguiente ejemplo, se muestra cómo un consumidor de tokens puede usar un controlador de actualización para obtener y actualizar automáticamente los tokens de alcance reducido:
Node.js
Para Node.js, puedes intercambiar y actualizar tokens de forma automática con la versión 7.9.0 (o una posterior) del paquete google-auth-library
.
Para verificar la versión de tu paquete, ejecuta el siguiente comando en el directorio de tu aplicación:
npm list google-auth-library
En el siguiente ejemplo, se muestra cómo un agente de tokens puede generar tokens de alcance reducido:
En el siguiente ejemplo, se muestra cómo un consumidor de tokens puede proporcionar un controlador de actualización que obtiene y actualiza de forma automática los tokens de alcance reducido:
Python
Para Python, puedes intercambiar y actualizar tokens de forma automática con la versión 2.0.0 (o una posterior) del paquete google-auth
.
Para verificar la versión del paquete, ejecuta el siguiente comando en el entorno en el que está instalado el paquete:
pip show google-auth
En el siguiente ejemplo, se muestra cómo un agente de tokens puede generar tokens de alcance reducido:
En el siguiente ejemplo, se muestra cómo un consumidor de tokens puede proporcionar un controlador de actualización que obtiene y actualiza de forma automática los tokens de alcance reducido:
Intercambia y actualiza el token de acceso de forma manual
Un agente de tokens puede usar la API de Security Token Service a fin de intercambiar un token de acceso por un token de acceso de alcance reducido. Luego, puede proporcionar el token de alcance reducido a un consumidor de tokens.
Para intercambiar el token de acceso, usa el siguiente método HTTP y URL:
POST https://sts.googleapis.com/v1/token
Configura el encabezado Content-Type
en la solicitud a application/x-www-form-urlencoded
. Incluye los siguientes campos en el cuerpo de la solicitud:
Campos | |
---|---|
grant_type |
Usa el valor |
options |
Un límite de acceso a credenciales con formato JSON, codificado con código por ciento. |
requested_token_type |
Usa el valor |
subject_token |
El token de acceso de OAuth 2.0 que deseas intercambiar. |
subject_token_type |
Usa el valor |
La respuesta es un objeto JSON que contiene los siguientes campos:
Campos | |
---|---|
access_token |
Un token de acceso de OAuth 2.0 de alcance reducido que respeta el límite de acceso a las credenciales. |
expires_in |
Cantidad de tiempo que transcurre hasta que vence el token de alcance reducido, expresada en segundos. Este campo solo se incluye si el token de acceso original representa una cuenta de servicio. Cuando este campo no está incluido, el token de alcance reducido tiene el mismo tiempo de vencimiento que el token de acceso original. |
issued_token_type |
Contiene el valor |
token_type |
Contiene el valor |
Por ejemplo, si se almacena un límite de acceso a las credenciales en formato JSON en el archivo ./access-boundary.json
, puedes usar el siguiente comando curl
para intercambiar el token de acceso. Reemplaza original-token
con el token de acceso original:
curl -H "Content-Type:application/x-www-form-urlencoded" \ -X POST \ https://sts.googleapis.com/v1/token \ -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange&subject_token_type=urn:ietf:params:oauth:token-type:access_token&requested_token_type=urn:ietf:params:oauth:token-type:access_token&subject_token=original-token" \ --data-urlencode "options=$(cat ./access-boundary.json)"
La respuesta es similar al siguiente ejemplo:
{
"access_token": "ya29.dr.AbCDeFg-123456...",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 3600
}
Cuando un consumidor de tokens solicita un token de alcance reducido, el agente de tokens responde con el token de alcance reducido y la cantidad de segundos hasta que venza. Si el token venció, el servidor rechaza la solicitud. Para actualizar el token de alcance reducido, el consumidor puede solicitar un token de alcance reducido del agente antes de que venza el token existente.
¿Qué sigue?
- Obtén más información sobre el control de acceso para Cloud Storage.
- Crea una credencial de cuenta de servicio de corta duración.
- Crea un token de acceso de OAuth 2.0 para una cuenta de servicio con uno de los siguientes métodos:
- Crea un token de acceso de OAuth 2.0 para un usuario.
- Consulta los permisos en cada función predefinida.
- Obtén información sobre las funciones personalizadas.