Autentikasi antar-layanan

Selain mengautentikasi permintaan pengguna akhir, Anda mungkin ingin mengautentikasi layanan (pengguna non-manusia) yang membuat permintaan ke API Anda. Halaman ini menjelaskan cara menggunakan akun layanan untuk menyediakan autentikasi bagi pengguna atau layanan.

Ringkasan

Untuk mengidentifikasi layanan yang mengirim permintaan ke API Anda, Anda menggunakan akun layanan. Layanan panggilan menggunakan kunci pribadi akun layanan untuk menandatangani Token Web JSON (JWT) yang aman dan mengirimkan JWT yang ditandatangani dalam permintaan ke API Anda.

Untuk menerapkan autentikasi akun layanan di API dan layanan panggilan Anda:

1. Buat akun layanan dan kunci untuk digunakan oleh layanan panggilan.
2. Tambahkan dukungan untuk autentikasi di konfigurasi API untuk layanan API Gateway Anda.

3. Tambahkan kode ke layanan panggilan yang:

   • Membuat JWT dan menandatanganinya dengan kunci pribadi akun layanan.
   • Mengirim JWT yang ditandatangani dalam permintaan ke API.

API Gateway memvalidasi bahwa klaim dalam JWT cocok dengan konfigurasi di konfigurasi API Anda sebelum meneruskan permintaan ke API Anda. API Gateway tidak memeriksa izin Cloud Identity yang telah Anda berikan pada akun layanan.

Prasyarat

Halaman ini mengasumsikan bahwa Anda telah:

• Membuat Google Cloud project.

• Membuat dokumen OpenAPI yang mendeskripsikan API Anda.

• Membuat konfigurasi API.

Membuat akun layanan dengan kunci

Anda memerlukan akun layanan dengan file kunci pribadi yang digunakan oleh layanan pemanggil untuk menandatangani JWT. Jika Anda memiliki lebih dari satu layanan yang mengirim permintaan ke API, Anda dapat membuat satu akun layanan untuk mewakili semua layanan yang memanggil. Jika Anda perlu membedakan layanan—misalnya, layanan tersebut mungkin memiliki izin yang berbeda—Anda dapat membuat akun layanan dan kunci untuk setiap layanan panggilan.

Bagian ini menunjukkan cara menggunakan konsol Google Cloud dan alat command line gcloud untuk membuat akun layanan dan file kunci pribadi serta menetapkan peran Service Account Token Creator ke akun layanan. Untuk mengetahui informasi tentang cara menggunakan API untuk melakukan tugas ini, lihat Membuat dan mengelola akun layanan.

Untuk membuat akun layanan dengan kunci:

Untuk mengetahui informasi tentang cara mengamankan kunci pribadi, lihat Praktik terbaik untuk mengelola kredensial.

Mengonfigurasi API untuk mendukung autentikasi

Saat membuat konfigurasi API untuk gateway, Anda menentukan akun layanan yang digunakan gateway untuk berinteraksi dengan layanan lain. Untuk mengaktifkan autentikasi akun layanan bagi layanan yang memanggil gateway Anda, ubah objek persyaratan keamanan dan objek definisi keamanan di konfigurasi API Anda. Dengan mengikuti langkah-langkah di bawah, API Gateway dapat memvalidasi klaim dalam JWT bertanda tangan yang digunakan oleh layanan panggilan.

1. Tambahkan akun layanan sebagai penerbit dalam konfigurasi API Anda.

   securityDefinitions:
     DEFINITION_NAME:
       authorizationUrl: ""
       flow: "implicit"
       type: "oauth2"
       x-google-issuer: "SA_EMAIL_ADDRESS"
       x-google-jwks_uri: "https://www.googleapis.com/robot/v1/metadata/x509/SA_EMAIL_ADDRESS"
   

   • Ganti DEFINITION_NAME dengan string yang mengidentifikasi definisi keamanan ini. Anda mungkin ingin menggantinya dengan nama akun layanan atau nama yang mengidentifikasi layanan panggilan.
   • Ganti SA_EMAIL_ADDRESS dengan alamat email akun layanan.
   • Anda dapat menentukan beberapa definisi keamanan dalam konfigurasi API, tetapi setiap definisi harus memiliki x-google-issuer yang berbeda. Jika Anda telah membuat akun layanan terpisah untuk setiap layanan panggilan, Anda dapat membuat definisi keamanan untuk setiap akun layanan, misalnya:

   securityDefinitions:
     service-1:
       authorizationUrl: ""
       flow: "implicit"
       type: "oauth2"
       x-google-issuer: "service-1@example-project-12345.iam.gserviceaccount.com"
       x-google-jwks_uri: "https://www.googleapis.com/robot/v1/metadata/x509/service-1@example-project-12345.iam.gserviceaccount.com"
     service-2:
       authorizationUrl: ""
       flow: "implicit"
       type: "oauth2"
       x-google-issuer: "service-2@example-project-12345.iam.gserviceaccount.com"
       x-google-jwks_uri: "https://www.googleapis.com/robot/v1/metadata/x509/service-2@example-project-12345.iam.gserviceaccount.com"
   

