Activer l'authentification mTLS Southbound pour les proxys configurables

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Cet article explique comment activer l'authentification TLS mutuelle (mTLS) Southbound pour sécuriser le trafic entre votre proxy d'API configurable Apigee et les cibles et backends de proxy compatibles avec mTLS. L'authentification TLS mutuelle (mTLS) permet d'authentifier les points de terminaison des clients et des serveurs lors d'un handshake TLS, ce qui permet aux utilisateurs de s'assurer que le client et le serveur sont des entités de confiance. De nombreuses entreprises utilisent mTLS pour vérifier que tout le trafic au sein d'un réseau est fiable et sécurisé. En ajoutant la fonctionnalité mTLS aux proxys configurables, les clients Apigee peuvent gérer facilement leur utilisation actuelle de mTLS lorsqu'ils passent aux proxys configurables, ou renforcer la sécurité des communications entre les proxys configurables existants et leurs backends.

Les sections suivantes décrivent les étapes requises pour configurer la compatibilité du protocole mTLS avec le trafic Southbound (c'est-à-dire passerelle -> backend) vers les proxys configurables Apigee.

Le développement configurable du proxy d'API ^BETA n'est disponible que pour les clients disposant d'organisations d'abonnements payants sur Apigee. Les clients Apigee disposant d'organisations basées sur le Pay-as-you-go peuvent créer des proxys d'API programmables.

Présentation des concepts de l'authentification mTLS

Le schéma suivant illustre le fonctionnement du handshake mTLS entre un client et un serveur, dans ce cas, un proxy configurable et un backend cible :

mtls-diagram

Dans le schéma ci-dessus, le serveur et le client disposent tous deux d'un keystore contenant leur certificat/clé publique et leur clé privée, indiquant la possibilité d'effectuer un handshake TLS mutuel. Lors de la vérification, le client (proxy configurable) compare le certificat de son truststore avec le certificat envoyé par le serveur (backend cible).

Lorsque vous effectuez le handshake TLS :

Le serveur TLS présente son certificat au client TLS pour s'authentifier.
Le client vérifie l'identité du serveur, puis présente son propre certificat pour s'authentifier auprès du serveur.
Une fois l'authentification mutuelle effectuée, le client et le serveur calculent une clé secrète partagée pour chiffrer leurs requêtes et leurs réponses.

Déployer un proxy configurable compatible avec mTLS

La section suivante décrit les étapes requises pour déployer un proxy configurable avec l'authentification mTLS activée pour le trafic entre la passerelle et son serveur backend cible.

Étape 1 : Configurer les fichiers sources

Pour pouvoir déployer un proxy configurable compatible avec mTLS, vous devez configurer de nouveaux fichiers, y compris les suivants :

Un truststore (alias de certificat uniquement), une clé et un alias de certificat permettant à la passerelle de votre proxy configurable de communiquer avec le serveur backend cible.
un keystore Apigee contenant le truststore, la clé et le certificat décrits ci-dessus.
Un déploiement d'archive contenant les détails du keystore dans la configuration du serveur cible.

Pour créer les fichiers sources requis, procédez comme suit :

Créez les clés privées et publiques de l'autorité de certification (CA) privée à l'aide de la commande suivante :

openssl req \
  -new \
  -x509 \
  -nodes \
  -days 365 \
  -subj '/CN=my-ca' \
  -keyout RootCA.key \
  -out RootCA.pem

Créez le certificat de la passerelle, la clé privée et la demande de signature de certificat (CSR) du proxy configurable à l'aide des commandes suivantes :
```
openssl genrsa -out my_gateway.key 2048
openssl req -new -key my_gateway.key -out my_gateway.csr
```

Signez le certificat client que vous venez de créer à l'aide de l'autorité de certification créée précédemment :

openssl x509 -req -in my_gateway.csr -CA RootCA.pem \
  -CAkey RootCA.key -set_serial 01 -out my_gateway.pem -days 365 -sha256

Créez le certificat, la clé privée et la demande de signature de certificat (CSR) du serveur à l'aide des commandes suivantes :

openssl genrsa -out my_server.key 2048
openssl req -new -key my_server.key -subj '/CN=${SERVER_HOST}' -out my_server.csr

Signez le certificat du serveur que vous venez de créer à l'aide de l'autorité de certification créée précédemment :

openssl x509 -req -in my_server.csr -CA RootCA.pem \
  -CAkey RootCA.key -set_serial 01 -out my_server.pem -days 365 -sha256

Une fois ces opérations effectuées, votre répertoire doit comporter huit nouveaux fichiers, comme illustré dans l'exemple ci-dessous :

ls \
  RootCA.key
  RootCA.pem // Certificate used for the Apigee truststore
  my_gateway.csr
  my_gateway.key  // Used for the Apigee key
  my_gateway.pem // Used for the client cert alias
  my_server.csr
  my_server.key // Used for the server key
  my_server.pem // Used for the server cert

Étape 2 : Configurer le keystore

Pour créer et configurer un keystore Apigee, procédez comme suit :

Ouvrez l'interface utilisateur Apigee dans un navigateur.
Sélectionnez Admin > Environments > TLS Keystores (Administrateur > Environnements > Keystores TLS).
Cliquez sur le bouton + Keystore pour créer un keystore.
Saisissez un nom dans la boîte de dialogue New Keystore (Nouveau keystore), comme illustré dans la figure ci-dessous :
Cliquez sur Add Keystore (Ajouter un keystore).
Sur la page de destination TLS Keystores (Keystores TLS), sélectionnez la ligne du keystore que vous venez de créer, puis cliquez sur + pour créer un alias.
Sur l'écran Create new alias (Créer un alias), procédez comme suit :
- Saisissez le nom de l'alias.
- Sélectionnez Certificate and Key (Certificat et clé) dans la liste déroulante Type du panneau Certificate Details (Détails du certificat).
- Utilisez le sélecteur de fichier pour choisir le fichier de certificat du keystore créé lors d'une étape précédente.
- Saisissez un mot de passe de clé.
- Utilisez le sélecteur de fichier pour choisir le fichier de clé créé lors d'une étape précédente.
Une fois les champs remplis comme illustré dans l'image ci-dessous, cliquez sur Save (Enregistrer) pour enregistrer les détails de l'alias et du certificat.
Sur la page de destination TLS Keystores (Keystores TLS), sélectionnez la ligne du keystore que vous venez de créer, puis cliquez sur + pour créer l'alias du truststore.
Sur l'écran Create new alias (Créer un alias), procédez comme suit :
- Saisissez le nom de l'alias.
- Sélectionnez Certificate Only (Certificat uniquement) dans la liste déroulante Type du panneau Certificate Details (Détails du certificat).
- Utilisez le sélecteur de fichier pour choisir le fichier de certificat du truststore créé lors d'une étape précédente.
- Une fois les champs remplis comme illustré dans l'image ci-dessous, cliquez sur Save (Enregistrer) pour enregistrer les détails de l'alias et du certificat.

Vous disposez maintenant d'un keystore et d'un truststore dans Apigee contenant les détails TLS requis lors du déploiement de l'archive du proxy configurable avec mTLS.

Étape 3 : Mettre en forme l'archive

Maintenant que vous disposez d'un keystore contenant vos certificats et votre clé, vous pouvez créer l'archive permettant de déployer le proxy configurable avec mTLS.

Une fois terminée, la structure du fichier d'archive doit se présenter comme suit :

src/
|  main/apigee
|  |  apiproxies/helloworld
|  |  |  config.yaml
|  |  environments/dev
|  |  |  deployments.json
|  |  |  targetservers.json
…

Le fichier targetservers.json permet de conserver les références au keystore configuré à l'étape précédente. Le fichier doit contenir les références au keystore, à l'alias et au truststore créés à l'étape 2. Exemple :

#targetservers.json
[
    {
        "name": "mymtlstarget",
        "description": "An example use mTLS",
        "host": "foo",
        "port": 8080,
        "isEnabled": true,
        "sSLInfo": {
                "enabled": true,
                "clientAuthEnabled": true,
                "keyStore": "mtls_keystore",
                "keyAlias": "mtls_alias",
                "trustStore": "mtls_truststore",
                "ignoreValidationErrors": false,
                "protocols": [
                "1.2"
                ],
                }
        },
        "protocol": "HTTP"
    },
    …
]

