Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Autentikasi antarlayanan

OpenAPI | gRPC

Selain mengautentikasi pengguna, Anda mungkin perlu mengizinkan layanan lain berinteraksi dengan API Anda. Meskipun aplikasi klien dapat memberikan perintah login web kepada pengguna untuk mengirimkan kredensial mereka, Anda memerlukan pendekatan lain untuk komunikasi layanan-ke-layanan yang aman. Halaman ini menunjukkan pendekatan yang kami rekomendasikan untuk menerapkan autentikasi antar-layanan dan menyediakan kode contoh.

Ringkasan

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

Untuk menerapkan autentikasi layanan-ke-layanan di API dan layanan panggilan Anda:

Buat akun layanan dan kunci untuk digunakan oleh layanan panggilan.
Tambahkan dukungan untuk autentikasi dalam dokumen OpenAPI untuk layanan Cloud Endpoints Anda.
Tambahkan kode ke layanan panggilan yang:
- Membuat JWT dan menandatanganinya dengan kunci pribadi akun layanan.
- Mengirim JWT yang ditandatangani dalam permintaan ke API.

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

Prasyarat

Halaman ini mengasumsikan bahwa Anda telah:

Membuat akun layanan dengan kunci

Anda memerlukan akun layanan dengan file kunci pribadi yang digunakan layanan panggilan untuk menandatangani JWT. Jika Anda memiliki lebih dari satu layanan yang mengirim permintaan ke API Anda, Anda dapat membuat satu akun layanan untuk mewakili semua layanan panggilan. Jika Anda perlu membedakan antara 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 Google Cloud konsol dan alat command line gcloud `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.

Catatan: Kunci akun layanan akan berisiko keamanan jika tidak dikelola dengan benar. Anda harus memilih alternatif yang lebih aman untuk kunci akun layanan jika memungkinkan. Jika harus mengautentikasi dengan kunci akun layanan, Anda bertanggung jawab atas keamanan kunci pribadi dan atas operasi lain yang dijelaskan dalam Praktik terbaik untuk mengelola kunci akun layanan. Jika Anda tidak dapat membuat kunci akun layanan, pembuatan kunci akun layanan mungkin dinonaktifkan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat Mengelola resource organisasi yang aman secara default.

Jika Anda memperoleh kunci akun layanan dari sumber eksternal, Anda harus memvalidasinya sebelum digunakan. Untuk mengetahui informasi selengkapnya, lihat Persyaratan keamanan untuk kredensial yang bersumber dari eksternal.

Untuk membuat akun layanan dan kunci:

Google Cloud Konsol

Buat akun layanan:
1. Di Google Cloud konsol, buka halaman Buat akun layanan.
  
  Buka halaman Buat Akun Layanan
2. Pilih project yang ingin Anda gunakan.
3. Di kolom Nama akun layanan, masukkan nama.
4. Opsional: Di kolom Deskripsi akun layanan, masukkan deskripsi.
5. Klik Create.
6. Klik Done.
  
  Jangan tutup jendela browser Anda. Anda akan menggunakannya pada langkah berikutnya.
Buat kunci akun layanan:
1. Di Google Cloud konsol, klik alamat email untuk akun layanan yang telah dibuat.
2. Klik Keys.
3. Klik Tambahkan kunci, lalu Buat kunci baru.
4. Klik Create. File JSON yang berisi kunci pribadi akun layanan akan didownload ke komputer Anda.
5. Klik Close.

gcloud

Anda dapat menjalankan perintah berikut menggunakan Google Cloud CLI di komputer lokal, atau dalam Cloud Shell.

Tetapkan akun default untuk gcloud. Jika Anda memiliki lebih dari satu akun, pastikan untuk memilih akun yang ada di Google Cloud project yang ingin Anda gunakan.
```
gcloud auth login
```
Tampilkan project ID untukproject Google Cloud Anda.
```
gcloud projects list
```
Tetapkan project default. Ganti PROJECT_ID dengan project ID Google Cloud yang ingin Anda gunakan.
```
gcloud config set project PROJECT_ID
```
Buat akun layanan. Ganti SA_NAME dan SA_DISPLAY_NAME dengan nama dan nama tampilan yang ingin Anda gunakan.
```
gcloud iam service-accounts create SA_NAME \
  --display-name "SA_DISPLAY_NAME"
```
Tampilkan alamat email untuk akun layanan yang baru saja Anda buat.
```
gcloud iam service-accounts list
```

Tambahkan peran Service Account Token Creator. Ganti SA_EMAIL_ADDRESS dengan alamat email akun layanan.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member serviceAccount:SA_EMAIL_ADDRESS \
  --role roles/iam.serviceAccountTokenCreator

Buat file kunci akun layanan di direktori kerja saat ini. Ganti FILE_NAME dengan nama yang ingin Anda gunakan untuk file kunci. Secara default, perintah gcloud membuat file JSON.
```
gcloud iam service-accounts keys create FILE_NAME.json \
  --iam-account SA_EMAIL_ADDRESS