2. Secara opsional, tambahkan x-google-audiences ke bagian securityDefinitions. Jika Anda tidak menambahkan x-google-audiences, API Gateway akan mewajibkan klaim "aud" (audiens) dalam JWT memiliki format https://SERVICE_NAME, dengan SERVICE_NAME adalah nama layanan API Gateway Anda, yang telah Anda konfigurasi di kolom host dokumen OpenAPI Anda.

3. Tambahkan bagian security di tingkat teratas file (tidak diindentasi atau disarangkan) untuk diterapkan ke seluruh API, atau di tingkat metode untuk diterapkan ke metode tertentu. Jika Anda menggunakan bagian security di tingkat API dan tingkat metode, setelan tingkat metode akan menggantikan setelan tingkat API.

   security:
     - DEFINITION_NAME: []

   • Ganti DEFINITION_NAME dengan nama yang Anda gunakan di bagian securityDefinitions.

   • Jika Anda memiliki lebih dari satu definisi di bagian securityDefinitions, tambahkan di bagian security, misalnya:

     security:
       - service-1: []
       - service-2: []
     

4. Deploy konfigurasi API yang diperbarui.

Sebelum meneruskan permintaan ke API Anda, API Gateway memverifikasi:

• Tanda tangan JWT menggunakan kunci publik, yang terletak di URI yang ditentukan di kolom x-google-jwks_uri dalam konfigurasi API Anda.
• Klaim "iss" (penerbit) di JWT cocok dengan nilai yang ditentukan di kolom x-google-issuer.
• Klaim "aud" (audiens) di JWT berisi nama layanan API Gateway Anda atau cocok dengan salah satu nilai yang Anda tentukan di kolom x-google-audiences.
• Token belum habis masa berlakunya dengan menggunakan klaim "exp" (waktu habis masa berlaku).

Untuk mengetahui informasi selengkapnya tentang x-google-issuer, x-google-jwks_uri, dan x-google-audiences, lihat Ekstensi OpenAPI.

Membuat permintaan yang diautentikasi ke API Gateway API

Untuk membuat permintaan yang diautentikasi, layanan panggilan mengirimkan JWT yang ditandatangani oleh akun layanan yang Anda tentukan dalam konfigurasi API. Layanan panggilan harus:

1. Buat JWT dan tandatangani dengan kunci pribadi akun layanan.
2. Kirim JWT yang ditandatangani dalam permintaan ke API.

Contoh kode berikut menunjukkan proses ini untuk bahasa tertentu. Untuk membuat permintaan yang diautentikasi dalam bahasa lain, lihat jwt.io untuk mengetahui daftar library yang didukung.

