Certificat client mTLS MCP non valide

Cette page s'applique à Apigee hybrid, mais pas à Apigee.

Il n'existe pas de documentation Apigee Edge équivalente pour ce sujet.

Problème constaté

Un ApigeeIssue avec Reason AIS_MCP_MTLS_CLIENT_CERT_INVALID s'affiche lorsque vous consultez les ressources de l'espace de noms apigee.

Messages d'erreur

Une fois kubectl -n apigee get apigeeissues exécuté, une erreur semblable à celle-ci s'affiche :

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

Causes possibles

Le tableau suivant liste les causes possibles de ce problème :

Cause Description
Le secret ou l'entrée du certificat client mTLS MCP est manquant Le secret nommé par mcpMtls n'existe pas, ou ne comporte aucune entrée cert ou key utilisable.
Le certificat ou la clé client mTLS MCP est incorrect L'entrée cert n'est pas encodée au format PEM, ou l'entrée key n'est pas la clé privée correspondante.
Le certificat client mTLS MCP omet l'utilisation de la clé étendue clientAuth Le certificat est analysé, mais son utilisation étendue de la clé n'inclut pas clientAuth.

Cause : Le secret ou l'entrée du certificat client mTLS MCP est manquant

Le secret Kubernetes qui doit contenir le certificat client mTLS MCP n'existe pas dans l'espace de noms apigee, ou il existe sans entrée cert non vide ou sans entrée key. Le plan de données MCP ne dispose d'aucun certificat client à présenter pour ce groupe d'environnements. Par conséquent, les appels d'outils MCP vers le groupe échouent lors du handshake TLS.

Diagnostic

Exécutez la commande suivante :

kubectl -n apigee describe apigeeissue ISSUE_NAME

Remplacez ISSUE_NAME par le nom du problème, par exemple mcp-client-cert-invalid-my-org-my-virtualhost.

Le résultat doit ressembler à ce qui suit :

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

Le contenu de Spec.Details nomme le secret, le ApigeeRouteConfig et ce qui ne va pas. Exemple :

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

Solution

  1. Utilisez kubectl describe pour afficher le nom du secret Kubernetes et ApigeeRouteConfig auquel le problème appartient :

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Remplacez ISSUE_NAME par le nom du problème, par exemple mcp-client-cert-invalid-my-org-my-virtualhost.

    Dans cet exemple, ApigeeRouteConfig my-org-my-virtualhost fait référence au secret my-org-my-virtualhost-mcp.

  2. Déterminez le nom virtualhost à partir de ApigeeRouteConfig.

    Le nom de la fonction ApigeeRouteConfig est au format suivant : <Apigee organization>-<virtualhost name>.

    Dans cet exemple, my-org est l'organisation Apigee et le nom de l'hôte virtuel est my-virtualhost.

  3. Recherchez l'hôte virtuel correspondant dans votre overrides.yaml et vérifiez quel format son bloc mcpMtls utilise (voir Configurer mTLS entre le plan de données MCP et la passerelle d'entrée). Sélectionnez l'onglet correspondant, puis suivez les étapes qu'il contient.

Fichiers de certificats

Lorsque vous utilisez des chemins d'accès aux fichiers (sslCertPath, sslKeyPath, caCertPath), le chart virtualhost crée et gère les secrets à partir du contenu du fichier.

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. Vérifiez si le secret existe et comporte les deux entrées, où MCP_CLIENT_SECRET_NAME est le secret nommé dans Spec.Details. La section Data doit lister cert et key :

    kubectl -n apigee describe secret MCP_CLIENT_SECRET_NAME

    Si le secret est manquant ou ne contient pas d'entrée, assurez-vous que les fichiers référencés par mcpMtls.sslCertPath et mcpMtls.sslKeyPath existent et ne sont pas vides. L'étape suivante permet de restaurer le secret à partir de ces fragments.

  2. Mettez à niveau l'hôte virtuel pour que le chart réécrive le secret :

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

Secrets Kubernetes

Lorsque vous utilisez une référence de secret Kubernetes (sslSecret), le plan de données MCP lit les valeurs de certificat directement à partir des secrets que vous avez créés, et les mises à jour s'appliquent automatiquement. Aucun helm upgrade n'est nécessaire.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Vérifiez que le secret existe et qu'il comporte les deux entrées, où MCP_CLIENT_SECRET_NAME est le secret nommé dans Spec.Details. La section Data doit lister cert et key. Vérifiez que le nom dans mcpMtls.sslSecret correspond au secret que vous avez créé et que le secret se trouve dans l'espace de noms 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 ne vérifie pas l'existence des secrets. Seuls helm install et helm upgrade le font. Par conséquent, une exécution helm template propre ne prouve pas que ce secret est présent.

  2. Créez ou mettez à jour le secret avec le certificat et sa clé privée, où MCP_CLIENT_SECRET_NAME est le secret nommé dans Spec.Details, et MCP_CLIENT_CERT_FILE et MCP_CLIENT_KEY_FILE sont le certificat et sa clé privée :

    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 -

