Sertifikat klien mTLS MCP tidak valid

Halaman ini berlaku untuk Apigee hybrid, tetapi tidak untuk Apigee.

Tidak ada dokumentasi Apigee Edge yang setara untuk topik ini.

Gejala

ApigeeIssue dengan Reason AIS_MCP_MTLS_CLIENT_CERT_INVALID ditampilkan saat melihat resource di namespace apigee.

Pesan error

Setelah menjalankan kubectl -n apigee get apigeeissues, error seperti berikut akan ditampilkan:

NAME                                            SEVERITY   REASON                             DOCUMENTATION                                                                                  AGE
mcp-client-cert-invalid-my-org-my-virtualhost   ERROR      AIS_MCP_MTLS_CLIENT_CERT_INVALID   https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID   5h18m

Kemungkinan penyebab

Tabel berikut mencantumkan kemungkinan penyebab masalah ini:

Penyebab Deskripsi
Rahasia atau entri sertifikat klien mTLS MCP tidak ada Secret yang diberi nama oleh mcpMtls tidak ada, atau tidak memiliki entri cert atau key yang dapat digunakan.
Sertifikat atau kunci klien mTLS MCP salah format Entri cert tidak dienkode PEM, atau entri key bukan kunci pribadi yang cocok.
Sertifikat klien mTLS MCP menghilangkan penggunaan kunci yang diperluas clientAuth Sertifikat diuraikan, tetapi penggunaan kunci yang diperpanjang tidak menyertakan clientAuth.

Penyebab: Rahasia atau entri sertifikat klien mTLS MCP tidak ada

Secret Kubernetes yang seharusnya menyimpan sertifikat klien mTLS MCP tidak ada di namespace apigee, atau ada tanpa entri cert yang tidak kosong atau tanpa entri key. Bidang data MCP tidak memiliki sertifikat klien yang dapat ditampilkan untuk grup lingkungan ini, sehingga panggilan alat MCP ke grup tersebut gagal pada TLS handshake.

Diagnosis

Jalankan perintah berikut:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Ganti ISSUE_NAME dengan nama masalah, misalnya mcp-client-cert-invalid-my-org-my-virtualhost.

Output-nya akan terlihat seperti berikut:

Name:         mcp-client-cert-invalid-my-org-my-virtualhost
Namespace:    apigee
Labels:       ais-reason=AIS_MCP_MTLS_CLIENT_CERT_INVALID
Annotations:  <none>
API Version:  apigee.cloud.google.com/v1alpha1
Kind:         ApigeeIssue
Metadata:
  Creation Timestamp:  2026-11-12T17:03:43Z
  Generation:          1
  Owner References:
    API Version:     apigee.cloud.google.com/v1alpha2
    Kind:            ApigeeOrganization
    Name:            my-org
    UID:             7e83a52c-ce00-4bed-98be-55835ada1817
  Resource Version:  3281563
  UID:               adc775c2-376d-4bf9-9860-500b2b2b8273
Spec:
  Details:        MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: secret not found: secrets "my-org-my-virtualhost-mcp" not found
  Documentation:  https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID
  Reason:         AIS_MCP_MTLS_CLIENT_CERT_INVALID
  Severity:       ERROR
Events:           <none>
Spec:
  Details:        MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: secret not found: secrets "my-org-my-virtualhost-mcp" not found

Konten Spec.Details memberi nama secret, ApigeeRouteConfig, dan apa yang salah. Contoh:

  • secret not found
  • secret has no usable "cert" entry
  • secret has no "key" entry