```

Lihat referensi gcloud untuk mengetahui informasi selengkapnya tentang perintah sebelumnya.

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

Mengonfigurasi API untuk mendukung autentikasi

Untuk mengaktifkan autentikasi akun layanan untuk layanan yang memanggil gateway Anda, ubah objek keamanan dalam dokumen OpenAPI Anda agar ESP dapat memvalidasi klaim dalam JWT yang ditandatangani. Perubahan akan bervariasi berdasarkan versi spesifikasi OpenAPI yang digunakan.

OpenAPI 2.0

Tambahkan akun layanan sebagai penerbit dalam spesifikasi OpenAPI 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 spesifikasi OpenAPI, tetapi setiap definisi harus memiliki x-google-issuer yang berbeda. Jika 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."
      x-google-jwks_uri: "https://www.googleapis.com/robot/v1/metadata/x509/service-1@example-project-12345."
    service-2:
      authorizationUrl: ""
      flow: "implicit"
      type: "oauth2"
      x-google-issuer: "service-2@example-project-12345."
      x-google-jwks_uri: "https://www.googleapis.com/robot/v1/metadata/x509/service-2@example-project-12345."

Secara opsional, tambahkan x-google-audiences ke bagian securityDefinitions. Jika Anda tidak menambahkan x-google-audiences, ESP mengharuskan klaim "aud" (audiens) dalam JWT berada dalam format https://SERVICE_NAME, dengan SERVICE_NAME adalah nama layanan ESP Anda, yang telah Anda konfigurasi di kolom host dokumen OpenAPI Anda.
Tambahkan bagian security di tingkat atas file (tidak diindentasi atau disarangkan) untuk diterapkan ke seluruh API, atau di tingkat metode untuk diterapkan ke metode tertentu. Jika Anda menggunakan security bagian di tingkat API dan di tingkat metode, setelan tingkat metode akan mengganti setelan tingkat API.
```
security:
  - DEFINITION_NAME: []
```
- Ganti DEFINITION_NAME dengan nama yang Anda gunakan di bagian securityDefinitions section.
- Jika Anda memiliki lebih dari satu definisi di bagian securityDefinitions, tambahkan definisi tersebut di bagian security, misalnya:
```
security:
  - service-1: []
  - service-2: []
```
Deploy spesifikasi OpenAPI yang telah diupdate . Sebelum ESP meneruskan permintaan ke API Anda, ESP akan memverifikasi:
- Tanda tangan JWT menggunakan kunci publik, yang terletak di URI ditentukan dalam kolom x-google-jwks_uri dalam spesifikasi OpenAPI Anda.
- Klaim "iss"(penerbit) dalam JWT cocok dengan nilai yang ditentukan dalam x-google-issuerkolom.
- Klaim "aud"(audiens) dalam JWT berisi nama layanan ESP Anda atau cocok dengan salah satu nilai yang Anda tentukan di kolom x-google-audiences.
- Token tidak berlaku lagi menggunakan klaim "exp"(waktu habis masa berlaku).

OpenAPI 3.x

Tambahkan akun layanan sebagai penerbit dalam spesifikasi OpenAPI Anda:

components:
  securitySchemes:
    SCHEME_NAME:
      type: oauth2
      flows:
       implicit:
         authorizationUrl: ""
         scopes: {}
      x-google-auth:
        issuer: SA_EMAIL_ADDRESS
        jwksUri: https://www.googleapis.com/robot/v1/metadata/x509/SA_EMAIL_ADDRESS
        audiences:
          - 848149964201.apps.googleusercontent.com
          - 841077041629.apps.googleusercontent.com
        jwtLocations:
          - header: Authorization
            valuePrefix: "Bearer "
security:
  - SCHEME_NAME: []

Ganti SCHEME_NAME dengan string yang mengidentifikasi skema 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 skema keamanan dalam spesifikasi OpenAPI, tetapi setiap definisi harus memiliki issuer yang berbeda. Jika telah membuat akun layanan terpisah untuk setiap layanan panggilan, Anda dapat membuat definisi keamanan untuk setiap akun layanan, misalnya:

components:
  securitySchemes:
    service-1:
      type: oauth2
      flows:
       implicit:
         authorizationUrl: ""
         scopes: {}
      x-google-auth:
        issuer: "service-1@example-project-12345."
        jwksUri: https://www.googleapis.com/robot/v1/metadata/x509/service-1@example-project-12345.
        jwtLocations:
          - header: Authorization
            valuePrefix: "Bearer "
    service-2:
      type: oauth2
      flows:
       implicit:
         authorizationUrl: ""
         scopes: {}
      x-google-auth:
        issuer: "service-2@example-project-12345."
        jwksUri: "https://www.googleapis.com/robot/v1/metadata/x509/service-2@example-project-12345."
        jwtLocations:
          - header: Authorization
            valuePrefix: "Bearer "

Secara opsional, tambahkan audiences ke bagian securitySchemes. Jika Anda tidak menambahkan audiences, ESP mengharuskan klaim "aud" (audiens) dalam JWT berada dalam format https://SERVICE_NAME, dengan SERVICE_NAME adalah nama layanan ESP Anda, yang telah Anda konfigurasi di kolom host dokumen OpenAPI Anda.
Tambahkan bagian security di tingkat atas file (tidak diindentasi atau disarangkan) untuk diterapkan ke seluruh API, atau di tingkat metode untuk diterapkan ke metode tertentu. Jika Anda menggunakan security bagian di tingkat API dan di tingkat metode, setelan tingkat metode akan mengganti setelan tingkat API.
```
security:
  - SCHEME_NAME: []