Les seuls champs obligatoires dans la section SSLInfo du fichier targetservers.json lors de l'activation de mTLS sont les suivants :

activé
clientAuthEnabled
keyStore
keyAlias
trustStore

Vous pouvez inclure les champs facultatifs suivants :

protocols
ciphers

Vous pouvez maintenant faire référence à ce serveur cible dans votre proxy d'archive. Par exemple, apiproxies/helloworld/config.yaml peut contenir une opération semblable à celle-ci :

...
operations:
  - id: mTLSOperation
   target:
      target_server_id: "mymtlstarget"
    http_match:
      - path_template: "/foo"
        method: GET
...

Étape 4 : Déployer le proxy

Une fois l'archive configurée, déployez le proxy configurable à l'aide de la commande suivante :

$ gcloud alpha apigee archives deploy --env=ENV_NAME --org=ORG_NAME --source=PATH_TO_SOURCE

Où :

ENV_NAME est l'environnement Apigee dans lequel votre proxy doit être déployé.
ORG_NAME est le nom de votre organisation Apigee.
PATH_TO_SOURCE est le chemin relatif au répertoire source contenant la configuration de votre archive.

Exemple :

$ gcloud alpha apigee archives deploy --env=dev --org=myorg --source=src

Une fois l'opération de déploiement terminée, le message suivant doit s'afficher :

