Descripción general de la autenticación de API basada en IAM

Esta página se aplica a Apigee, pero no a Apigee Hybrid.

Apigee admite la autenticación y la autorización basadas en IAM para los proxies de API. Para usar esta función, incluye la política VerifyIAM en el flujo de solicitud del proxy y configura el identificador de usuario (por lo general, la dirección de correo electrónico) del consumidor de la API para que tenga el rol o los permisos de Google Cloud IAM necesarios para invocar las APIs de Apigee. La solicitud a la API debe pasar un token de acceso Google Cloud válido para ese usuario.

Los administradores pueden otorgar autorización a cualquier principalGoogle Cloud , no solo a usuarios individuales.

Usa el control de acceso basado en IAM

En esta sección, se describe el proceso de extremo a extremo para configurar la autenticación y la autorización basadas en IAM, cómo se evalúan las solicitudes una vez que se configura el acceso y cómo revocar el acceso de los consumidores de la API que ya tenían acceso.

Agrega la administración de acceso

Para configurar la administración de acceso para un proxy de API, haz lo siguiente:

  1. Agrega la política VerifyIAM a los proxies de API de Apigee como parte del flujo de solicitudes.
  2. El administrador de Cloud para el proyecto de Apigee:
    1. Otorga el rol de IAM deploymentInvoker (o un rol personalizado con el permiso de IAM apigee.deployments.invoke) al principal Google Cloud del consumidor de la API a nivel del proyecto. Esto le otorga al consumidor de la API acceso para invocar todas las APIs alojadas en la organización de Apigee asociada.

      o

    2. Usa la acción SetIamPolicy para otorgar el rol o permiso al principal Google Cloud del consumidor de la API en una implementación en particular o de forma iterativa en varias implementaciones. Usa la operación de lista en el recurso de implementación para ver todas las implementaciones dentro de un entorno, incluidos los proxies de API y los flujos compartidos. El nombre de la implementación es el nombre del proxy de API o del flujo compartido.
  3. Dirige al consumidor de la API para que genere un token de acceso, que pasará dentro de la solicitud a la API de Apigee para la verificación de permisos. El token generado debe tener el permiso de autenticación https://www.googleapis.com/auth/cloud-platform.

Operaciones de administración

En esta sección, se enumeran las acciones que realizan los administradores de la API (productores de la API) cuando administran permisos basados en IAM.

La documentación de las operaciones basadas en la API que se usan cuando se administra el acceso basado en IAM se encuentra en la documentación de referencia de las APIs de organizations.environments y organizations.environments.deployments, y se incluyen las operaciones SetIamPolicy, GetIamPolicy, TestIamPermissions y GetDeployment.

En esta tabla, se asignan las operaciones a los permisos necesarios:

Operación del administrador Acción Se requiere permiso de IAM Recurso de IAM en el que se necesita el permiso*
GetDeployment Recupera información de una implementación en un entorno de Apigee apigee.deployments.get Proyecto de Google Cloud o entorno de Apigee
ListDeployments Enumera las implementaciones de un entorno de Apigee apigee.deployments.list Proyecto o entorno de Apigee
SetIamPolicy Establece el acceso de invocación para los consumidores de API en una implementación de API en particular apigee.deployments.setIamPolicy Proyecto de Google Cloud o entorno de Apigee
GetIamPolicy Recupera el conjunto de parámetros de configuración de acceso de invocación para una implementación de API apigee.deployments.getIamPolicy Proyecto de Google Cloud o entorno de Apigee
TestIamPermissions Verifica si el usuario que llama a esta API tiene el permiso mencionado en la carga útil. No se necesita permiso de IAM N/A
* El proyecto Google Cloud es el que se usa para aprovisionar Apigee. Los permisos a nivel del entorno de Apigee se establecen en el entorno con setIAMPolicy.

Verificación de acceso al entorno de ejecución