Resolusi

  1. Gunakan kubectl describe untuk menampilkan nama secret Kubernetes dan ApigeeRouteConfig yang terkait dengan masalah tersebut:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Ganti ISSUE_NAME dengan nama masalah, misalnya mcp-client-cert-invalid-my-org-my-virtualhost.

    Dalam contoh ini, ApigeeRouteConfig my-org-my-virtualhost merujuk ke secret my-org-my-virtualhost-mcp.

  2. Tentukan nama virtualhost dari ApigeeRouteConfig.

    Nama ApigeeRouteConfig menggunakan format: <Apigee organization>-<virtualhost name>.

    Dalam contoh ini, my-org adalah organisasi Apigee dan nama virtualhost-nya adalah my-virtualhost.

  3. Temukan virtualhost yang sesuai di overrides.yaml Anda dan periksa bentuk blok mcpMtls yang digunakannya (lihat Mengonfigurasi mTLS antara bidang data MCP dan gateway masuk). Pilih tab yang cocok, lalu ikuti langkah-langkah di tab tersebut.

File sertifikat

Saat Anda menggunakan jalur file (sslCertPath, sslKeyPath, caCertPath), diagram virtualhost akan membuat dan mengelola secret dari konten file.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  caCertPath: ./certs/ca.pem
  sslCertPath: ./certs/vhost.pem
  sslKeyPath: ./certs/vhost.key
  mcpMtls:
    caCertPath: ./certs/mcp-ca.pem
    sslCertPath: ./certs/mcp-client.pem
    sslKeyPath: ./certs/mcp-client.key
...
  1. Periksa apakah secret ada dan memiliki kedua entri, dengan MCP_CLIENT_SECRET_NAME adalah secret yang diberi nama di Spec.Details. Bagian Data harus mencantumkan cert dan key:

    kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME

    Jika secret tidak ada atau tidak memiliki entri, pastikan file yang direferensikan oleh mcpMtls.sslCertPath dan mcpMtls.sslKeyPath ada dan tidak kosong. Langkah berikutnya akan memulihkan secret dari file tersebut.

  2. Upgrade virtualhost agar diagram menulis ulang secret:

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Secret Kubernetes

Saat Anda menggunakan referensi secret Kubernetes (sslSecret), bidang data MCP akan membaca nilai sertifikat langsung dari secret yang Anda buat, dan update akan diterapkan secara otomatis. helm upgrade tidak diperlukan.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Pastikan secret ada dan memiliki kedua entri, dengan MCP_CLIENT_SECRET_NAME adalah secret yang diberi nama di Spec.Details. Bagian Data harus mencantumkan cert dan key. Pastikan nama di mcpMtls.sslSecret cocok dengan secret yang Anda buat dan secret tersebut berada di namespace apigee:

    kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME
    kubectl get secret -A --field-selector metadata.name=MCP_CLIENT_SECRET_NAME   # if the first command finds nothing

    helm template tidak memeriksa apakah secret ada; hanya helm install dan helm upgrade yang melakukannya, sehingga eksekusi helm template yang bersih bukan bukti bahwa secret ini ada.

  2. Buat atau perbarui secret dengan sertifikat dan kunci pribadinya secara bersamaan, dengan MCP_CLIENT_SECRET_NAME sebagai secret yang diberi nama di Spec.Details, serta MCP_CLIENT_CERT_FILE dan MCP_CLIENT_KEY_FILE sebagai sertifikat dan kunci pribadinya:

    kubectl -n apigee create secret generic MCP_CLIENT_SECRET_NAME \
      --from-file=cert=MCP_CLIENT_CERT_FILE --from-file=key=MCP_CLIENT_KEY_FILE \
      --dry-run=client -o yaml | kubectl apply -f -

Data plane MCP mengambil secret yang telah diperbaiki pada refresh berkala berikutnya, biasanya dalam beberapa menit, tanpa memulai ulang pod, dan ApigeeIssue akan ditarik pada pemindaian berikutnya.

Penyebab: Sertifikat atau kunci klien mTLS MCP salah format

Entri cert tidak berisi sertifikat X.509 berenkode PEM, atau entri key tidak berenkode PEM atau bukan kunci pribadi untuk sertifikat tersebut. Data plane MCP tidak dapat memuat pasangan.

Diagnosis

Jalankan perintah berikut:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Ganti ISSUE_NAME dengan nama masalah, misalnya mcp-client-cert-invalid-my-org-my-virtualhost.