1. Di layanan panggilan, tambahkan fungsi berikut dan teruskan parameter berikut:
   Java

   • saKeyfile: Jalur lengkap ke file kunci pribadi akun layanan.
   • saEmail: Alamat email akun layanan.
   • audience: Jika Anda menambahkan kolom x-google-audiences ke konfigurasi API, tetapkan audience ke salah satu nilai yang Anda tentukan untuk x-google-audiences. Jika tidak, tetapkan audience ke https://SERVICE_NAME, dengan SERVICE_NAME adalah nama layanan API Gateway Anda.
   • expiryLength: Waktu habis masa berlaku JWT, dalam detik.

   Python

   • sa_keyfile: Jalur lengkap ke file kunci pribadi akun layanan.
   • sa_email: Alamat email akun layanan.
   • audience: Jika Anda menambahkan kolom x-google-audiences ke konfigurasi API, tetapkan audience ke salah satu nilai yang Anda tentukan untuk x-google-audiences. Jika tidak, tetapkan audience ke https://SERVICE_NAME, dengan SERVICE_NAME adalah nama layanan API Gateway Anda.
   • expiry_length: Waktu habis masa berlaku JWT, dalam detik.

   Mulai

   • saKeyfile: Jalur lengkap ke file kunci pribadi akun layanan.
   • saEmail: Alamat email akun layanan.
   • audience: Jika Anda menambahkan kolom x-google-audiences ke konfigurasi API, tetapkan audience ke salah satu nilai yang Anda tentukan untuk x-google-audiences. Jika tidak, tetapkan audience ke https://SERVICE_NAME, dengan SERVICE_NAME adalah nama layanan API Gateway Anda.
   • expiryLength: Waktu habis masa berlaku JWT, dalam detik.

   Fungsi ini membuat JWT, menandatanganinya menggunakan file kunci pribadi, dan mengembalikan JWT yang ditandatangani.

   Java

   /**
    * Generates a signed JSON Web Token using a Google API Service Account
    * utilizes com.auth0.jwt.
    */
   public static String generateJwt(final String saKeyfile, final String saEmail,
       final String audience, final int expiryLength)
       throws FileNotFoundException, IOException {
   
     Date now = new Date();
     Date expTime = new Date(System.currentTimeMillis() + TimeUnit.SECONDS.toMillis(expiryLength));
   
     // Build the JWT payload
     JWTCreator.Builder token = JWT.create()
         .withIssuedAt(now)
         // Expires after 'expiryLength' seconds
         .withExpiresAt(expTime)
         // Must match 'issuer' in the security configuration in your
         // swagger spec (e.g. service account email)
         .withIssuer(saEmail)
         // Must be either your Endpoints service name, or match the value
         // specified as the 'x-google-audience' in the OpenAPI document
         .withAudience(audience)
         // Subject and email should match the service account's email
         .withSubject(saEmail)
         .withClaim("email", saEmail);
   
     // Sign the JWT with a service account
     FileInputStream stream = new FileInputStream(saKeyfile);
     ServiceAccountCredentials cred = ServiceAccountCredentials.fromStream(stream);
     RSAPrivateKey key = (RSAPrivateKey) cred.getPrivateKey();
     Algorithm algorithm = Algorithm.RSA256(null, key);
     return token.sign(algorithm);
   }

   Python

   def generate_jwt(
       sa_keyfile,
       sa_email="account@project-id.iam.gserviceaccount.com",
       audience="your-service-name",
       expiry_length=3600,
   ):
       """Generates a signed JSON Web Token using a Google API Service Account."""
   
       now = int(time.time())
   
       # build payload
       payload = {
           "iat": now,
           # expires after 'expiry_length' seconds.
           "exp": now + expiry_length,
           # iss must match 'issuer' in the security configuration in your
           # swagger spec (e.g. service account email). It can be any string.
           "iss": sa_email,
           # aud must be either your Endpoints service name, or match the value
           # specified as the 'x-google-audience' in the OpenAPI document.
           "aud": audience,
           # sub and email should match the service account's email address
           "sub": sa_email,
           "email": sa_email,
       }
   
       # sign with keyfile
       signer = google.auth.crypt.RSASigner.from_service_account_file(sa_keyfile)
       jwt = google.auth.jwt.encode(signer, payload)
   
       return jwt
   
   

   Mulai

   
   // generateJWT creates a signed JSON Web Token using a Google API Service Account.
   func generateJWT(saKeyfile, saEmail, audience string, expiryLength int64) (string, error) {
   	now := time.Now().Unix()
   
   	// Build the JWT payload.
   	jwt := &jws.ClaimSet{
   		Iat: now,
   		// expires after 'expiryLength' seconds.
   		Exp: now + expiryLength,
   		// Iss must match 'issuer' in the security configuration in your
   		// swagger spec (e.g. service account email). It can be any string.
   		Iss: saEmail,
   		// Aud must be either your Endpoints service name, or match the value
   		// specified as the 'x-google-audience' in the OpenAPI document.
   		Aud: audience,
   		// Sub and Email should match the service account's email address.
   		Sub:           saEmail,
   		PrivateClaims: map[string]interface{}{"email": saEmail},
   	}
   	jwsHeader := &jws.Header{
   		Algorithm: "RS256",
   		Typ:       "JWT",
   	}
   
   	// Extract the RSA private key from the service account keyfile.
   	sa, err := os.ReadFile(saKeyfile)
   	if err != nil {
   		return "", fmt.Errorf("could not read service account file: %w", err)
   	}
   	conf, err := google.JWTConfigFromJSON(sa)
   	if err != nil {
   		return "", fmt.Errorf("could not parse service account JSON: %w", err)
   	}
   	block, _ := pem.Decode(conf.PrivateKey)
   	parsedKey, err := x509.ParsePKCS8PrivateKey(block.Bytes)
   	if err != nil {
   		return "", fmt.Errorf("private key parse error: %w", err)
   	}
   	rsaKey, ok := parsedKey.(*rsa.PrivateKey)
   	// Sign the JWT with the service account's private key.
   	if !ok {
   		return "", errors.New("private key failed rsa.PrivateKey type assertion")
   	}
   	return jws.Encode(jwsHeader, jwt, rsaKey)
   }
   

