Halaman ini menjelaskan cara melakukan autentikasi ke resource yang diamankan oleh Identity-Aware Proxy (IAP) dari akun pengguna atau akun layanan.
Akses terprogram adalah skenario saat Anda memanggil aplikasi yang dilindungi IAP dari klien non-browser. Hal ini mencakup alat command line, panggilan layanan ke layanan, dan aplikasi seluler. Bergantung pada kasus penggunaan, Anda mungkin ingin mengautentikasi ke IAP menggunakan kredensial pengguna atau kredensial layanan.
Akun pengguna adalah milik pengguna individual. Anda mengautentikasi akun pengguna saat aplikasi Anda memerlukan akses ke resource yang diamankan IAP atas nama pengguna. Untuk mengetahui informasi selengkapnya, lihat Akun pengguna.
Akun layanan mewakili aplikasi, bukan pengguna individu. Anda mengautentikasi akun layanan saat ingin mengizinkan aplikasi mengakses resource yang diamankan oleh IAP. Untuk mengetahui informasi selengkapnya, lihat Akun layanan.
IAP mendukung jenis kredensial berikut untuk akses terprogram:
- Token ID OAuth 2.0 - Token yang diterbitkan Google untuk pengguna manusia atau akun layanan dengan klaim audiens yang ditetapkan ke ID resource aplikasi IAP.
- JWT yang ditandatangani akun layanan - Token JWT yang ditandatangani sendiri atau dikeluarkan Google untuk akun layanan.
Teruskan kredensial ini ke IAP di header HTTP Authorization
atau
Proxy-Authorization
.
Sebelum memulai
Sebelum memulai, Anda memerlukan aplikasi yang diamankan IAP yang ingin dihubungkan secara terprogram menggunakan akun developer, akun layanan, atau kredensial aplikasi seluler.
Mengautentikasi akun pengguna
Anda dapat mengaktifkan akses pengguna ke aplikasi dari aplikasi desktop atau seluler untuk mengizinkan program berinteraksi dengan resource yang diamankan IAP.
Melakukan autentikasi dari aplikasi seluler
- Buat atau gunakan client ID OAuth 2.0 yang ada untuk aplikasi seluler Anda. Untuk menggunakan client ID OAuth 2.0 yang ada, ikuti langkah-langkah di Cara membagikan Klien OAuth. Tambahkan client ID OAuth ke daftar yang diizinkan untuk akses terprogram untuk aplikasi.
- Mendapatkan token ID untuk client ID yang diamankan IAP.
- Android: Gunakan
Google Sign-In API
untuk meminta
token
OpenID Connect
(OIDC). Tetapkan
client ID
requestIdToken
ke client ID untuk resource yang Anda hubungkan. - iOS: Gunakan Login dengan Google untuk mendapatkan token ID.
- Android: Gunakan
Google Sign-In API
untuk meminta
token
OpenID Connect
(OIDC). Tetapkan
client ID
- Sertakan token ID di header
Authorization: Bearer
untuk membuat permintaan yang diautentikasi ke resource yang diamankan IAP.
Melakukan autentikasi dari aplikasi desktop
Bagian ini menjelaskan cara mengautentikasi akun pengguna dari command line desktop.
- Untuk mengizinkan developer mengakses aplikasi Anda dari command line, buat client ID OAuth 2.0 desktop atau bagikan client ID OAuth desktop yang ada.
- Tambahkan ID OAuth ke daftar yang diizinkan untuk akses terprogram untuk aplikasi.
Login ke aplikasi
Setiap developer yang ingin mengakses aplikasi yang diamankan IAP harus login terlebih dahulu. Anda dapat memaketkan proses ke dalam skrip, seperti dengan menggunakan gcloud CLI. Contoh berikut menggunakan curl untuk login dan membuat token yang dapat digunakan untuk mengakses aplikasi:
- Login ke akun Anda yang memiliki akses ke Google Cloud resource.
Mulai server lokal yang dapat mengulang permintaan masuk.
# Example using Netcat (http://netcat.sourceforge.net/) nc -k -l 4444
Buka URI berikut, dengan
DESKTOP_CLIENT_ID
adalah client ID aplikasi Desktop: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
Di output server lokal, cari parameter permintaan:
GET /?code=CODE&scope=email%20openid%20https://www.googleapis.com/auth/userinfo.email&hd=google.com&prompt=consent HTTP/1.1
Salin nilai CODE untuk mengganti
AUTH_CODE
dalam perintah berikut, beserta client ID dan secret Aplikasi desktop: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
Perintah ini menampilkan objek JSON dengan kolom
id_token
yang dapat Anda gunakan untuk mengakses aplikasi.
Mengakses aplikasi
Untuk mengakses aplikasi, gunakan id_token
:
curl --verbose --header 'Authorization: Bearer ID_TOKEN' URL
Token refresh
Anda dapat menggunakan token refresh yang dibuat selama alur login untuk mendapatkan token ID baru. Hal ini berguna saat masa berlaku token ID asli berakhir. Setiap token ID berlaku selama sekitar satu jam, selama waktu tersebut Anda dapat membuat beberapa permintaan ke aplikasi tertentu.
Contoh berikut menggunakan curl untuk menggunakan token refresh guna mendapatkan token ID baru.
Dalam contoh ini, REFRESH_TOKEN
adalah token dari alur login.
DESKTOP_CLIENT_ID
dan DESKTOP_CLIENT_SECRET
sama
dengan yang digunakan dalam alur login:
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
Perintah ini menampilkan objek JSON dengan kolom id_token
baru yang
dapat Anda gunakan untuk mengakses aplikasi.
Mengautentikasi akun layanan
Anda dapat menggunakan JWT akun layanan atau token OpenID Connect (OIDC) untuk mengautentikasi akun layanan dengan resource yang diamankan IAP. Tabel berikut menguraikan beberapa perbedaan antara berbagai token autentikasi dan fiturnya.
Fitur Authentication | JWT akun layanan | Token OpenID Connect |
---|---|---|
Dukungan akses kontekstual | ||
Persyaratan Client ID OAuth 2.0 | ||
Cakupan token | URL resource yang diamankan IAP | Client ID OAuth 2.0 |
Melakukan autentikasi dengan JWT akun layanan
IAP mendukung autentikasi JWT akun layanan untuk aplikasi yang dikonfigurasi dengan identitas Google, Identity Platform, dan Workforce Identity Federation.
Mengautentikasi akun layanan menggunakan JWT terdiri dari langkah-langkah utama berikut:
Berikan akun layanan panggilan peran Service Account Token Creator (
roles/iam.serviceAccountTokenCreator
).Peran ini memberi akun utama izin untuk membuat kredensial jangka pendek, seperti JWT.
Buat JWT untuk resource yang diamankan IAP.
Tanda tangani JWT menggunakan kunci pribadi akun layanan.
Membuat JWT
JWT yang dibuat harus memiliki payload yang mirip dengan contoh berikut:
{
"iss": SERVICE_ACCOUNT_EMAIL_ADDRESS,
"sub": SERVICE_ACCOUNT_EMAIL_ADDRESS,
"aud": TARGET_URL,
"iat": IAT,
"exp": EXP,
}
Untuk kolom
iss
dansub
, tentukan alamat email akun layanan. Ini ditemukan di kolomclient_email
file JSON akun layanan, atau diteruskan. Format standar:service-account@PROJECT_ID.iam.gserviceaccount.com
Untuk kolom
aud
, tentukan URL resource yang diamankan IAP.Untuk kolom
iat
, tentukan waktu epoch Unix saat ini, dan untuk kolomexp
, tentukan waktu dalam 3600 detik kemudian. Ini menentukan kapan masa berlaku JWT berakhir.
Menandatangani JWT
Anda dapat menggunakan salah satu metode berikut untuk menandatangani JWT:
- Gunakan API kredensial IAM untuk menandatangani JWT tanpa memerlukan akses langsung ke kunci pribadi.
- Gunakan file kunci kredensial lokal untuk menandatangani JWT secara lokal.
Menandatangani JWT menggunakan IAM Service Account Credentials API
Gunakan IAM Service Account Credentials API untuk menandatangani JWT akun layanan. Metode ini mengambil kunci pribadi yang terkait dengan akun layanan Anda dan menggunakannya untuk menandatangani payload JWT. Hal ini memungkinkan penandatanganan JWT tanpa akses langsung ke kunci pribadi.
Untuk melakukan autentikasi ke IAP, siapkan kredensial default aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
gcloud
- Jalankan perintah berikut untuk menyiapkan permintaan dengan payload 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
- Gunakan perintah Google Cloud CLI berikut untuk menandatangani payload di
claim.json
:
gcloud iam service-accounts sign-jwt --iam-account="SERVICE_ACCOUNT_EMAIL_ADDRESS" claim.json output.jwt
Setelah permintaan berhasil, output.jwt
berisi JWT yang ditandatangani yang dapat Anda gunakan untuk mengakses resource yang diamankan dengan 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
Jalankan perintah berikut untuk menyiapkan permintaan dengan payload JWT:
cat << EOF > request.json { "payload": JWT_PAYLOAD } EOF
Menandatangani JWT menggunakan IAM
Service Account Credentials API:
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"
Setelah permintaan berhasil, JWT yang ditandatangani akan ditampilkan dalam respons.
Gunakan JWT untuk mengakses resource yang diamankan IAP.
Menandatangani JWT dari file kunci kredensial lokal
JWT ditandatangani menggunakan kunci pribadi akun layanan.
Jika Anda memiliki file kunci akun layanan, JWT dapat ditandatangani secara lokal.
Skrip mengirim header JWT beserta payload. Untuk kolom kid
di header, gunakan ID kunci pribadi akun layanan, yang ada di
kolom private_key_id
dari file JSON kredensial akun layanan.
Kunci ini juga digunakan untuk menandatangani JWT.
Mengakses aplikasi
Dalam semua kasus, untuk mengakses aplikasi, gunakan signed-jwt
:
curl --verbose --header 'Authorization: Bearer SIGNED_JWT' URL
Mengautentikasi dengan token OIDC
- Buat atau gunakan client ID OAuth 2.0 yang ada. Untuk menggunakan client ID OAuth 2.0 yang ada, ikuti langkah-langkah di Cara membagikan Klien OAuth.
- Tambahkan ID OAuth ke daftar yang diizinkan untuk akses terprogram untuk aplikasi.
- Pastikan akun layanan default ditambahkan ke daftar akses untuk project yang diamankan IAP.
Saat membuat permintaan ke resource yang diamankan IAP, Anda harus menyertakan token di header Authorization
: Authorization: 'Bearer OIDC_TOKEN'
Contoh kode berikut menunjukkan cara mendapatkan token OIDC.
Mendapatkan token OIDC untuk akun layanan default
Untuk mendapatkan token OIDC untuk akun layanan default Compute Engine, App Engine, atau Cloud Run, lihat contoh kode berikut untuk membuat token guna mengakses resource yang diamankan IAP:
C#
Untuk melakukan autentikasi ke IAP, siapkan kredensial default aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Go
Untuk melakukan autentikasi ke IAP, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Java
Untuk melakukan autentikasi ke IAP, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Node.js
Untuk melakukan autentikasi ke IAP, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
PHP
Untuk melakukan autentikasi ke IAP, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Python
Untuk melakukan autentikasi ke IAP, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Ruby
Untuk melakukan autentikasi ke IAP, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Mendapatkan token OIDC dari file kunci akun layanan lokal
Untuk membuat token OIDC menggunakan file kunci akun layanan, Anda akan menggunakan file kunci untuk membuat dan menandatangani pernyataan JWT, lalu menukar pernyataan tersebut dengan token ID. Skrip Bash berikut menunjukkan proses ini:
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 "$@"
Skrip ini melakukan langkah-langkah berikut:
- Mengekstrak informasi kunci akun layanan dari file kunci JSON Anda
- Membuat JWT dengan kolom yang diperlukan, termasuk client ID IAP sebagai target audiens
- Menandatangani JWT menggunakan kunci pribadi akun layanan
- Menukar JWT ini dengan token OIDC melalui layanan OAuth Google
- Menggunakan token yang dihasilkan untuk membuat permintaan terautentikasi ke resource yang diamankan oleh IAP Anda
Untuk menggunakan skrip ini:
- Simpan ke file, misalnya:
get_iap_token.sh
- Buat agar dapat dieksekusi:
chmod +x get_iap_token.sh
- Jalankan dengan tiga parameter:
./get_iap_token.sh service-account-key.json \
OAUTH_CLIENT_ID \
URL
Dengan keterangan:
service-account-key.json
adalah file kunci akun layanan yang Anda download- OAUTH_CLIENT_ID adalah client ID OAuth untuk resource yang diamankan IAP
- URL adalah URL yang ingin Anda akses
Mendapatkan token OIDC dalam semua kasus lainnya
Dalam semua kasus lainnya, gunakan IAM credentials API untuk membuat token OIDC dengan meniru identitas akun layanan target tepat sebelum mengakses resource yang diamankan IAP. Proses ini melibatkan langkah-langkah berikut:
Berikan akun layanan panggilan (akun layanan yang terkait dengan kode yang mendapatkan token ID) dengan peran Pembuat Token Identitas OpenID Connect Akun Layanan (
roles/iam.serviceAccountOpenIdTokenCreator
).Hal ini memberi akun layanan panggilan kemampuan untuk meniru identitas akun layanan target.
Gunakan kredensial yang disediakan oleh akun layanan panggilan untuk memanggil metode generateIdToken di akun layanan target.
Tetapkan kolom
audience
ke client ID Anda.
Untuk petunjuk langkah demi langkah, lihat Membuat token ID.
Melakukan Autentikasi dari Header Otorisasi Proxy
Jika aplikasi Anda menggunakan header permintaan Authorization
, Anda dapat menyertakan
token ID dalam header Proxy-Authorization: Bearer
. Jika token ID yang valid
ditemukan di header Proxy-Authorization
, IAP akan memberikan
otorisasi permintaan dengan token tersebut. Setelah memberikan otorisasi pada permintaan, IAP
akan meneruskan header Authorization
ke aplikasi Anda tanpa memproses
konten.
Jika tidak ada token ID yang valid yang ditemukan di header Proxy-Authorization
,
IAP akan terus memproses header Authorization
dan
menghapus header Proxy-Authorization
sebelum meneruskan permintaan ke
aplikasi Anda.
Langkah berikutnya
- Pelajari lebih lanjut Otorisasi: Token Pembawa.
- Coba Login untuk Android atau Login untuk iOS.