Waiting for operation [b64c2665-b5ac-43cc-9e2d-232e8895c2ed] to complete...done.

Si le déploiement échoue, consultez la section Erreurs liées au déploiement de l'archive pour résoudre les problèmes liés à cette étape.

Étape 5 : Vérifier le proxy

Une fois votre proxy déployé, vous pouvez exécuter une commande telle que la suivante pour vous assurer qu'il fonctionne comme prévu :

$ curl https://ORG_NAME-ENV_NAME.PROXY_URL

Où :

ENV_NAME est l'environnement Apigee dans lequel votre proxy doit être déployé.
ORG_NAME est le nom de votre organisation Apigee.
PROXY_URL est l'URL de votre proxy déployé.

Par exemple, si vous appelez un proxy helloworld qui doit renvoyer un message en cas de réussite :

$ curl https://myorg-dev.apigee.net/helloworld

Si votre proxy fonctionne comme prévu, le message suivant doit s'afficher :

{
        "message": "Hello world!"
}

Mettre à jour un certificat de votre proxy

Apigee ne renouvelle pas automatiquement les certificats en votre nom. Pour que vos proxys fonctionnent comme prévu, vous devrez peut-être mettre à jour les certificats utilisés par vos environnements de temps à autre. Suivez la procédure suivante pour créer un alias ou un truststore dans le même keystore que celui utilisé pour votre proxy configurable.

Pour mettre à jour un certificat d'alias, procédez comme suit :

Ouvrez l'interface utilisateur Apigee dans un navigateur.
Cliquez sur Admin > Environments > TLS Keystores (Administrateur > Environnements > Keystores TLS), puis sélectionnez le keystore que vous souhaitez mettre à jour.
Créez un objet d'alias et sélectionnez le nouveau fichier de certificat du keystore, comme décrit à l'Étape 2 : Configurer le keystore ci-dessus.

Mettez à jour le fichier targetservers.json pour référencer le nouvel objet de keystore. Exemple :

$ cat src/main/apigee/apiproxies/helloworld/apiproxy/environments/dev/targetservers.json
[
    {
        "name": "mymtlstarget",
        "description": "An example use mTLS",
        "host": "foo",
        "port": 8080,
        "isEnabled": true,
        "sSLInfo": {
                "enabled": true,
                "clientAuthEnabled": true,
                "keyStore": "mtls_keystore",
                "keyAlias": "new_mtls_alias",
                "trustStore": "mtls_truststore",
                "ignoreValidationErrors": false,
                "protocols": [
                "1.2"
                ],
                }
        },
        "protocol": "HTTP"
    },
    …
]