Output-nya akan terlihat seperti berikut:

Name:         mcp-client-cert-invalid-my-org-my-virtualhost
Namespace:    apigee
Labels:       ais-reason=AIS_MCP_MTLS_CLIENT_CERT_INVALID
Annotations:  <none>
API Version:  apigee.cloud.google.com/v1alpha1
Kind:         ApigeeIssue
Metadata:
  Creation Timestamp:  2026-11-12T17:03:43Z
  Generation:          1
  Owner References:
    API Version:     apigee.cloud.google.com/v1alpha2
    Kind:            ApigeeOrganization
    Name:            my-org
    UID:             7e83a52c-ce00-4bed-98be-55835ada1817
  Resource Version:  3281563
  UID:               adc775c2-376d-4bf9-9860-500b2b2b8273
Spec:
  Details:        MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" and "key" are not a usable certificate and key: tls: private key does not match public key
  Documentation:  https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID
  Reason:         AIS_MCP_MTLS_CLIENT_CERT_INVALID
  Severity:       ERROR
Events:           <none>
Spec:
  Details:        MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" and "key" are not a usable certificate and key: tls: private key does not match public key

Konten Spec.Details memberi nama secret, ApigeeRouteConfig, dan apa yang salah. Contoh:

  • entry holds no PEM encoded certificate: entri cert bukan PEM.
  • tls: failed to find any PEM data in key input: entri key bukan PEM.
  • tls: private key does not match public key: entri cert dan key tidak berpasangan.
  • tls: failed to parse private key: kunci tidak dapat diurai, biasanya karena dienkripsi. Entri key harus berupa kunci pribadi PEM yang tidak dienkripsi.

Resolusi

  1. Gunakan kubectl describe untuk menampilkan nama secret Kubernetes dan ApigeeRouteConfig yang terkait dengan masalah tersebut:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Ganti ISSUE_NAME dengan nama masalah, misalnya mcp-client-cert-invalid-my-org-my-virtualhost.

    Dalam contoh ini, ApigeeRouteConfig my-org-my-virtualhost merujuk ke secret my-org-my-virtualhost-mcp.

  2. Tentukan nama virtualhost dari ApigeeRouteConfig.

    Nama ApigeeRouteConfig menggunakan format: <Apigee organization>-<virtualhost name>.

    Dalam contoh ini, my-org adalah organisasi Apigee dan nama virtualhost-nya adalah my-virtualhost.

  3. Temukan virtualhost yang sesuai di overrides.yaml Anda dan periksa bentuk blok mcpMtls yang digunakannya (lihat Mengonfigurasi mTLS antara bidang data MCP dan gateway masuk). Pilih tab yang cocok, lalu ikuti langkah-langkah di tab tersebut.

File sertifikat

Saat Anda menggunakan jalur file (sslCertPath, sslKeyPath, caCertPath), diagram virtualhost akan membuat dan mengelola secret dari konten file.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  caCertPath: ./certs/ca.pem
  sslCertPath: ./certs/vhost.pem
  sslKeyPath: ./certs/vhost.key
  mcpMtls:
    caCertPath: ./certs/mcp-ca.pem
    sslCertPath: ./certs/mcp-client.pem
    sslKeyPath: ./certs/mcp-client.key
...
  1. Validasi file sertifikat dan file kunci yang direferensikan oleh mcpMtls.sslCertPath dan mcpMtls.sslKeyPath, dan perbaiki jika diperlukan. Sertifikat harus berisi baris sertifikat awal dan akhir, dan kuncinya harus berupa kunci pribadi untuk sertifikat tersebut. Contoh:

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. Upgrade virtualhost agar diagram menulis ulang secret:

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Secret Kubernetes