Cuando el consumidor de la API intenta acceder a una API con control de acceso basado en IAM, se realiza una verificación para ver si tiene el token de acceso necesario y el rol o permiso adecuado a nivel del proyecto o de la implementación. Si es así, se le permite continuar con el acceso al proxy. De lo contrario, se bloquearán.

Quitar acceso

Para quitar el acceso a nivel del proyecto: Para quitar el acceso de un consumidor de la API que se administra a nivel del proyecto, el administrador de Cloud del proyecto de Apigee revoca el rol de IAM deploymentInvoker (o el rol personalizado con el permiso de IAM apigee.deployments.invoke) del principal Google Cloud del consumidor de la API para el proyecto Google Cloud .

Si se otorgó acceso a implementaciones individuales con setIamPolicy, quita el rol o el permiso de las implementaciones con otra operación setIamPolicy.

Características y limitaciones del control de acceso basado en IAM

Ten en cuenta estas características y limitaciones cuando uses la autenticación y autorización basadas en IAM:

  • Por lo general, la ejecución de políticas con VerifyIAM tarda entre 10 y 50 milisegundos. Sin embargo, es posible que algunas llamadas experimenten latencias más altas. Por ejemplo, en la región de asia-east2 específicamente, la latencia promedio puede aumentar a 50 ms, y algunas llamadas podrían tardar alrededor de 100 ms en completarse.

    Ten en cuenta que estas cifras de latencia no están garantizadas.

  • La inclusión de la política VerifyIAM para un proxy es solo una verificación de verificado o no verificado; los roles y permisos específicos del consumidor de la API no se consideran en procesos posteriores del flujo de solicitud o respuesta.
  • Dado que la verificación de autorización solo se realiza en el momento de la ejecución de la política de VerifyIAM, esta debería ser la primera política en el flujo de solicitud, después de las políticas de administración de tráfico.
  • Si la validación de permisos se realiza correctamente o el productor de la API marcó la política VerifyIAM para continuar en caso de error, el flujo de la solicitud continúa ejecutando las demás políticas, si las hay, hasta llegar al servidor de destino. Si falla la verificación de permisos y el productor de la API no marcó la política para que continúe en caso de error, el usuario recibirá un mensaje de error.
  • Agregar acceso de invocación (apigee.deployments.invoke) a nivel del entorno no otorga acceso de invocación a todas las implementaciones de la API dentro del entorno.
  • Las condiciones de IAM no son compatibles con el recurso de implementación y no se pueden usar para controlar el acceso de invocación. Consulta Agrega condiciones de IAM de Apigee a las políticas para obtener más información.
  • El control de acceso basado en IAM admite un máximo de 1,500 vinculaciones de roles en una sola política y otras limitaciones. Consulta Cuotas y límites de IAM.
  • El control de acceso basado en IAM está sujeto a retrasos en la propagación de IAM.
  • Si intentas administrar otras operaciones de apigee.deployments, como apigee.deployments.delete a través de setIamPolicy a nivel de la implementación, no será efectivo, pero tampoco se mostrará un error. Solo apigee.deployements.invoke es efectivo.
  • El acceso a una implementación se borra cuando el proxy correspondiente se quita del entorno o se borra. El acceso debe volver a agregarse en la reimplementación.
  • Por el momento, la autenticación y la autorización basadas en IAM no están disponibles en Hybrid.

Ejemplos

En esta sección, se proporcionan ejemplos para otorgar y revocar el acceso basado en IAM a las APIs. En estos ejemplos, se da por sentado que VerifyIAM ya se agregó al proxy de API adecuado.

En estos ejemplos, usa la consola de Cloud o gcloud (que se muestra) para administrar roles o permisos en el principal Google Cloud del consumidor de la API.

Otorga y revoca el acceso de los usuarios para invocar todas las APIs de una organización de Apigee

Para agregar acceso, agrega el rol deploymentInvoker:

APIGEE_ORG=GCP_PROJECT
USER=USER_EMAIL_HERE
gcloud projects add-iam-policy-binding "${APIGEE_ORG}" --member="${USER}" \
    --role='roles/apigee.deploymentInvoker'
  

Para revocar el acceso, quita el rol deploymentInvoker:

APIGEE_ORG=GCP_PROJECT
USER=USER_EMAIL_HERE
gcloud projects remove-iam-policy-binding "${APIGEE_ORG}" --member="${USER}" \
    --role='roles/apigee.deploymentInvoker'
 

Otorga y revoca el acceso de los usuarios a implementaciones específicas dentro de un entorno

Para agregar el rol de invocador de un solo usuario a una implementación específica, haz lo siguiente:

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER=USER_EMAIL_HERE
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "bindings": [
      {
        "members": [
          "user:'"$USER"'"
        ],
        "role": "roles/apigee.deploymentInvoker"
      }
    ]
  }
}'
  

Una respuesta exitosa debería verse de la siguiente manera:

{
    "version": 1,
    "etag": "BwYT8i40Vwo=",
    "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:user-email@example.com"
        ]
      }
    ]
  }

Para agregar el rol de invocador para varios usuarios a una implementación específica, haz lo siguiente:

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER1=EMAIL_FOR_USER1
USER2=EMAIL_FOR_USER2
USER3=EMAIL_FOR_USER3
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "bindings": [
      {
        "members": [
        "user:'"$USER1"'",
        "user:'"$USER2"'",
        "user:'"$USER3"'"
        ],
        "role": "roles/apigee.deploymentInvoker"
      }
    ]
  }
}'
  

Para consultar el objeto de política que se estableció previamente, haz lo siguiente:

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:getIamPolicy" \
  --header "Authorization: Bearer $TOKEN"
  

Deberías ver una respuesta exitosa como la que se muestra arriba.

El usuario puede verificar si puede acceder a la implementación especificada (si el permiso apigee.deployments.invoke está establecido para el usuario en una implementación especificada), sin invocar la API implementada directamente. Para ello, el usuario puede enviar esta solicitud con un token de acceso que genere:

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER=USER_EMAIL_HERE
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:testIamPermissions" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{"permissions":["apigee.deployments.invoke"]}'

La respuesta debe incluir el permiso apigee.deployments.invoke para el usuario.

Para revocar el acceso a una implementación específica para un solo usuario, quita el rol de deploymentInvoker para ese usuario. Para ello, primero obtén el objeto de política que está asociado actualmente con la implementación:

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:getIamPolicy" \
  --header "Authorization: Bearer $TOKEN"
  

La respuesta de éxito debería ser similar a la siguiente.

{
  "version": 1,
  "etag": "BwYT8i40Vwo=",
  "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:user1-email@example.com",
          "user:user2-email@example.com",
          "user:user3-email@example.com"
        ]
      }
    ]
  }

Para quitar la vinculación de un solo usuario, usa setIamPolicy y especifica en la carga útil los usuarios que deben seguir teniendo acceso, como lo harías cuando configuras el acceso inicial para esos usuarios. Continuando con el ejemplo anterior, si quisieras quitar el acceso de USER1, pero conservar el de USER2 y USER3, usarías este comando:

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "bindings": [
      {
        "members": [
        "user:'"$USER2"'",
        "user:'"$USER3"'"
        ],
        "role": "roles/apigee.deploymentInvoker"
      }
    ]
  }
}'

Para quitar la vinculación de todos los usuarios en una implementación específica, especifica una carga útil vacía:

  curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{}'
  

Para verificar que se quitó la vinculación, asegúrate de que el permiso apigee.deployments.invoke no exista para el usuario en la implementación:

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:testIamPermissions" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{"permissions":["apigee.deployments.invoke"]}'

Esto debería devolver una respuesta adecuada; por ejemplo, un resultado vacío si ningún usuario tiene permiso para invocar la API.