Déployez la nouvelle archive. Exemple :
```
$ gcloud alpha apigee archives deploy --env=ENV_NAME --org=ORG_NAME --source=PATH_TO_SOURCE
```
Où :
- ENV_NAME est l'environnement Apigee dans lequel votre proxy doit être déployé.
- ORG_NAME est le nom de votre organisation Apigee.
- PATH_TO_SOURCE est le chemin relatif au répertoire source contenant la configuration de votre archive.
Exemple :
```
$ gcloud alpha apigee archives deploy --env=dev --org=myorg --source=src
```
Une fois l'opération de déploiement terminée, le message suivant doit s'afficher :
```
Waiting for operation [b64c2665-b5ac-43cc-9e2d-232e8895c2ed] to complete...done.
```

Votre proxy doit maintenant utiliser le fichier de certificat mis à jour du keystore dans l'objet d'alias. Vérifiez que votre proxy fonctionne comme prévu en suivant la procédure de l'Étape 4 : Vérifier le proxy ci-dessus.

Pour mettre à jour le certificat d'un truststore, procédez comme suit :

Ouvrez l'interface utilisateur Apigee dans un navigateur.
Cliquez sur Admin > Environments > TLS Keystores (Administrateur > Environnements > Keystores TLS), puis sélectionnez le keystore que vous souhaitez mettre à jour.
Créez un objet d'alias et sélectionnez le nouveau fichier de certificat du keystore, comme décrit à l'Étape 2 : Configurer le keystore ci-dessus.

Mettez à jour le fichier targetservers.json pour référencer le nouvel objet de keystore. Exemple :

$ cat src/main/apigee/apiproxies/helloworld/apiproxy/environments/dev/targetservers.json
[
    {
        "name": "mymtlstarget",
        "description": "An example use mTLS",
        "host": "foo",
        "port": 8080,
        "isEnabled": true,
        "sSLInfo": {
                "enabled": true,
                "clientAuthEnabled": true,
                "keyStore": "mtls_keystore",
                "keyAlias": "mtls_alias",
                "trustStore": "new_mtls_truststore",
                "ignoreValidationErrors": false,
                "protocols": [
                "1.2"
                ],
                }
        },
        "protocol": "HTTP"
    },
    …
]

Déployez la nouvelle archive. Exemple :
```
$ gcloud alpha apigee archives deploy --env=ENV_NAME --org=ORG_NAME --source=PATH_TO_SOURCE
```
Où :
- ENV_NAME est l'environnement Apigee dans lequel votre proxy doit être déployé.
- ORG_NAME est le nom de votre organisation Apigee.
- PATH_TO_SOURCE est le chemin relatif au répertoire source contenant la configuration de votre archive.
Exemple :
```
$ gcloud alpha apigee archives deploy --env=dev --org=myorg --source=src
```
Une fois l'opération de déploiement terminée, le message suivant doit s'afficher :
```
Waiting for operation [b64c2665-b5ac-43cc-9e2d-232e8895c2ed] to complete...done.
```

Votre proxy doit maintenant utiliser le fichier de certificat mis à jour du truststore dans l'objet d'alias. Vérifiez que votre proxy fonctionne comme prévu en suivant la procédure de l'Étape 4 : Vérifier le proxy ci-dessus.

Guide de dépannage et de gestion des erreurs

Cette section décrit un certain nombre de problèmes de configuration courants et de messages d'erreur que vous pouvez rencontrer lors de la configuration de mTLS pour votre proxy configurable. Dans la mesure du possible, nous vous suggérons des solutions potentielles à ces problèmes.

Erreurs de mise à jour du keystore

Cette section décrit les erreurs que vous pouvez rencontrer lors de la mise à jour des fichiers du keystore.

Mettre à jour un alias de keystore

Si vous essayez de mettre à jour l'alias d'un truststore ou d'un keystore avec un nouveau certificat pour l'environnement d'un proxy configurable sans déployer d'archive, le message d'erreur suivant s'affiche :

Alias updates are currently disabled for configurable proxy environments. To update the certificate,
create a new alias and reference it within a new archive deployment.

Mettre à jour une référence de keystore

Si vous essayez de mettre à jour une référence de keystore pour l'environnement d'un proxy configurable sans déployer d'archive, le message d'erreur suivant s'affiche :

Reference updates are currently disabled for configurable proxy environments.
To update the reference, create a new reference and reference it within a new archive deployment.

Erreurs de déploiement d'archive

Cette section décrit les erreurs que vous pouvez rencontrer lors du déploiement de l'archive d'un proxy configurable.

Keystore manquant

Description