2. Di layanan panggilan, tambahkan fungsi berikut untuk mengirim JWT yang ditandatangani di header Authorization: Bearer dalam permintaan ke API:
   Java

   /**
    * Makes an authorized request to the endpoint.
    */
   public static String makeJwtRequest(final String signedJwt, final URL url)
       throws IOException, ProtocolException {
   
     HttpURLConnection con = (HttpURLConnection) url.openConnection();
     con.setRequestMethod("GET");
     con.setRequestProperty("Content-Type", "application/json");
     con.setRequestProperty("Authorization", "Bearer " + signedJwt);
   
     InputStreamReader reader = new InputStreamReader(con.getInputStream());
     BufferedReader buffReader = new BufferedReader(reader);
   
     String line;
     StringBuilder result = new StringBuilder();
     while ((line = buffReader.readLine()) != null) {
       result.append(line);
     }
     buffReader.close();
     return result.toString();
   }

   Python

   def make_jwt_request(signed_jwt, url="https://your-endpoint.com"):
       """Makes an authorized request to the endpoint"""
       headers = {
           "Authorization": "Bearer {}".format(signed_jwt.decode("utf-8")),
           "content-type": "application/json",
       }
       response = requests.get(url, headers=headers)
       print(response.status_code, response.content)
       response.raise_for_status()
   
   

   Mulai

   
   // makeJWTRequest sends an authorized request to your deployed endpoint.
   func makeJWTRequest(signedJWT, url string) (string, error) {
   	client := &http.Client{
   		Timeout: 10 * time.Second,
   	}
   
   	req, err := http.NewRequest("GET", url, nil)
   	if err != nil {
   		return "", fmt.Errorf("failed to create HTTP request: %w", err)
   	}
   	req.Header.Add("Authorization", "Bearer "+signedJWT)
   	req.Header.Add("content-type", "application/json")
   
   	response, err := client.Do(req)
   	if err != nil {
   		return "", fmt.Errorf("HTTP request failed: %w", err)
   	}
   	defer response.Body.Close()
   	responseData, err := io.ReadAll(response.Body)
   	if err != nil {
   		return "", fmt.Errorf("failed to parse HTTP response: %w", err)
   	}
   	return string(responseData), nil
   }
   

Saat Anda mengirim permintaan menggunakan JWT, demi alasan keamanan, sebaiknya Anda menempatkan token autentikasi di header Authorization: Bearer. Contoh:

curl --request POST \
  --header "Authorization: Bearer ${TOKEN}" \
  "${GATEWAY_URL}/echo"

dengan GATEWAY_URL dan TOKEN adalah variabel lingkungan yang masing-masing berisi URL gateway yang di-deploy dan token autentikasi Anda.

Menerima hasil yang diautentikasi di API Anda

API Gateway biasanya meneruskan semua header yang diterimanya. Namun, header Authorization asli akan diganti jika alamat backend ditentukan oleh x-google-backend dalam konfigurasi API.

API Gateway akan mengirimkan hasil autentikasi di X-Apigateway-Api-Userinfo ke backend API. Sebaiknya gunakan header ini, bukan header Authorization yang asli. Header ini dienkode base64url dan berisi payload JWT.

Langkah berikutnya

• Mengelola akses API