Una clave de API es una credencial secreta que permite autenticar solicitudes. Una cuenta de servicio es una identidad no humana que puede usar una aplicación o una carga de trabajo automatizada. Una cuenta de servicio puede ser propietaria de claves de API. La cuenta y sus claves cumplen funciones distintas dentro del mismo sistema de autenticación.
Para tus propias tareas de desarrollo, usa una clave de proyecto que pertenezca a tu cuenta de usuario. Para una aplicación o automatización que deba tener sus propios permisos y ciclo de vida, usa una cuenta de servicio. Para administrar la organización mediante las API de administración, usa una clave de API de administración.
Elegir la identidad adecuada
| Carga de trabajo | Identidad y credencial | Motivo |
|---|---|---|
| Tus propias tareas de desarrollo o exploración en el entorno local | Tu cuenta de usuario y una clave de API del proyecto | Las solicitudes usan los permisos que tienes en el proyecto. |
| Una aplicación desplegada, una tarea programada o un flujo de trabajo de integración continua (CI) | Una cuenta de servicio del proyecto y su clave de API | La carga de trabajo tiene una identidad independiente de la de cualquier desarrollador. |
| Una carga de trabajo con un proveedor de identidad compatible con OpenAI | Una cuenta de servicio del proyecto con federación de identidades de cargas de trabajo | La carga de trabajo puede autenticarse sin almacenar una clave de API de OpenAI de larga duración. |
| Una automatización que crea proyectos o administra sus cuentas de servicio y claves | Una clave de API de administración | La administración de la organización requiere puntos de acceso y permisos administrativos independientes. |
Cuando una clave pertenece a un usuario, las solicitudes que se hacen con ella usan los permisos de ese usuario. No compartas la clave de un desarrollador con todo el equipo ni uses la identidad de esa persona como identidad permanente de una aplicación en producción.
Cada cuenta de servicio pertenece a un proyecto. Asigna a cada carga de trabajo la identidad y los permisos de acceso que necesita dentro del proyecto. Puedes usar proyectos distintos para aislar los recursos, los miembros y el uso de cada aplicación o entorno. Dentro de un mismo proyecto, puedes distinguir las cargas de trabajo mediante cuentas de servicio distintas sin crear otro proyecto.
Entender los permisos y su alcance
Lo que puedes hacer con una clave de API depende tanto de los permisos de la clave como de los de su propietario. Los alcances de la clave pueden limitar las operaciones que permite, pero no pueden otorgar permisos que el usuario o la cuenta de servicio no tenga. Incluso una clave sin restricciones está sujeta a los permisos efectivos de su propietario.
Asigna a cada cuenta de servicio solo los roles que necesita su carga de trabajo y luego restringe sus claves cuando corresponda. Consulta Permisos y roles para conocer el modelo de autorización. En Cuentas de servicio con Terraform encontrarás una configuración que crea una identidad, le asigna un rol personalizado y emite una clave con un alcance definido.
Una clave de API de administración tiene una función distinta de la de una clave de proyecto para una carga de trabajo. Guarda la credencial administrativa en el servicio de confianza que aprovisiona y administra los recursos. Para las solicitudes que la aplicación envíe a los modelos, usa la credencial de la cuenta de servicio del proyecto.
Automatizar la administración de proyectos y claves
Si tu aplicación aprovisiona proyectos para sus clientes, puedes asignar a cada carga de trabajo una cuenta de servicio del proyecto. Así, su identidad es independiente de la del desarrollador que ejecuta el proceso de aprovisionamiento. Tu servicio de aprovisionamiento usa las API de administración para gestionar el proyecto y sus cuentas de servicio. La aplicación aprovisionada usa su propia credencial de proyecto.
Estas son las operaciones administrativas que puedes usar:
| Operación | Finalidad |
|---|---|
| Crear un proyecto | Crea el proyecto al que pertenecen los recursos y la cuenta de servicio de la carga de trabajo. |
| Crear una cuenta de servicio | Crea la identidad de la carga de trabajo en ese proyecto. La opción create_service_account_only crea la cuenta sin roles predeterminados ni clave de API inicial. |
| Crear una clave de API para una cuenta de servicio | Emite una clave para una cuenta de servicio existente. Puedes definir los alcances de la clave y una fecha de vencimiento según sea necesario. |
| Administrar las claves de API del proyecto | Permite listar, consultar, actualizar o revocar las claves existentes del proyecto, incluidas las de las cuentas de servicio. |
Los puntos de acceso para administrar claves de API de proyecto no permiten crear una clave de proyecto en nombre de otro usuario para que le pertenezca a ese usuario. Para crear claves de forma programática, usa una cuenta de servicio y el punto de acceso correspondiente para crear sus claves.
Si creas una cuenta de servicio sin roles predeterminados, la cuenta no obtiene permiso para enviar solicitudes a los modelos. Asígnale los permisos necesarios antes de usar sus credenciales. Las políticas de claves de la organización y del proyecto también se aplican al crear claves, incluso si usas una cuenta de servicio.
Administrar las credenciales durante su ciclo de vida
La API devuelve el valor completo de una clave de cuenta de servicio solo cuando creas la clave. Guárdala en tu gestor de secretos y ponla a disposición de la carga de trabajo en el servidor. No incluyas claves secretas en el código que se ejecuta en el navegador, las aplicaciones móviles, el control de versiones, los registros ni las respuestas que reciben los clientes.
Establece una fecha de vencimiento que cumpla con las políticas de tu organización y de tu proyecto. Para rotar una clave, emite una nueva, actualiza la carga de trabajo para que la use, verifica que funcione y revoca la clave anterior. La cuenta de servicio puede conservar su identidad aunque cambien sus claves.
Revisa los permisos de acceso de la carga de trabajo cuando cambien sus funciones y revoca sus credenciales cuando la retires. Consulta las recomendaciones sobre claves de API en producción para conocer las políticas de administración y vencimiento de claves. Para autenticar una carga de trabajo sin almacenar una clave de API, consulta la federación de identidades de cargas de trabajo.