Dans ce scénario, le déploiement d'archive spécifié fait référence à un keystore inexistant dans son fichier targetservers.json.

Exemple

$ gcloud alpha apigee operations describe b64c2665-b5ac-43cc-9e2d-232e8895c2ed

Using Apigee organization 'myorg'
done: true
error:
  code: 3
  message: 'generic::invalid_argument: proxy "organizations/{org}/apis/{api}/revisions/1"
    contains reference(s) to invalid target server(s): target server "mtlstarget-docs"
    contains invalid TLS settings: missing required private key for "alias \"organizations/{org}/environments/{env}/keystores/does-not-exist/aliases/my_alias\"";
    missing required certificate(s) for "alias \"organizations/{org}/environments/{env}/keystores/does-not-exist/aliases/my_alias\""'
metadata:
  '@type': type.googleapis.com/google.cloud.apigee.v1.OperationMetadata
  operationType: INSERT
  state: FINISHED
  targetResourceName: organizations/{org}/environments/{env}/archiveDeployments/afjq46noszlmmgt3uh
name: organizations/{org}/operations/6b7dbb09-fa01-4cb1-8c3f-9393027b3d92
organization: {org}
uuid: 6b7dbb09-fa01-4cb1-8c3f-9393027b3d92

Solution

Pour résoudre cette erreur, vous pouvez procéder comme suit :

Créez un keystore portant le même nom que celui référencé dans le fichier targetservers.json.
Mettez à jour le fichier targetservers.json pour faire référence à un keystore Apigee valide et existant.

Alias manquant

Description

Dans ce scénario, le déploiement d'archive spécifié fait référence à un alias inexistant dans son fichier targetservers.json :

Exemple

$ gcloud alpha apigee operations describe b64c2665-b5ac-43cc-9e2d-232e8895c2ed

Using Apigee organization 'myorg'
done: true
error:
  code: 3
  message: 'generic::invalid_argument: proxy "organizations/{org}/apis/{api}/revisions/1"
    contains reference(s) to invalid target server(s): target server "mtlstarget-docs"
    contains invalid TLS settings: missing required private key for "alias \"organizations/{org}/environments/{env}/keystores/docs-keystore/aliases/does-not-exist\"";
    missing required certificate(s) for "alias \"organizations/{org}/environments/{env}/keystores/docs-keystore/aliases/does-not-exist\""'
metadata:
  '@type': type.googleapis.com/google.cloud.apigee.v1.OperationMetadata
  operationType: INSERT
  state: FINISHED
  targetResourceName: organizations/{org}/environments/{env}/archiveDeployments/knvztvpqxbpojcdi9o
name: organizations/{org}/operations/2917bb4a-ebcb-4c59-8f48-187f6423da5d
organization: {org}
uuid: 2917bb4a-ebcb-4c59-8f48-187f6423da5d

Solution

Pour résoudre cette erreur, vous pouvez procéder comme suit :

Créez un alias dans le keystore spécifié portant le même nom que celui référencé dans le fichier targetservers.json.
Mettez à jour le fichier targetservers.json pour faire référence à une combinaison de keystore et d'alias Apigee valide et existante.

Truststore manquant

Description

Dans ce scénario, le déploiement d'archive spécifié fait référence à un alias inexistant dans son fichier targetservers.json :

Exemple

$ gcloud alpha apigee operations describe b64c2665-b5ac-43cc-9e2d-232e8895c2ed

Using Apigee organization 'myorg'
done: true
error:
  code: 3
  message: 'generic::invalid_argument: proxy "organizations/{org}/apis/{api}/revisions/1"
    contains reference(s) to invalid target server(s): target server "mtlstarget-docs"
    contains invalid TLS settings: missing required certificate(s) for truststore
    "organizations/{org}/environments/{env}/keystores/does-not-exist"'
metadata:
  '@type': type.googleapis.com/google.cloud.apigee.v1.OperationMetadata
  operationType: INSERT
  state: FINISHED
  targetResourceName: organizations/{org}/environments/{env}/archiveDeployments/{archive}
name: organizations/{org}/operations/5bb2ab24-e4ba-4fb9-ab7e-d620a0672557
organization: {org}
uuid: 5bb2ab24-e4ba-4fb9-ab7e-d620a0672557

Solution

