Ajout de la déconnexion comme élément dorsal du service de passerelle d'API

Découvrez comment définir un élément dorsal de déconnexion avec le service de passerelle d'API.

Une exigence courante est que les API fournissent la possibilité aux clients d'API de se déconnecter proprement en révoquant les jetons d'accès et en appelant potentiellement d'autres URL pour effectuer des tâches supplémentaires après la déconnexion. La passerelle d'API vous permet de définir des éléments dorsaux de déconnexion pour fournir une telle fonctionnalité lors de l'utilisation d'une politique d'authentification de jeton OAuth 2.0 pour un déploiement d'API. Les demandes à l'élément dorsal de déconnexion peuvent éventuellement inclure une URL après déconnexion en tant que valeur d'un paramètre d'interrogation nommé postLogoutUrl.

Lors de la définition d'une politique d'authentification par jeton OAuth 2.0, vous pouvez éventuellement spécifier un chemin vers l'élément dorsal de déconnexion (chemin de déconnexion) pour révoquer les jetons d'accès en cas d'échec de l'authentification. Voir Validation des jetons pour ajouter l'authentification et l'autorisation aux déploiements d'API.

La définition d'élément dorsal de déconnexion comprend facultativement :

Liste des URL de post-déconnexion autorisées vers lesquelles une demande peut être redirigée pour révoquer les jetons d'accès. Si le paramètre d'interrogation postLogoutUrl est inclus dans la demande, sa valeur doit être l'une de ces URL. Les URL de la liste peuvent être des chemins absolus ou des chemins relatifs, et les URL peuvent inclure des variables de contexte. Notez que si vous spécifiez un chemin relatif (c'est-à-dire vers une autre route dans le déploiement d'API), le déploiement d'API et la route doivent permettre un accès anonyme. Notez également que si vous n'incluez pas explicitement une ou plusieurs URL dans la liste, toute URL après déconnexion est autorisée.
Données à transmettre aux URL de déconnexion lorsque la demande est redirigée, en tant que valeur du paramètre d'interrogation state. Les données ne peuvent inclure que des variables de contexte (et non des valeurs statiques).

À la réception d'une demande au chemin de déconnexion d'un client d'API, la passerelle d'API vérifie que le client d'API est authentifié pour appeler l'élément dorsal de déconnexion, vérifie que toute URL de post-déconnexion incluse dans la demande est autorisée et supprime toutes les informations stockées sur la session du client d'API (par exemple, dans les témoins). En supposant que l'URL de post-déconnexion soit autorisée, ce qui se passe ensuite dépend de l'authentification du client d'API et du fait que la réponse précédemment mise en mémoire cache à partir de l'URL de détection spécifiée dans la politique d'authentification par jeton OAuth 2.0 a fourni un point d'extrémité de session d'extrémité :

Si le client d'API n'est pas authentifié, la passerelle d'API redirige la demande de déconnexion vers l'URL de post-déconnexion.
Si le client d'API est authentifié, mais que la politique d'authentification par jeton OAuth 2.0 n'a pas fourni de point d'extrémité de session de fin, la passerelle d'API redirige la demande de déconnexion vers l'URL après déconnexion et transmet les informations d'état spécifiées dans la définition d'élément dorsal de déconnexion.
Si le client d'API est authentifié et que la politique d'authentification par jeton OAuth 2.0 a fourni un point d'extrémité de session d'extrémité, la passerelle d'API redirige la demande de déconnexion vers ce point d'extrémité de session d'extrémité et transmet l'URL après déconnexion, ainsi que toutes les informations d'état spécifiées dans la définition d'élément dorsal de déconnexion. Dans ce cas, il incombe au fournisseur d'identités de rediriger la demande vers l'URL de post-déconnexion.

Vous pouvez ajouter un élément dorsal de déconnexion à une spécification de déploiement d'API comme :

En utilisant la console.
En modifiant un fichier JSON.

Utilisation de la console pour ajouter des éléments dorsaux de déconnexion à une spécification de déploiement d'API

Pour ajouter des éléments dorsaux de déconnexion à une spécification de déploiement d'API à l'aide de la console :

Créez ou mettez à jour un déploiement d'API à l'aide de la console, sélectionnez l'option À partir de zéro et entrez les détails dans la page Informations de base.

Pour plus d'informations, voir Déploiement d'une API sur une passerelle d'API en créant un déploiement d'API et Mise à jour d'une passerelle d'API.
Dans la page Authentification, spécifiez les options d'authentification.