Saat Anda menggunakan referensi secret Kubernetes (sslSecret), bidang data MCP akan membaca nilai sertifikat langsung dari secret yang Anda buat, dan update akan diterapkan secara otomatis. helm upgrade tidak diperlukan.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Validasi file sertifikat (MCP_CLIENT_CERT_FILE) dan file kunci (MCP_CLIENT_KEY_FILE) yang Anda simpan di entri cert dan key secret, dan perbaiki jika diperlukan. Sertifikat harus berisi baris sertifikat awal dan akhir, dan kunci harus berupa kunci pribadi untuk sertifikat tersebut. Contoh:

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. Perbarui secret di tempat dengan sertifikat dan kunci pribadinya secara bersamaan, dengan MCP_CLIENT_SECRET_NAME sebagai secret yang diberi nama di Spec.Details, serta MCP_CLIENT_CERT_FILE dan MCP_CLIENT_KEY_FILE sebagai sertifikat dan kunci pribadinya:

    kubectl -n apigee create secret generic MCP_CLIENT_SECRET_NAME \
      --from-file=cert=MCP_CLIENT_CERT_FILE --from-file=key=MCP_CLIENT_KEY_FILE \
      --dry-run=client -o yaml | kubectl apply -f -

Data plane MCP mengambil secret yang telah diperbaiki pada refresh berkala berikutnya, biasanya dalam beberapa menit, tanpa memulai ulang pod, dan ApigeeIssue akan ditarik pada pemindaian berikutnya.

Penyebab: Sertifikat klien mTLS MCP menghilangkan penggunaan kunci yang diperluas clientAuth

Sertifikat terbentuk dengan baik dan dipasangkan dengan kuncinya, tetapi penggunaan kunci yang diperpanjang (EKU) tidak mencakup clientAuth, sehingga tidak dapat digunakan untuk autentikasi klien dan bidang data MCP tidak menampilkannya. Hal ini umum terjadi saat sertifikat server, atau sertifikat dari profil CA publik yang tidak lagi menerbitkan clientAuth, digunakan kembali.

Diagnosis

Jalankan perintah berikut:

kubectl -n apigee describe apigeeissue ISSUE_NAME

Ganti ISSUE_NAME dengan nama masalah, misalnya mcp-client-cert-invalid-my-org-my-virtualhost.

Output-nya akan terlihat seperti berikut:

Name:         mcp-client-cert-invalid-my-org-my-virtualhost
Namespace:    apigee
Labels:       ais-reason=AIS_MCP_MTLS_CLIENT_CERT_INVALID
Annotations:  <none>
API Version:  apigee.cloud.google.com/v1alpha1
Kind:         ApigeeIssue
Metadata:
  Creation Timestamp:  2026-11-12T17:03:43Z
  Generation:          1
  Owner References:
    API Version:     apigee.cloud.google.com/v1alpha2
    Kind:            ApigeeOrganization
    Name:            my-org
    UID:             7e83a52c-ce00-4bed-98be-55835ada1817
  Resource Version:  3281563
  UID:               adc775c2-376d-4bf9-9860-500b2b2b8273
Spec:
  Details:        MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" has extended key usage [serverAuth], which omits clientAuth
  Documentation:  https://cloud.google.com/apigee/docs/hybrid/troubleshooting/AIS_MCP_MTLS_CLIENT_CERT_INVALID
  Reason:         AIS_MCP_MTLS_CLIENT_CERT_INVALID
  Severity:       ERROR
Events:           <none>
Spec:
  Details:        MCP mTLS client certificate in secret "my-org-my-virtualhost-mcp" for ApigeeRouteConfig "my-org-my-virtualhost" is not usable: "cert" has extended key usage [serverAuth], which omits clientAuth

Konten Spec.Details memberi nama secret dan ApigeeRouteConfig, serta mencantumkan penggunaan kunci yang diperpanjang yang dibawa oleh sertifikat.

