Cette page explique comment s'authentifier auprès d'une ressource sécurisée par Identity-Aware Proxy (IAP) avec un compte utilisateur ou un compte de service.
L'accès programmatique correspond au scénario dans lequel vous appelez des applications protégées par IAP à partir de clients autres que des navigateurs. Cela inclut les outils de ligne de commande, les appels de service à service et les applications mobiles. Selon votre cas d'utilisation, vous pouvez vous authentifier auprès de l'IAP à l'aide d'identifiants utilisateur ou d'identifiants de service.
Un compte utilisateur appartient à un utilisateur individuel. Vous authentifiez un compte utilisateur lorsque votre application doit accéder à des ressources sécurisées par IAP au nom d'un utilisateur. Pour en savoir plus, consultez Comptes utilisateur.
Un compte de service représente une application et non un utilisateur individuel. Vous authentifiez un compte de service lorsque vous souhaitez autoriser une application à accéder à vos ressources sécurisées par IAP. Pour en savoir plus, consultez la page Comptes de service.
L'API IAP est compatible avec les types d'identifiants suivants pour l'accès programmatique:
- Jeton d'ID OAuth 2.0 : jeton émis par Google pour un utilisateur ou un compte de service humain, dont la revendication d'audience est définie sur l'ID de ressource de l'application IAP.
- JWT signé par un compte de service : jeton JWT autosigné ou émis par Google pour un compte de service.
Transmettez ces identifiants à l'IAP dans l'en-tête HTTP Authorization
ou Proxy-Authorization
.
Avant de commencer
Avant de commencer, vous devez disposer d'une application sécurisée par IAP à laquelle vous souhaitez vous connecter de manière automatisée à l'aide d'un compte de développeur, d'un compte de service ou d'identifiants d'application mobile.
Authentifier un compte utilisateur
Vous pouvez activer l'accès des utilisateurs à votre application depuis une application mobile ou de bureau afin de permettre à un programme d'interagir avec une ressource sécurisée par IAP.
S'authentifier à partir d'une application mobile
- Créez ou utilisez un ID client OAuth 2.0 existant pour votre application mobile. Pour utiliser un ID client OAuth 2.0 existant, suivez la procédure décrite dans la section Partager des clients OAuth. Ajoutez l'ID client OAuth à la liste d'autorisation pour l'accès programmatique de l'application.
- Obtenez un jeton d'ID pour l'ID client sécurisé par IAP.
- Android: demandez un jeton OpenID Connect (OIDC) à l'aide de l'API Google Sign-In. Définissez l'ID client
requestIdToken
sur celui de la ressource à laquelle vous vous connectez. - iOS : utilisez Google Sign-In pour obtenir un jeton d'ID.
- Android: demandez un jeton OpenID Connect (OIDC) à l'aide de l'API Google Sign-In. Définissez l'ID client
- Incluez le jeton d'ID dans un en-tête
Authorization: Bearer
pour envoyer la requête authentifiée à la ressource sécurisée par IAP.
S'authentifier à partir d'une application de bureau
Cette section décrit comment authentifier un compte utilisateur à partir d'une ligne de commande d'ordinateur de bureau.
- Pour permettre aux développeurs d'accéder à votre application à partir de la ligne de commande, créez un ID client OAuth 2.0 pour ordinateur ou partagez un ID client OAuth pour ordinateur existant.
- Ajoutez l'ID OAuth à la liste d'autorisation pour l'accès programmatique de l'application.
Se connecter à l'application
Chaque développeur souhaitant accéder à une application sécurisée par IAP doit d'abord se connecter. Vous pouvez intégrer le processus dans un script, par exemple à l'aide de la CLI gcloud. L'exemple suivant utilise curl pour se connecter et générer un jeton permettant d'accéder à l'application:
- Connectez-vous à votre compte ayant accès à la ressource Google Cloud .
Démarrez un serveur local capable d'émettre un écho des requêtes entrantes.
# Example using Netcat (http://netcat.sourceforge.net/) nc -k -l 4444
Accédez à l'URI suivant, où
DESKTOP_CLIENT_ID
correspond à l'ID client de l'application de bureau: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
Dans la sortie du serveur local, recherchez les paramètres de requête:
GET /?code=CODE&scope=email%20openid%20https://www.googleapis.com/auth/userinfo.email&hd=google.com&prompt=consent HTTP/1.1
Copiez la valeur CODE pour remplacer
AUTH_CODE
dans la commande suivante, ainsi que l'ID client et le secret de l'application de bureau:curl --verbose \ --data client_id=DESKTOP_CLIENT_ID \ --data client_secret=DESKTOP_CLIENT_SECRET \ --data code=CODE \ --data redirect_uri=http://localhost:4444 \ --data grant_type=authorization_code \ https://oauth2.googleapis.com/token
Cette commande renvoie un objet JSON avec un champ
id_token
que vous pouvez utiliser pour accéder à l'application.
Accéder à l'application
Pour accéder à l'application, utilisez id_token
:
curl --verbose --header 'Authorization: Bearer ID_TOKEN' URL
Jeton d'actualisation
Vous pouvez utiliser le jeton d'actualisation généré lors du flux de connexion pour obtenir de nouveaux jetons d'ID. Cela peut être utile lorsque le jeton d'ID d'origine expire. Chaque jeton d'ID est valide pendant environ une heure, période au cours de laquelle vous pouvez envoyer plusieurs requêtes à une application spécifique.
L'exemple suivant utilise curl pour utiliser le jeton d'actualisation afin d'obtenir un nouveau jeton d'ID.
Dans cet exemple, REFRESH_TOKEN
correspond au jeton du flux de connexion.
DESKTOP_CLIENT_ID
et DESKTOP_CLIENT_SECRET
sont les mêmes que ceux utilisés dans le flux de connexion:
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
Cette commande renvoie un objet JSON avec un nouveau champ id_token
que vous pouvez utiliser pour accéder à l'application.
Authentifier un compte de service
Vous pouvez utiliser un jeton JWT de compte de service ou un jeton OpenID Connect (OIDC) pour authentifier un compte de service avec une ressource sécurisée par IAP. Le tableau suivant décrit certaines des différences entre les différents jetons d'authentification et leurs fonctionnalités.
Fonctionnalités d'authentification | JWT du compte de service | Jeton OpenID Connect |
---|---|---|
Compatibilité de l'accès contextuel | ||
Exigence concernant l'ID client OAuth 2.0 | ||
Champ d'application du jeton | URL de la ressource sécurisée par IAP | ID client OAuth 2.0 |
S'authentifier avec un jeton JWT de compte de service
L'API IAP est compatible avec l'authentification JWT du compte de service pour les applications configurées pour les identités Google, Identity Platform et la fédération des identités des employés.
L'authentification d'un compte de service à l'aide d'un jeton JWT comprend les étapes principales suivantes:
Attribuez au compte de service appelant le rôle Créateur de jetons du compte de service (
roles/iam.serviceAccountTokenCreator
).Ce rôle permet aux comptes principaux de créer des identifiants éphémères, comme des jetons JWT.
Créez un JWT pour la ressource sécurisée par IAP.
Signez le jeton JWT à l'aide de la clé privée du compte de service.
Créer le jeton JWT
Le JWT créé doit avoir une charge utile semblable à l'exemple suivant:
{
"iss": SERVICE_ACCOUNT_EMAIL_ADDRESS,
"sub": SERVICE_ACCOUNT_EMAIL_ADDRESS,
"aud": TARGET_URL,
"iat": IAT,
"exp": EXP,
}
Pour les champs
iss
etsub
, spécifiez l'adresse e-mail du compte de service. Vous le trouverez dans le champclient_email
du fichier JSON du compte de service ou transmis. Format type :service-account@PROJECT_ID.iam.gserviceaccount.com
Pour le champ
aud
, spécifiez l'URL de la ressource sécurisée par l'IAP.Pour le champ
iat
, spécifiez l'heure actuelle de l'epoch UNIX, et pour le champexp
, spécifiez une heure dans un délai de 3 600 secondes. Il définit la date d'expiration du jeton JWT.
Signature du jeton JWT
Vous pouvez signer le jeton JWT à l'aide de l'une des méthodes suivantes:
- Utilisez l'API IAM Credentials pour signer un jeton JWT sans avoir besoin d'un accès direct à une clé privée.
- Utilisez un fichier de clé d'identifiants locaux pour signer le jeton JWT localement.
Signature du jeton JWT à l'aide de l'API IAM Service Account Credentials
Utilisez l'API IAM Service Account Credentials pour signer un jeton JWT de compte de service. La méthode récupère la clé privée associée à votre compte de service et l'utilise pour signer la charge utile JWT. Cela permet de signer un jeton JWT sans accès direct à une clé privée.
Pour vous authentifier auprès de l'IAP, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
gcloud
- Exécutez la commande suivante pour préparer une requête avec la charge utile 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
- Utilisez la commande Google Cloud CLI suivante pour signer la charge utile dans
claim.json
:
gcloud iam service-accounts sign-jwt --iam-account="SERVICE_ACCOUNT_EMAIL_ADDRESS" claim.json output.jwt
Une fois la requête effectuée, output.jwt
contient un jeton JWT signé que vous pouvez utiliser pour accéder à votre ressource sécurisée par IAP.
Python
import datetime
import json
import google.auth
from google.cloud import iam_credentials_v1
def generate_jwt_payload(service_account_email: str, resource_url: str) -> str:
"""Generates JWT payload for service account.
Creates a properly formatted JWT payload with standard claims (iss, sub, aud,
iat, exp) needed for IAP authentication.
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:
str: JSON string containing the JWT payload with properly formatted claims.
"""
# Create current time and expiration time (1 hour later) in UTC
iat = datetime.datetime.now(tz=datetime.timezone.utc)
exp = iat + datetime.timedelta(seconds=3600)
# Convert datetime objects to numeric timestamps (seconds since epoch)
# as required by JWT standard (RFC 7519)
payload = {
"iss": service_account_email,
"sub": service_account_email,
"aud": resource_url,
"iat": int(iat.timestamp()),
"exp": int(exp.timestamp()),
}
return json.dumps(payload)
def sign_jwt(target_sa: str, resource_url: str) -> str:
"""Signs JWT payload using ADC and IAM credentials API.
Uses Google Cloud's IAM Credentials API to sign a JWT. This requires the
caller to have iap.webServiceVersions.accessViaIap permission on the target
service account.
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:
str: A signed JWT that can be used to access IAP protected apps.
Use in Authorization header as: 'Bearer <signed_jwt>'
"""
# Get default credentials from environment or application credentials
source_credentials, project_id = google.auth.default()
# Initialize IAM credentials client with source credentials
iam_client = iam_credentials_v1.IAMCredentialsClient(credentials=source_credentials)
# Generate the service account resource name
# If project_id is None, use '-' as placeholder as per API requirements
project = project_id if project_id else "-"
name = iam_client.service_account_path(project, target_sa)
# Create and sign the JWT payload
payload = generate_jwt_payload(target_sa, resource_url)
# Sign the JWT using the IAM credentials API
response = iam_client.sign_jwt(name=name, payload=payload)
return response.signed_jwt
curl
Exécutez la commande suivante pour préparer une requête avec la charge utile JWT:
cat << EOF > request.json { "payload": JWT_PAYLOAD } EOF
Signer le jeton JWT à l'aide d'IAM
API Service Account Credentials:
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"
Une fois la requête réussie, un jeton JWT signé est renvoyé dans la réponse.
Utilisez le jeton JWT pour accéder à votre ressource sécurisée par IAP.
Signature du jeton JWT à partir d'un fichier de clé d'identifiants local
Les jetons JWT sont signés à l'aide de la clé privée du compte de service.
Si vous disposez d'un fichier de clé de compte de service, le jeton JWT peut être signé en local.
Le script envoie un en-tête JWT avec la charge utile. Pour le champ kid
de l'en-tête, utilisez l'ID de clé privée du compte de service, qui se trouve dans le champ private_key_id
du fichier JSON des identifiants du compte de service.
La clé est également utilisée pour signer le jeton JWT.
Accéder à l'application
Dans tous les cas, pour accéder à l'application, utilisez signed-jwt
:
curl --verbose --header 'Authorization: Bearer SIGNED_JWT' URL
S'authentifier avec un jeton OIDC
- Créez ou utilisez un ID client OAuth 2.0 existant. Pour utiliser un ID client OAuth 2.0 existant, suivez la procédure décrite dans la section Partager des clients OAuth.
- Ajoutez l'ID OAuth à la liste d'autorisation pour l'accès programmatique de l'application.
- Assurez-vous que le compte de service par défaut est ajouté à la liste d'accès du projet sécurisé par IAP.
Lorsque vous envoyez des requêtes à la ressource sécurisée par IAP, vous devez inclure le jeton dans l'en-tête Authorization
: Authorization: 'Bearer OIDC_TOKEN'
Les exemples de code suivants montrent comment obtenir un jeton OIDC.
Obtenir un jeton OIDC pour le compte de service par défaut
Pour obtenir un jeton OIDC pour le compte de service par défaut pour Compute Engine, App Engine ou Cloud Run, consultez l'exemple de code suivant pour générer un jeton permettant d'accéder à une ressource sécurisée par IAP:
C#
Pour vous authentifier auprès de l'IAP, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Go
Pour vous authentifier auprès d'IAP, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Java
Pour vous authentifier auprès d'IAP, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Node.js
Pour vous authentifier auprès d'IAP, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
PHP
Pour vous authentifier auprès d'IAP, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Python
Pour vous authentifier auprès d'IAP, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Ruby
Pour vous authentifier auprès d'IAP, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Obtenir un jeton OIDC à partir d'un fichier de clé de compte de service local
Pour générer un jeton OIDC à l'aide d'un fichier de clé de compte de service, vous devez utiliser le fichier de clé pour créer et signer une assertion JWT, puis échanger cette assertion contre un jeton d'ID. Le script Bash suivant illustre ce processus:
Bash
#!/usr/bin/env bash
#
# Example script that generates an OIDC token using a service account key file
# and uses it to access an IAP-secured resource
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}"
# Define the scope and token endpoint
local iam_scope="https://www.googleapis.com/auth/iam"
local oauth_token_uri="https://www.googleapis.com/oauth2/v4/token"
# Extract data from service account key file
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')"
# Set token timestamps (current time and expiration 10 minutes later)
local issued_at="$(date +%s)"
local expires_at="$((issued_at + 600))"
# Create JWT header and payload
local header="{'alg':'RS256','typ':'JWT','kid':'${private_key_id}'}"
local header_base64="$(echo "${header}" | base64 | tr -d '\n')"
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 | tr -d '\n')"
# Create JWT signature using the private key
local signature_base64="$(printf %s "${header_base64}.${payload_base64}" | openssl dgst -binary -sha256 -sign <(printf '%s\n' "${private_key}") | base64 | tr -d '\n')"
local assertion="${header_base64}.${payload_base64}.${signature_base64}"
# Exchange the signed JWT assertion for an ID token
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)"
# Extract just the ID token from the response
local bearer_id_token="$(echo "${token_payload}" | jq -r '.id_token')"
echo "${bearer_id_token}"
}
main() {
# Check if required arguments are provided
if [[ $# -lt 3 ]]; then
echo "Usage: $0 <service_account_key_file.json> <iap_client_id> <url>"
exit 1
fi
# Assign parameters to variables
SERVICE_ACCOUNT_KEY="$1"
IAP_CLIENT_ID="$2"
URL="$3"
# Generate the ID token
echo "Generating token..."
ID_TOKEN=$(get_token "${SERVICE_ACCOUNT_KEY}" "${IAP_CLIENT_ID}")
# Access the IAP-secured resource with the token
echo "Accessing: ${URL}"
curl --header "Authorization: Bearer ${ID_TOKEN}" "${URL}"
}
# Run the main function with all provided arguments
main "$@"
Ce script effectue les tâches suivantes:
- Extraction des informations de clé de compte de service à partir de votre fichier de clé JSON
- Crée un jeton JWT avec les champs nécessaires, y compris l'ID client de l'IAP en tant qu'audience cible.
- Signe le jeton JWT à l'aide de la clé privée du compte de service
- Échange ce JWT contre un jeton OIDC via le service OAuth de Google
- Utilise le jeton obtenu pour envoyer une requête authentifiée à votre ressource sécurisée par IAP.
Pour utiliser ce script:
- Enregistrez-le dans un fichier, par exemple:
get_iap_token.sh
. - Rendez-le exécutable:
chmod +x get_iap_token.sh
- Exécutez-la avec trois paramètres:
./get_iap_token.sh service-account-key.json \
OAUTH_CLIENT_ID \
URL
Où :
service-account-key.json
est le fichier de clé de compte de service que vous avez téléchargé.- OAUTH_CLIENT_ID est l'ID client OAuth de votre ressource sécurisée par IAP.
- URL est l'URL à laquelle vous souhaitez accéder.
Obtenir un jeton OIDC dans tous les autres cas
Dans tous les autres cas, utilisez l'API des identifiants IAM pour générer un jeton OIDC en usurpant l'identité d'un compte de service cible juste avant d'accéder à une ressource sécurisée par IAP. Ce processus comprend les étapes suivantes:
Attribuez au compte de service appelant (le compte de service associé au code qui obtient le jeton d'ID) le rôle Créateur de jetons d'identité OpenID Connect du compte de service (
roles/iam.serviceAccountOpenIdTokenCreator
).Cela permet au compte de service appelant d'usurper l'identité du compte de service cible.
Utilisez les identifiants fournis par le compte de service appelant pour appeler la méthode generateIdToken sur le compte de service cible.
Définissez le champ
audience
sur votre ID client.
Pour obtenir des instructions détaillées, consultez la section Créer un jeton d'ID.
Authentifier à partir de l'en-tête Proxy-Authorization
Si votre application utilise l'en-tête de requête Authorization
, vous pouvez inclure le jeton d'ID dans un en-tête Proxy-Authorization: Bearer
à la place. Si un jeton d'ID valide est détecté dans un en-tête Proxy-Authorization
, IAP autorise la requête avec celui-ci. Après avoir autorisé la requête, l'IAP transmet l'en-tête Authorization
à votre application sans traiter le contenu.
Si aucun jeton d'ID valide n'est trouvé dans l'en-tête Proxy-Authorization
, l'IAP continue de traiter l'en-tête Authorization
et supprime l'en-tête Proxy-Authorization
avant de transmettre la requête à votre application.
Étapes suivantes
- En savoir plus sur l'autorisation avec les jetons de support
- Essayez Sign-In pour Android ou Sign-In pour iOS.