En esta página, se describe cómo autenticar un recurso protegido por Identity-Aware Proxy (IAP) desde una cuenta de usuario o una cuenta de servicio.
Una cuenta de usuario pertenece a un usuario individual. Debes autenticarla cuando tu aplicación requiera acceso a recursos protegidos con IAP en nombre de un usuario. Para obtener más información, consulta Cuentas de usuario.
Una cuenta de servicio pertenece a una aplicación y no a un usuario individual. Debes autenticarla cuando desees permitir que una aplicación acceda a tus recursos protegidos con IAP. Para obtener más información, consulta Cuentas de servicio.
Antes de comenzar
Necesitarás lo siguiente antes de comenzar:
- Una aplicación protegida con IAP a la que deseas conectarte de manera programática mediante una cuenta de desarrollador, una cuenta de servicio o credenciales de aplicación para dispositivos móviles.
Autentica una cuenta de usuario
Puedes habilitar el acceso de los usuarios a tu aplicación desde una aplicación para computadoras o dispositivos móviles a fin de permitir que un programa interactúe con un recurso protegido con IAP.
Autenticación desde una aplicación para dispositivos móviles
- Crea o usa un ID de cliente de OAuth 2.0 existente en tu app para dispositivos móviles. Si quieres usar un ID de cliente de OAuth 2.0 existente, sigue los pasos que se indican en Cómo compartir clientes de OAuth.
- Incluye en la lista de entidades permitidas el ID de cliente de OAuth para el acceso programático de la aplicación.
- Obtén un token de ID para el ID de cliente protegido con IAP.
- Android: Usa la API de Acceso con Google para solicitar un token de OpenID Connect (OIDC). Establece el ID de cliente
requestIdToken
en el ID de cliente del recurso al que te estás conectando. - iOS: Usa el Acceso con Google para obtener un token de ID.
- Android: Usa la API de Acceso con Google para solicitar un token de OpenID Connect (OIDC). Establece el ID de cliente
- Incluye el token de ID en un encabezado
Authorization: Bearer
a fin de realizar la solicitud autenticada para el recurso protegido con IAP.
Autenticación desde una aplicación de escritorio
En esta sección se describe cómo autenticar una cuenta de usuario desde una línea de comandos de escritorio.
- Para permitir que los desarrolladores accedan a tu aplicación desde la línea de comandos, crea un ID de cliente de OAuth 2.0 para computadoras o comparte un ID de cliente de OAuth para computadoras existente.
- Incluye en la lista de entidades permitidas el ID de cliente de OAuth para el acceso programático de la aplicación.
Accede a la aplicación
Todos los desarrolladores que quieran acceder a una aplicación protegida con IAP deberán primero acceder. Puedes empaquetar el proceso en una secuencia de comandos, por ejemplo, mediante la gcloud CLI. A continuación se muestra un ejemplo del uso de curl para ingresar y generar un token que se puede usar a fin de acceder a la aplicación:
- Ingresa a la cuenta que tiene acceso al recurso de Google Cloud.
-
Iniciar un servidor local que pueda reproducir las solicitudes entrantes
$ nc -k -l 4444
NOTA: El comando usa la utilidad NetCat. Puedes usar la utilidad que prefieras. -
Ve al siguiente URI, en el que
DESKTOP_CLIENT_ID
es el ID de cliente de la app para computadoras:https://accounts.google.com/o/oauth2/v2/auth?client_id=DESKTOP_CLIENT_ID&response_type=code&scope=openid%20email&access_type=offline&redirect_uri=http://localhost:4444&cred_ref=true
-
En el resultado del servidor local, busca los parámetros de la solicitud. Deberías ver
algo como lo siguiente:
GET /?code=$CODE&scope=email%20openid%20https://www.googleapis.com/auth/userinfo.email&hd=google.com&prompt=consent HTTP/1.1
Copia el CODE para reemplazarAUTH_CODE
a continuación junto con el ID y el secreto de cliente de la app para computadoras:curl --verbose \ --data client_id=DESKTOP_CLIENT_ID \ --data client_secret=DESKTOP_CLIENT_SECRET \ --data code=AUTH_CODE \ --data redirect_uri=http://localhost:4444 \ --data grant_type=authorization_code \ https://oauth2.googleapis.com/token
Este código muestra un objeto JSON con un campo
id_token
que puedes usar para acceder a la aplicación.
Accede a la aplicación
Para acceder a la app, usa el id_token
de la siguiente manera:
curl --verbose --header 'Authorization: Bearer ID_TOKEN' URL
Token de actualización
Puedes usar el token de actualización que se generó durante el flujo de acceso para obtener tokens de ID nuevos. Esto es útil cuando vence el token de ID original. Cada token de ID es válido por alrededor de una hora, durante la cual puedes realizar varias solicitudes a una app específica.
El siguiente es un ejemplo que utiliza curl para utilizar el token de actualización y obtener un token de ID nuevo. En el siguiente ejemplo, REFRESH_TOKEN
es el token del flujo de acceso.
DESKTOP_CLIENT_ID
y DESKTOP_CLIENT_SECRET
son los mismos que se usan en el flujo de acceso:
curl --verbose \ --data client_id=DESKTOP_CLIENT_ID \ --data client_secret=DESKTOP_CLIENT_SECRET \ --data refresh_token=REFRESH_TOKEN \ --data grant_type=refresh_token \ https://oauth2.googleapis.com/token
Este código muestra un objeto JSON con un nuevo campo id_token
que puedes usar para acceder a la app.
Autentica una cuenta de servicio
Puedes usar un JWT de cuenta de servicio o un token de OpenID Connect (OIDC) para autenticar una cuenta de servicio con un recurso protegido con IAP. En la siguiente tabla, se describen algunas de las diferencias entre los distintos tokens de autenticación y sus características.
Funciones de Authentication | JWT de la cuenta de servicio | Token de OpenID Connect |
---|---|---|
Compatibilidad con el acceso adaptado al contexto | ||
Requisito de ID de cliente de OAuth 2.0 | ||
Alcance del token | URL del recurso protegido con IAP | ID de cliente de OAuth 2.0 |
Autentica con un JWT de cuenta de servicio
La autenticación de una cuenta de servicio con un JWT consta de los siguientes pasos principales:
Otorga a la cuenta de servicio de llamadas el rol Creador de tokens de cuentas de servicio (
roles/iam.serviceAccountTokenCreator
).El rol da permiso a las principales para crear credenciales de corta duración, como JWT.
Crea un JWT para el recurso protegido con IAP.
Firma el JWT con la clave privada de la cuenta de servicio.
Crea el JWT
El JWT creado debería tener una carga útil similar a la del ejemplo siguiente:
{ "iss": SERVICE_ACCOUNT_EMAIL_ADDRESS, "sub": SERVICE_ACCOUNT_EMAIL_ADDRESS, "aud": TARGET_URL, "iat": IAT, "exp": EXP, }
En los campos
iss
ysub
, especifica la dirección de correo electrónico de la cuenta de servicio. Se encuentra en el campoclient_email
del archivo JSON de la cuenta de servicio o se pasa. Formato habitual:service-account@PROJECT_ID.iam.gserviceaccount.com
En el campo
aud
, especifica la URL del recurso protegido con IAP.En el campo
iat
, especifica el tiempo Unix actual y en el campoexp
, especifica una hora dentro de los 3, 600 segundos más tarde. Esto define cuándo vence el JWT.
Firma el JWT
Puedes usar uno de los siguientes métodos para firmar el JWT:
- Usar la API de credenciales de IAM para firmar un JWT sin solicitar acceso directo a una clave privada
- Usar un archivo de claves de credenciales local para firmar el JWT localmente.
Firma el JWT con la API de credenciales de la cuenta de servicio de IAM
Usa la API de credenciales de la cuenta de servicio de IAM para firmar el JWT de una cuenta de servicio. El método recupera la clave privada asociada con tu cuenta de servicio y la usa para firmar la carga útil de JWT. Esto permite la firma de un JWT sin acceso directo a una clave privada.
Para autenticarte en IAP, 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.
gcloud
Ejecuta el siguiente comando para preparar una solicitud con la carga útil de JWT:
cat > claim.json << EOM { "iss": "SERVICE_ACCOUNT_EMAIL_ADDRESS", "sub": "SERVICE_ACCOUNT_EMAIL_ADDRESS", "aud": "TARGET_URL", "iat": $(date +%s), "exp": $((`date +%s` + 3600)) } EOM
Usa el siguiente comando de Google Cloud CLI para firmar la carga útil en
request.json
:gcloud iam service-accounts sign-jwt --iam-account=SERVICE_ACCOUNT_EMAIL_ADDRESS claim.json output.jwt
Si la solicitud se procesa correctamente,
output.jwt
contiene un JWT firmado.Usa el JWT para acceder a tu recurso protegido con IAP.
Python
import datetime
import json
import google.auth
from google.cloud import iam_credentials_v1
import jwt
def generate_jwt_payload(service_account_email: str, resource_url: str) -> str:
"""Generates JWT payload for service account.
The resource url provided must be the same as the url of the IAP secured resource.
Args:
service_account_email (str): Specifies service account JWT is created for.
resource_url (str): Specifies scope of the JWT, the URL that the JWT will be allowed to access.
Returns:
A signed-jwt that can be used to access IAP protected applications.
Access the application with the JWT in the Authorization Header.
curl --verbose --header 'Authorization: Bearer SIGNED_JWT' URL
"""
iat = datetime.datetime.now(tz=datetime.timezone.utc)
exp = iat + 3600
return json.dumps({
'iss': service_account_email,
'sub': service_account_email,
'aud': resource_url,
'iat': iat,
'exp': exp,
})
def sign_jwt(target_sa: str, resource_url: str) -> str:
"""Signs JWT payload using ADC and IAM credentials API.
Args:
target_sa (str): Service Account JWT is being created for.
iap.webServiceVersions.accessViaIap permission is required.
resource_url (str): Audience of the JWT, and scope of the JWT token.
This is the url of the IAP protected application.
Returns:
A signed-jwt that can be used to access IAP protected apps.
"""
source_credentials, _ = google.auth.default()
iam_client = iam_credentials_v1.IAMCredentialsClient(credentials=source_credentials)
return iam_client.sign_jwt(
name=iam_client.service_account_path('-', target_sa),
payload=generate_jwt_payload(target_sa, resource_url),
).signed_jwt
Si la solicitud es exitosa, la secuencia de comandos mostrará un JWT firmado. Usa el JWT para acceder a tu recurso protegido con IAP.
curl
Ejecuta el siguiente comando para preparar una solicitud con la carga útil de JWT:
cat << EOF > request.json { "payload": JWT_PAYLOAD } EOF
Firma el JWT con la API de credenciales de la cuenta de servicio de IAM:
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -d @request.json \ "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL_ADDRESS:signJwt"
Si la solicitud es exitosa, aparecerá un JWT firmado en la respuesta.
Usa el JWT para acceder a tu recurso protegido con IAP.
Firma el JWT desde un archivo de claves de credenciales local
Los JWT se firman con la clave privada de la cuenta de servicio.
Si tienes un archivo de claves de cuenta de servicio, el JWT se puede firmar de forma local.
La secuencia de comandos envía un encabezado JWT junto con la carga útil. En el campo kid
del encabezado, usa el ID de la clave privada de la cuenta de servicio, que se encuentra en el campo private_key_id
del archivo JSON de credenciales de la cuenta de servicio.
La clave también se usa para firmar el JWT.
Python
import time
import jwt
import json
def generate_jwt_payload(service_account_email, resource_url):
"""Generates JWT payload for service account.
The resource url provided must be the same as the url of the IAP secured resource.
Args:
service_account_email (str): Specifies service account JWT is created for.
resource_url (str): Specifies scope of the JWT, the URL that the JWT will be allowed to access.
Returns:
A signed-jwt that can be used to access IAP protected applications.
Access the application with the JWT in the Authorization Header.
curl --verbose --header 'Authorization: Bearer SIGNED_JWT' URL
"""
iat = datetime.datetime.now(tz=datetime.timezone.utc)
exp = iat + 3600
return json.dumps({
'iss': service_account_email,
'sub': service_account_email,
'aud': resource_url,
'iat': iat,
'exp': exp,
})
def sign_jwt_with_key_file(credential_key_file_path, resource_url):
"""Signs JWT payload using local service account credential key file.
Args:
credential_key_file_path (str): Path to the downloaded JSON credentials of the service
account the JWT is being created for.
resource_url (str): Scope of JWT token, This is the url of the IAP protected application.
Returns:
A service account JWT created with a downloaded private key.
"""
with open(credential_key_file_path, 'r') as credential_key_file:
key_data = json.load(credential_key_file)
PRIVATE_KEY_ID_FROM_JSON = key_data["private_key_id"]
PRIVATE_KEY_FROM_JSON = key_data["private_key"]
SERVICE_ACCOUNT_EMAIL = key_data["client_email"]
# Sign JWT with private key and store key id in the header
additional_headers = {'kid': PRIVATE_KEY_ID_FROM_JSON}
payload = generate_jwt_payload(service_account_email=SERVICE_ACCOUNT_EMAIL, resource_url=resource_url)
signed_jwt = jwt.encode(
payload,
PRIVATE_KEY_FROM_JSON,
headers=additional_headers,
algorithm='RS256',
)
return signed_jwt
Un JWT firmado es el resultado.
Accede a la aplicación
En todos los casos, para acceder a la app, usa el signed-jwt
de la siguiente manera:
curl --verbose --header 'Authorization: Bearer SIGNED_JWT' URL
Autenticar con un token de OIDC
- Crea o usa un ID de cliente de OAuth 2.0 existente. Para usar un ID de cliente de OAuth 2.0 existente, sigue los pasos que se indican en Cómo compartir clientes de OAuth.
- Incluye en la lista de entidades permitidas el ID de cliente de OAuth para el acceso programático de la aplicación.
También debes agregar la cuenta de servicio a la lista de acceso del proyecto protegido con IAP. En las siguientes muestras de código, se indica cómo obtener un token de OIDC. Debes incluir el token en un encabezado Authorization: Bearer
para realizar la solicitud de autenticación al recurso protegido con IAP.
Obtén un token de OIDC para la cuenta de servicio predeterminada
Si quieres obtener un token de OIDC para la cuenta de servicio predeterminada de Compute Engine, App Engine o Cloud Run, puedes usar la siguiente muestra de código para generar el token y acceder a un recurso protegido con IAP:
C#
Go
Para autenticarte en IAP, 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.
Java
Node.js
PHP
Para autenticarte en IAP, 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.
Python
Para autenticarte en IAP, 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.
Ruby
Para autenticarte en IAP, 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.
Obtén un token de OIDC de un archivo de claves de cuenta de servicio local
Si tienes un archivo de claves de cuenta de servicio, puedes adaptar las muestras de código anteriores para proporcionar ese archivo.
Bash
#!/usr/bin/env bash
set -euo pipefail
get_token() {
# Get the bearer token in exchange for the service account credentials.
local service_account_key_file_path="${1}"
local iap_client_id="${2}"
local iam_scope="https://www.googleapis.com/auth/iam"
local oauth_token_uri="https://www.googleapis.com/oauth2/v4/token"
local private_key_id="$(cat "${service_account_key_file_path}" | jq -r '.private_key_id')"
local client_email="$(cat "${service_account_key_file_path}" | jq -r '.client_email')"
local private_key="$(cat "${service_account_key_file_path}" | jq -r '.private_key')"
local issued_at="$(date +%s)"
local expires_at="$((issued_at + 600))"
local header="{'alg':'RS256','typ':'JWT','kid':'${private_key_id}'}"
local header_base64="$(echo "${header}" | base64)"
local payload="{'iss':'${client_email}','aud':'${oauth_token_uri}','exp':${expires_at},'iat':${issued_at},'sub':'${client_email}','target_audience':'${iap_client_id}'}"
local payload_base64="$(echo "${payload}" | base64)"
local signature_base64="$(printf %s "${header_base64}.${payload_base64}" | openssl dgst -binary -sha256 -sign <(printf '%s\n' "${private_key}") | base64)"
local assertion="${header_base64}.${payload_base64}.${signature_base64}"
local token_payload="$(curl -s \
--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
--data-urlencode "assertion=${assertion}" \
https://www.googleapis.com/oauth2/v4/token)"
local bearer_id_token="$(echo "${token_payload}" | jq -r '.id_token')"
echo "${bearer_id_token}"
}
main(){
# TODO: Replace the following variables:
SERVICE_ACCOUNT_KEY="service_account_key_file_path"
IAP_CLIENT_ID="iap_client_id"
URL="application_url"
# Obtain the ID token.
ID_TOKEN=$(get_token "${SERVICE_ACCOUNT_KEY}" "${IAP_CLIENT_ID}")
# Access the application with the ID token.
curl --header "Authorization: Bearer ${ID_TOKEN}" "${URL}"
}
main "$@"
Obtener un token de OIDC en todos los demás casos
En todos los demás casos, usa la API de credenciales de IAM para generar un token de OIDC mediante la suplantación de la identidad de una cuenta de servicio de destino justo antes de acceder a un recurso protegido con IAP. Este proceso implica los siguientes pasos:
Proporciona la cuenta de servicio de llamadas (la cuenta de servicio asociada con el código que obtiene el token de ID) con el rol de creador de tokens de OpenID Connect Identity de la cuenta de servicio (
roles/iam.serviceAccountOpenIdTokenCreator
).Esto le brinda a la cuenta de servicio de llamadas la capacidad de usar la identidad de la cuenta de servicio de destino.
Usa las credenciales proporcionadas por la cuenta de servicio de llamadas para llamar al método generateIdToken en la cuenta de servicio de destino.
Establece el campo
audience
con tu ID de cliente.
Para obtener instrucciones paso a paso, consulta Crea un token de ID.
Autenticación desde el encabezado de autorización del proxy
Si tu aplicación usa el encabezado de la solicitud Authorization
, puedes incluir el token de ID en un encabezado Proxy-Authorization: Bearer
. Si se encuentra un token de ID válido en un encabezado Proxy-Authorization
, IAP autoriza la solicitud con él. Después de autorizar la solicitud, IAP pasa el encabezado Authorization
a tu aplicación sin procesar el contenido.
Si no se encuentra un token de ID válido en el encabezado Proxy-Authorization
, IAP continúa procesando el encabezado Authorization
y quita el encabezado Proxy-Authorization
antes de pasar la solicitud a la aplicación.
¿Qué sigue?
- Obtén más información sobre el token del portador de autorización.
- Intenta acceder a Android o acceder a iOS.