Resolusi

  1. Gunakan kubectl describe untuk menampilkan nama secret Kubernetes dan ApigeeRouteConfig yang terkait dengan masalah tersebut:

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Ganti ISSUE_NAME dengan nama masalah, misalnya mcp-client-cert-invalid-my-org-my-virtualhost.

    Dalam contoh ini, ApigeeRouteConfig my-org-my-virtualhost merujuk ke secret my-org-my-virtualhost-mcp.

  2. Tentukan nama virtualhost dari ApigeeRouteConfig.

    Nama ApigeeRouteConfig menggunakan format: <Apigee organization>-<virtualhost name>.

    Dalam contoh ini, my-org adalah organisasi Apigee dan nama virtualhost-nya adalah my-virtualhost.

  3. Temukan virtualhost yang sesuai di overrides.yaml Anda dan periksa bentuk blok mcpMtls yang digunakannya (lihat Mengonfigurasi mTLS antara bidang data MCP dan gateway masuk). Pilih tab yang cocok, lalu ikuti langkah-langkah di tab tersebut.

File sertifikat

Saat Anda menggunakan jalur file (sslCertPath, sslKeyPath, caCertPath), diagram virtualhost akan membuat dan mengelola secret dari konten file.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  caCertPath: ./certs/ca.pem
  sslCertPath: ./certs/vhost.pem
  sslKeyPath: ./certs/vhost.key
  mcpMtls:
    caCertPath: ./certs/mcp-ca.pem
    sslCertPath: ./certs/mcp-client.pem
    sslKeyPath: ./certs/mcp-client.key
...
  1. Terbitkan ulang sertifikat klien dari CA pribadi Anda dengan profil yang menyertakan penggunaan kunci yang diperluas clientAuth. Konfirmasi, dengan MCP_CLIENT_CERT_FILE adalah sertifikat yang diterbitkan ulang, lalu ganti file yang direferensikan oleh mcpMtls.sslCertPath dan mcpMtls.sslKeyPath:

    openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage
    # must list: TLS Web Client Authentication
  2. Upgrade virtualhost agar diagram menulis ulang secret:

    helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \
      --namespace apigee \
      --set envgroup=ENV_GROUP_NAME \
      -f overrides.yaml

Secret Kubernetes

Saat Anda menggunakan referensi secret Kubernetes (sslSecret), bidang data MCP akan membaca nilai sertifikat langsung dari secret yang Anda buat, dan update akan diterapkan secara otomatis. helm upgrade tidak diperlukan.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Terbitkan ulang sertifikat klien dari CA pribadi Anda dengan profil yang menyertakan penggunaan kunci yang diperluas clientAuth. Konfirmasi sebelum Anda memperbarui secret, dengan MCP_CLIENT_CERT_FILE sebagai sertifikat yang diterbitkan ulang:

    openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage
    # must list: TLS Web Client Authentication
  2. Perbarui secret di tempat dengan sertifikat dan kunci pribadinya secara bersamaan, dengan MCP_CLIENT_SECRET_NAME sebagai secret yang diberi nama di Spec.Details, serta MCP_CLIENT_CERT_FILE dan MCP_CLIENT_KEY_FILE sebagai sertifikat dan kunci pribadinya:

    kubectl -n apigee create secret generic MCP_CLIENT_SECRET_NAME \
      --from-file=cert=MCP_CLIENT_CERT_FILE --from-file=key=MCP_CLIENT_KEY_FILE \
      --dry-run=client -o yaml | kubectl apply -f -

Data plane MCP mengambil secret yang telah diperbaiki pada refresh berkala berikutnya, biasanya dalam beberapa menit, tanpa memulai ulang pod, dan ApigeeIssue akan ditarik pada pemindaian berikutnya.

Harus mengumpulkan informasi diagnostik

Jika masalah berlanjut bahkan setelah mengikuti petunjuk sebelumnya, kumpulkan informasi diagnostik berikut, lalu hubungi Google Cloud Customer Care:

  1. Project ID Google Cloud .
  2. Nama organisasi Apigee hybrid.
  3. Kolom Spec.Details dari ApigeeIssue.
  4. (opsional) Sertifikat dalam file yang dirujuk oleh mcpMtls.sslCertPath, atau dalam entri cert secret, untuk virtualhost yang terpengaruh.