```
- Ganti SCHEME_NAME dengan nama yang Anda gunakan di bagian securitySchemes section.
- Jika Anda memiliki lebih dari satu definisi di bagian securitySchemes, tambahkan definisi tersebut di bagian security, misalnya:
```
security:
  - service-1: []
  - service-2: []
```
Deploy spesifikasi OpenAPI yang telah diupdate . Sebelum ESP meneruskan permintaan ke API Anda, ESP akan memverifikasi:
- Tanda tangan JWT menggunakan kunci publik, yang terletak di URI ditentukan dalam jwksUri dalam spesifikasi OpenAPI Anda.
- Klaim "iss"(penerbit) dalam JWT cocok dengan nilai yang ditentukan dalam issuerkolom.
- Klaim "aud"(audiens) dalam JWT berisi nama layanan ESP Anda atau cocok dengan salah satu nilai yang Anda tentukan di kolom audiences.
- Token tidak berlaku lagi menggunakan klaim "exp"(waktu habis masa berlaku).

Membuat permintaan yang diautentikasi ke Endpoints API

Untuk membuat permintaan yang diautentikasi, layanan panggilan mengirim JWT yang ditandatangani oleh akun layanan yang Anda tentukan dalam dokumen OpenAPI. Layanan panggilan harus:

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

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

Di layanan panggilan, tambahkan fungsi berikut dan teruskan parameter berikut: parameter:

Java

saKeyfile: Jalur lengkap ke file kunci pribadi akun layanan.
saEmail: Alamat email akun layanan.
audience: Jika Anda menambahkan kolom x-google-audiences ke dokumen OpenAPI, 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 Endpoints 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 dokumen OpenAPI, 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 Endpoints Anda.
expiry_length: Waktu habis masa berlaku JWT, dalam detik.

saKeyfile: Jalur lengkap ke file kunci pribadi akun layanan.
saEmail: Alamat email akun layanan.
audience: Jika Anda menambahkan kolom x-google-audiences ke dokumen OpenAPI, 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 Endpoints Anda.
expiryLength: Waktu habis masa berlaku JWT, dalam detik.

Fungsi ini membuat JWT, menandatanganinya menggunakan file kunci pribadi, dan menampilkan 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


// 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)
}

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()


// 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, karena alasan keamanan, sebaiknya letakkan token autentikasi di header Authorization: Bearer. Contoh:

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

dengan ENDPOINTS_HOST dan TOKEN adalah variabel lingkungan yang berisi nama host API dan token autentikasi Anda.

Menerima hasil yang diautentikasi di API Anda

ESP biasanya meneruskan semua header yang diterimanya. Namun, ESP akan mengganti header Authorization asli saat alamat backend ditentukan oleh x-google-backend dalam spesifikasi OpenAPI atau BackendRule dalam konfigurasi layanan gRPC.

ESP akan mengirim hasil autentikasi di X-Endpoint-API-UserInfo ke backend API. Sebaiknya gunakan header ini, bukan header Authorization asli. Header ini adalah string yang base64url mengenkode objek JSON. Format objek JSON berbeda antara ESPv2 dan ESP. Untuk ESPv2, objek JSON persis sama dengan payload JWT asli. Untuk ESP, objek JSON menggunakan nama kolom yang berbeda dan menempatkan payload JWT asli di kolom claims. Lihat Menangani JWT di layanan backend untuk mengetahui informasi selengkapnya tentang format.

Langkah berikutnya

Memecahkan masalah validasi JWT

Autentikasi antarlayanan Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Ringkasan

Prasyarat

Membuat akun layanan dengan kunci

Google Cloud Konsol

gcloud

Mengonfigurasi API untuk mendukung autentikasi

OpenAPI 2.0

OpenAPI 3.x

Membuat permintaan yang diautentikasi ke Endpoints API

Menerima hasil yang diautentikasi di API Anda

Langkah berikutnya

Autentikasi antarlayanan