Pour résoudre cette erreur, vous pouvez procéder comme suit :

Créez un truststore dans le keystore spécifié portant le même nom que celui référencé dans le fichier targetservers.json.
Mettez à jour le fichier targetservers.json pour faire référence à une combinaison de keystore et de truststore Apigee valide et existante.

Certificat non valide pour un alias ou un truststore

Description

Dans ce scénario, le déploiement d'archive spécifié fait référence à un certificat non valide ou arrivé à expiration pour l'alias ou le truststore spécifié dans son fichier targetservers.json :

Exemple

gcloud alpha apigee operations describe b64c2665-b5ac-43cc-9e2d-232e8895c2ed

done: true
error:
  code: 3
  message: 'generic::invalid_argument: proxy "organizations/{org}/apis/{api}/revisions/1"
    contains reference(s) to invalid target server(s): target server "mtlstarget-docs"
    contains invalid TLS settings: truststore "organizations/{org}/environments/{env}/keystores/expired-keystore"
    contains an invalid certificate within alias "organizations/{org}/environments/{env}/keystores/expired-keystore/aliases/expired":
    certificate has expired'
metadata:
  '@type': type.googleapis.com/google.cloud.apigee.v1.OperationMetadata
  operationType: INSERT
  state: FINISHED
  targetResourceName: organizations/{org}/environments/{env}/archiveDeployments/{archive}
name: organizations/{org}/operations/3e28f818-8e1f-4afc-aedd-4aed29cc5519
organization: {org}
uuid: 3e28f818-8e1f-4afc-aedd-4aed29cc5519

Solution

Pour résoudre cette erreur, vous pouvez procéder comme suit :

Mettez à jour l'alias spécifié avec un nouveau certificat valide.
Mettez à jour le fichier targetservers.json pour faire référence à une combinaison de keystore et d'alias Apigee valide et existante.

Erreurs liées au trafic lors de l'exécution

Cette section décrit les erreurs que vous pouvez rencontrer lors de l'exécution.

Certificats arrivés à expiration ou non valides

Description

Si un certificat a expiré ou n'est pas valide, une erreur 503 peut s'afficher lorsque vous envoyez une requête à votre proxy configurable :

Exemple

$ curl https://myorg-dev.apigee.net/helloworld

upstream connect error or disconnect/reset before headers. reset reason: connection failure,
transport failure reason: TLS error: 268435581:SSL routines:OPENSSL_internal:CERTIFICATE_VERIFY_FAILED

Solution

Pour déterminer la cause de cette erreur, vérifiez les points suivants :

Les certificats et les clés du backend sont valides pour les certificats et les clés du proxy figurant dans le keystore référencé.
Les certificats du backend ne sont pas arrivés à expiration.
1. Ouvrez l'interface utilisateur Apigee dans un navigateur.
2. Cliquez sur Admin > Environnements > Keystores TLS (Administrateur > Environnements > Keystores TLS), puis sélectionnez votre keystore.
3. Vérifiez l'état d'expiration de vos certificats.
Le keystore référencé n'a pas été mis à jour lors du déploiement de l'archive.

Pour mettre à jour un certificat arrivé à expiration, suivez les instructions de la section Mettre à jour un certificat de votre proxy.

Activer l'authentification mTLS Southbound pour les proxys configurables Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Présentation des concepts de l'authentification mTLS

Déployer un proxy configurable compatible avec mTLS

Étape 1 : Configurer les fichiers sources

Étape 2 : Configurer le keystore

Étape 3 : Mettre en forme l'archive

Étape 4 : Déployer le proxy

Étape 5 : Vérifier le proxy

Mettre à jour un certificat de votre proxy

Guide de dépannage et de gestion des erreurs

Erreurs de mise à jour du keystore

Mettre à jour un alias de keystore

Mettre à jour une référence de keystore

Erreurs de déploiement d'archive

Keystore manquant

Description

Exemple

Solution

Alias manquant

Description

Exemple

Solution

Truststore manquant

Description

Exemple

Solution

Certificat non valide pour un alias ou un truststore

Description

Exemple

Solution

Erreurs liées au trafic lors de l'exécution

Certificats arrivés à expiration ou non valides

Description

Exemple

Solution

Activer l'authentification mTLS Southbound pour les proxys configurables