Le plan de données MCP récupère le secret corrigé lors de sa prochaine actualisation périodique, généralement en quelques minutes, sans redémarrage du pod, et le ApigeeIssue est retiré lors de l'analyse suivante.

Cause : Le certificat ou la clé client mTLS MCP est incorrect

L'entrée cert ne contient pas de certificat X.509 encodé au format PEM, ou l'entrée key n'est pas encodée au format PEM ou n'est pas la clé privée de ce certificat. Le plan de données MCP ne peut pas charger la paire.

Diagnostic

Exécutez la commande suivante :

kubectl -n apigee describe apigeeissue ISSUE_NAME

Remplacez ISSUE_NAME par le nom du problème, par exemple mcp-client-cert-invalid-my-org-my-virtualhost.

Le résultat doit ressembler à ce qui suit :

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

Le contenu de Spec.Details nomme le secret, le ApigeeRouteConfig et ce qui ne va pas. Exemple :

  • entry holds no PEM encoded certificate : l'entrée cert n'est pas au format PEM.
  • tls: failed to find any PEM data in key input : l'entrée key n'est pas au format PEM.
  • tls: private key does not match public key : les entrées cert et key ne sont pas associées.
  • tls: failed to parse private key : la clé ne peut pas être analysée, généralement parce qu'elle est chiffrée. L'entrée key doit être une clé privée PEM non chiffrée.

Solution

  1. Utilisez kubectl describe pour afficher le nom du secret Kubernetes et ApigeeRouteConfig auquel le problème appartient :

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Remplacez ISSUE_NAME par le nom du problème, par exemple mcp-client-cert-invalid-my-org-my-virtualhost.

    Dans cet exemple, ApigeeRouteConfig my-org-my-virtualhost fait référence au secret my-org-my-virtualhost-mcp.

  2. Déterminez le nom virtualhost à partir de ApigeeRouteConfig.

    Le nom de la fonction ApigeeRouteConfig est au format suivant : <Apigee organization>-<virtualhost name>.

    Dans cet exemple, my-org est l'organisation Apigee et le nom de l'hôte virtuel est my-virtualhost.

  3. Recherchez l'hôte virtuel correspondant dans votre overrides.yaml et vérifiez quel format son bloc mcpMtls utilise (voir Configurer mTLS entre le plan de données MCP et la passerelle d'entrée). Sélectionnez l'onglet correspondant, puis suivez les étapes qu'il contient.

Fichiers de certificats

Lorsque vous utilisez des chemins d'accès aux fichiers (sslCertPath, sslKeyPath, caCertPath), le chart virtualhost crée et gère les secrets à partir du contenu du fichier.

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. Validez le fichier de certificat et le fichier de clé référencés par mcpMtls.sslCertPath et mcpMtls.sslKeyPath, et corrigez-les si nécessaire. Le certificat doit contenir les lignes de début et de fin du certificat, et la clé doit être la clé privée correspondante. Exemple :

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. Mettez à niveau l'hôte virtuel pour que le chart réécrive le secret :

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

Secrets Kubernetes

Lorsque vous utilisez une référence de secret Kubernetes (sslSecret), le plan de données MCP lit les valeurs de certificat directement à partir des secrets que vous avez créés, et les mises à jour s'appliquent automatiquement. Aucun helm upgrade n'est nécessaire.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Validez le fichier de certificat (MCP_CLIENT_CERT_FILE) et le fichier de clé (MCP_CLIENT_KEY_FILE) que vous stockez dans les entrées cert et key du secret, et corrigez-les si nécessaire. Le certificat doit contenir les lignes de début et de fin du certificat, et la clé doit être la clé privée correspondante. Exemple :

    -----BEGIN CERTIFICATE-----
    MIIDYTCCAkmgAwIBAgIUSXeU0pQYRFzYlqZpKhNNJdBLFBIwDQYJKoZIhvcNAQEL
    ... <contents omitted> ...
    QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2Nzg5QUJDREVGR0hJSktM
    MMM=
    -----END CERTIFICATE-----
  2. Mettez à jour le secret en place avec le certificat et sa clé privée, où MCP_CLIENT_SECRET_NAME est le secret nommé dans Spec.Details, et MCP_CLIENT_CERT_FILE et MCP_CLIENT_KEY_FILE sont le certificat et sa clé privée :

    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 -

Le plan de données MCP récupère le secret corrigé lors de sa prochaine actualisation périodique, généralement en quelques minutes, sans redémarrage du pod, et le ApigeeIssue est retiré lors de l'analyse suivante.