Pour plus d'informations sur les options d'authentification, voir Ajout de l'authentification et de l'autorisation aux déploiements d'API.
Dans la page Routes, créez une route et spécifiez les données suivantes :
- Chemin : Chemin des appels d'API utilisant les méthodes indiquées au service dorsal. Notez que le chemin de routage que vous spécifiez :
  - Est relatif au préfixe du chemin du déploiement (voir Déploiement d'une API sur une passerelle d'API en créant un déploiement d'API).
  - Doit être précédé d'une barre oblique (/) et peut être simplement cette seule barre oblique.
  - Peut contenir plusieurs barres obliques (à condition qu'elles ne soient pas adjacentes) et peut se terminer par une barre oblique.
  - Peut inclure des caractères alphanumériques en majuscules et en minuscules.
  - peut inclure les caractères spéciaux $ - _ . + ! * ' ( ) , % ; : @ & =
  - Peut inclure des paramètres et des caractères génériques (voir Ajout de paramètres de chemin et de caractères génériques aux chemins de routage).
- Méthodes : Une ou plusieurs méthodes acceptées par le service dorsal. Dans le cas des éléments dorsaux de déconnexion, seule GET est acceptée.
- Type dorsal : Type du service dorsal comme Logout.
- URI de déconnexion autorisés : (facultatif) Liste d'une ou de plusieurs URL autorisées vers lesquelles une demande de déconnexion peut être redirigée pour révoquer des jetons. Les URL de la liste peuvent être des chemins absolus ou des chemins relatifs, et les URL peuvent inclure des variables de contexte. Par exemple, ["https://${request.header[tenant-id].page.html}", "https://fixed-path.page.html", "/logout_html"].
  Notez ce qui suit :
  - Une URL après déconnexion peut être incluse dans une demande à l'élément dorsal de déconnexion en tant que valeur d'un paramètre d'interrogation nommé postLogoutUrl.
  - Si vous spécifiez un chemin relatif (c'est-à-dire vers une autre route dans le déploiement d'API), le déploiement d'API et la route doivent permettre un accès anonyme.
  - Si vous n'incluez pas explicitement une ou plusieurs URL dans la liste, toute URL de post-déconnexion est autorisée.
- État après déconnexion : (facultatif) Données à transmettre lorsqu'une demande de déconnexion est redirigée vers un point d'extrémité de session de fin ou une URL après déconnexion. Les données ne peuvent inclure que des variables de contexte (et non des valeurs statiques). Par exemple, request.query[region]
  Les données sont transmises en tant que valeur du paramètre d'interrogation state.
(Facultatif) Sélectionnez Autre route pour entrer les détails des routes supplémentaires.
Sélectionnez Suivant pour vérifier les détails que vous avez entrés pour le déploiement d'API.
Sélectionnez Créer ou enregistrer les modifications pour créer ou mettre à jour le déploiement d'API.
(Facultatif) Vérifiez que l'API a été déployée avec succès en l'appelant (voir Appel d'une API déployée sur une passerelle d'API).

Modification d'un fichier JSON pour ajouter des éléments dorsaux de déconnexion à une spécification de déploiement d'API

Pour ajouter des éléments dorsaux de déconnexion à une spécification de déploiement d'API dans un fichier JSON :

Dans votre éditeur JSON préféré, modifiez la spécification de déploiement d'API existante à laquelle vous souhaitez ajouter un élément dorsal de déconnexion ou créez une spécification de déploiement d'API (voir Création d'une spécification de déploiement d'API).

Par exemple, la spécification de déploiement d'API de base suivante définit une simple fonction sans serveur Hello World d'Oracle Functions comme élément dorsal unique :
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
Dans la section routes, incluez une nouvelle section pour un élément dorsal de déconnexion :
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    },
    {
      "path": "<logout-route-path>",
      "methods": ["<method-list>"],
      "backend": {
        "type": "OAUTH2_LOGOUT",
        "allowedPostLogoutUris": ["<url>", "<url"],
        "postLogoutState": "<logout-data>"
      }
    }
  ]
}
```
où :
- <logout-route-path> indique un chemin pour les appels à l'aide des méthodes listées vers l'élément dorsal de déconnexion. Notez que le chemin de routage que vous spécifiez :
  - Est relatif au préfixe du chemin du déploiement (voir Déploiement d'une API sur une passerelle d'API en créant un déploiement d'API).
  - Doit être précédé d'une barre oblique (/) et peut être simplement cette seule barre oblique.
  - Peut contenir plusieurs barres obliques (à condition qu'elles ne soient pas adjacentes) et peut se terminer par une barre oblique.
  - Peut inclure des caractères alphanumériques en majuscules et en minuscules.
  - peut inclure les caractères spéciaux $ - _ . + ! * ' ( ) , % ; : @ & =
  - Peut inclure des paramètres et des caractères génériques (voir Ajout de paramètres de chemin et de caractères génériques aux chemins de routage).
- <method-list> indique une ou plusieurs méthodes acceptées par l'élément dorsal de déconnexion, séparées par des virgules. Dans le cas des éléments dorsaux de déconnexion, seule GET est acceptée.
- "type": "OAUTH2_LOGOUT" spécifie que l'élément dorsal est un élément dorsal de déconnexion.
- "allowedPostLogoutUris": ["<url>", "<url>"] spécifie facultativement une liste d'une ou plusieurs URL autorisées vers lesquelles une demande de déconnexion peut être redirigée pour révoquer des jetons. Les URL de la liste peuvent être des chemins absolus ou des chemins relatifs, et les URL peuvent inclure des variables de contexte. Par exemple, ["https://${request.header[tenant-id].page.html}", "https://fixed-path.page.html", "/logout_html"].
  
  Notez ce qui suit :
  - Une URL après déconnexion peut être incluse dans une demande à l'élément dorsal de déconnexion en tant que valeur d'un paramètre d'interrogation nommé postLogoutUrl.
  - Si vous spécifiez un chemin relatif (c'est-à-dire vers une autre route dans le déploiement d'API), le déploiement d'API et la route doivent permettre un accès anonyme.
  - Si vous n'incluez pas explicitement une ou plusieurs URL dans la liste, toute URL de post-déconnexion est autorisée.
- "postLogoutState": "<logout-data>" spécifie facultativement les données à transmettre lorsqu'une demande de déconnexion est redirigée vers un point d'extrémité de session d'extrémité ou une URL après déconnexion. Les données ne peuvent inclure que des variables de contexte (et non des valeurs statiques). Par exemple, request.query[region]
  
  Les données sont transmises en tant que valeur du paramètre d'interrogation state.
Dans cet exemple, une demande à l'élément dorsal /logout peut inclure l'une des URL spécifiées pour allowedPostLogoutUris comme valeur du paramètre d'interrogation postLogoutUrl. Lorsque l'URL de post-déconnexion est appelée, la valeur de la variable de contexte request.query[region] est transmise à l'URL. Notez que dans cet exemple, l'une des valeurs allowedPostLogoutUris ("/logout_html") est un chemin relatif vers l'élément dorsal de réponse standard /logout_html dans le même déploiement d'API. Comme il s'agit d'un chemin relatif vers une autre route dans le même déploiement d'API, l'élément dorsal /logout_html doit inclure une politique d'autorisation de type ANONYMOUS, comme illustré ici.
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    },
    {
      "path": "/logout",
      "methods": ["GET"],
      "backend": {
        "type": "OAUTH2_LOGOUT",
        "allowedPostLogoutUris": ["https://${request.header[tenant-id].page.html}", "/logout_html"],
        "postLogoutState": "request.query[region]"
      }
    },
    {
      "path": "/logout_html",
      "methods": ["GET"],
      "backend": {
        "type": "STOCK_RESPONSE_BACKEND",
        "body": "Token could not be revoked."
      },
      "requestPolicies": {
        "authorization": {
          "type": "ANONYMOUS"
        }
      }
    }
  ]
}
```
Enregistrez le fichier JSON contenant la spécification de déploiement d'API.
Utilisez comme suit la spécification de déploiement d'API lorsque vous créez ou mettez à jour un déploiement d'API :
- En spécifiant le fichier JSON dans la console lorsque vous sélectionnez l'option Charger une API existante.
- En spécifiant le fichier JSON dans une demande à l'API REST du service Passerelle d'API.
Pour plus d'informations, voir Déploiement d'une API sur une passerelle d'API en créant un déploiement d'API et Mise à jour d'une passerelle d'API.
(Facultatif) Vérifiez que l'API a été déployée avec succès en l'appelant (voir Appel d'une API déployée sur une passerelle d'API).

Documentation sur Oracle Cloud Infrastructure

Ajout de la déconnexion comme élément dorsal du service de passerelle d'API

Utilisation de la console pour ajouter des éléments dorsaux de déconnexion à une spécification de déploiement d'API

Modification d'un fichier JSON pour ajouter des éléments dorsaux de déconnexion à une spécification de déploiement d'API