Cause : Le certificat client MCP mTLS omet l'utilisation de la clé étendue clientAuth

Le certificat est bien formé et associé à sa clé, mais son utilisation étendue de la clé (EKU) n'inclut pas clientAuth. Il ne peut donc pas être utilisé pour l'authentification du client, et le plan de données MCP ne le présente pas. Cela se produit généralement lorsqu'un certificat de serveur ou un certificat d'un profil d'autorité de certification public qui n'émet plus de clientAuth est réutilisé.

Diagnostic

Exécutez la commande suivante :

kubectl -n apigee describe apigeeissue ISSUE_NAME

Remplacez ISSUE_NAME par le nom du problème, par exemple mcp-client-cert-invalid-my-org-my-virtualhost.

Le résultat doit ressembler à ce qui suit :

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

Le contenu de Spec.Details nomme le secret et le ApigeeRouteConfig, et liste les utilisations de clé étendues que le certificat comporte.

Solution

  1. Utilisez kubectl describe pour afficher le nom du secret Kubernetes et ApigeeRouteConfig auquel le problème appartient :

    kubectl -n apigee describe apigeeissue ISSUE_NAME

    Remplacez ISSUE_NAME par le nom du problème, par exemple mcp-client-cert-invalid-my-org-my-virtualhost.

    Dans cet exemple, ApigeeRouteConfig my-org-my-virtualhost fait référence au secret my-org-my-virtualhost-mcp.

  2. Déterminez le nom virtualhost à partir de ApigeeRouteConfig.

    Le nom de la fonction ApigeeRouteConfig est au format suivant : <Apigee organization>-<virtualhost name>.

    Dans cet exemple, my-org est l'organisation Apigee et le nom de l'hôte virtuel est my-virtualhost.

  3. Recherchez l'hôte virtuel correspondant dans votre overrides.yaml et vérifiez quel format son bloc mcpMtls utilise (voir Configurer mTLS entre le plan de données MCP et la passerelle d'entrée). Sélectionnez l'onglet correspondant, puis suivez les étapes qu'il contient.

Fichiers de certificats

Lorsque vous utilisez des chemins d'accès aux fichiers (sslCertPath, sslKeyPath, caCertPath), le chart virtualhost crée et gère les secrets à partir du contenu du fichier.

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. Réémettez le certificat client à partir de votre autorité de certification privée avec un profil incluant l'utilisation étendue de la clé clientAuth. Confirmez-le, où MCP_CLIENT_CERT_FILE est le certificat réémis, puis remplacez les fichiers référencés par mcpMtls.sslCertPath et mcpMtls.sslKeyPath :

    openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage
    # must list: TLS Web Client Authentication
  2. Mettez à niveau l'hôte virtuel pour que le chart réécrive le secret :

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

Secrets Kubernetes

Lorsque vous utilisez une référence de secret Kubernetes (sslSecret), le plan de données MCP lit les valeurs de certificat directement à partir des secrets que vous avez créés, et les mises à jour s'appliquent automatiquement. Aucun helm upgrade n'est nécessaire.

virtualhosts:
...
- name: my-virtualhost
  selector:
    app: apigee-ingressgateway
  tlsMode: MUTUAL
  sslSecret: my-ingress-secret
  mcpMtls:
    sslSecret: my-mcp-client-secret
...
  1. Réémettez le certificat client à partir de votre autorité de certification privée avec un profil incluant l'utilisation étendue de la clé clientAuth. Confirmez-le avant de mettre à jour le secret, où MCP_CLIENT_CERT_FILE est le certificat réémis :

    openssl x509 -in MCP_CLIENT_CERT_FILE -noout -ext extendedKeyUsage
    # must list: TLS Web Client Authentication
  2. Mettez à jour le secret en place avec le certificat et sa clé privée, où MCP_CLIENT_SECRET_NAME est le secret nommé dans Spec.Details, et MCP_CLIENT_CERT_FILE et MCP_CLIENT_KEY_FILE sont le certificat et sa clé privée :

    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 -

Le plan de données MCP récupère le secret corrigé lors de sa prochaine actualisation périodique, généralement en quelques minutes, sans redémarrage du pod, et le ApigeeIssue est retiré lors de l'analyse suivante.

Vous devez collecter des informations de diagnostic

Si le problème persiste, même après avoir suivi les instructions ci-dessus, rassemblez les informations de diagnostic suivantes, puis contactez Google Cloud Customer Care :

  1. L'ID du projet Google Cloud .
  2. Nom de l'organisation Apigee Hybrid
  3. Champ Spec.Details de ApigeeIssue
  4. (Facultatif) Certificat dans le fichier référencé par mcpMtls.sslCertPath ou dans l'entrée cert du secret, pour l'hôte virtuel concerné.