Validation de jetons pour ajouter l'authentification et l'autorisation aux déploiements d'API
Vous pouvez ajouter des fonctionnalités d'authentification et d'autorisation à une passerelle d'API en faisant en sorte que la passerelle d'API valide elle-même les jetons inclus dans une demande (comme décrit dans cette rubrique). Vous pouvez également demander à la passerelle d'API de transmettre un jeton d'accès à arguments multiples ou à arguments uniques inclus dans une demande à une fonction d'autorisation déployée sur OCI Functions pour validation (comme décrit dans Transmission de jetons aux fonctions d'autorisation pour ajouter l'authentification et l'autorisation aux déploiements d'API).
Pour que la passerelle d'API valide elle-même le jeton inclus dans une demande, créez une stratégie de demande d'authentification de type TOKEN_AUTHENTICATION. Les jetons que vous utilisez pour contrôler l'accès aux API sont souvent, mais pas toujours, des jetons Web JSON (JWT).
Lors de l'utilisation d'une stratégie TOKEN_AUTHENTICATION, vous autorisez un déploiement d'API à utiliser des jetons pour l'authentification et l'autorisation en incluant deux types de stratégie de demande différents dans la spécification de déploiement d'API :
- Une stratégie de demande d'authentification pour l'ensemble du déploiement d'API qui définit l'utilisation des jetons, y compris la méthode de validation et indique si les utilisateurs finaux non authentifiés peuvent accéder aux routages du déploiement d'API.
- Une stratégie de demande d'autorisation pour chaque routage qui spécifie les opérations qu'un utilisateur final est autorisé à effectuer, en fonction des valeurs spécifiées dans la demande
scope
d'un jeton JWT.
Vous pouvez ajouter des stratégies de demande d'authentification et d'autorisation à une spécification de déploiement d'API en :
- Utilisation de la console.
- modifiant un fichier JSON.
Dans les versions antérieures, vous créiez des stratégies de demande d'authentification de type JWT_AUTHENTICATION afin d'utiliser des jetons JWT pour l'authentification. Les stratégies de demande d'authentification JWT_AUTHENTICATION existantes sont toujours prises en charge (reportez-vous à Remarques sur l'utilisation des stratégies de demande JWT_AUTHENTICATION). Toutefois, si vous créez des stratégies de demande d'authentification pour authentifier les jetons JWT, nous vous recommandons de créer des stratégies de demande d'authentification en tant que stratégies TOKEN_AUTHENTICATION. L'utilisation de stratégies TOKEN_AUTHENTICATION vous permet d'effectuer les opérations suivantes :
- Validez les jetons JWT et non-JWT.
- Validez les jetons à l'aide d'un fournisseur d'identités pour obtenir une adresse d'introspection.
- Indiquez les stratégies d'échec de validation, y compris la génération d'un nouveau jeton JWT en cas de jeton JWT non valide ou manquant dans la demande d'origine.
Que se passe-t-il pendant l'authentification par jeton ?
Lorsqu'une passerelle d'API reçoit une demande d'un client d'API et que vous avez indiqué une stratégie d'authentification par jeton, elle localise un jeton (par exemple, dans un en-tête de jeton) et l'utilise.
Vous indiquez comment la passerelle d'API valide le jeton obtenu en définissant la stratégie de validation de la stratégie d'authentification de jeton de l'un des types suivants :
- OAuth 2.0, adresse d'introspection : indiquez ce type de stratégie de validation pour que la passerelle d'API valide un jeton JWT ou non JWT avec l'adresse d'introspection d'un fournisseur d'identités. Vous devez indiquer l'URL de repérage du fournisseur d'identités à partir duquel obtenir l'adresse d'introspection. Dans ce cas, la passerelle d'API transmet les informations d'identification client (l'ID client, ainsi que la clé secrète client extraite du service Vault) au fournisseur d'identités pour valider le jeton. Le jeton est validé sans l'utilisation de clés publiques. Pour accélérer la validation future, vous pouvez indiquer que la passerelle d'API doit mettre en cache la réponse de l'adresse d'introspection pendant 1 heure (valeur par défaut) à 24 heures. Si vous définissez la spécification de déploiement d'API dans un fichier JSON et que vous voulez ce comportement, incluez une stratégie de validation de type
REMOTE_DISCOVERY
. - JWKS distants : indiquez ce type de stratégie de validation si vous voulez que la passerelle d'API utilise des clés de vérification publiques extraites d'un fournisseur d'identités lors de l'exécution pour vérifier un jeton JWT. Dans ce cas, la passerelle d'API contacte le fournisseur d'identités pour vérifier le jeton JWT. Le fournisseur d'identités agit en tant que serveur d'autorisation. Si vous définissez la spécification de déploiement d'API dans un fichier JSON et que vous voulez ce comportement, incluez une stratégie de validation de type
REMOTE_JWKS
. - Clés statiques : indiquez ce type de stratégie de validation si vous voulez que la passerelle d'API utilise des clés de vérification publiques déjà émises par un fournisseur d'identités (appelées "clés statiques") pour vérifier un jeton JWT. Dans ce cas, la passerelle d'API peut vérifier le jeton JWT localement lors de l'exécution sans avoir à contacter le fournisseur d'identités. Cela permet de valider plus rapidement les jetons. Si vous définissez la spécification de déploiement d'API dans un fichier JSON et que vous voulez ce comportement, incluez une stratégie de validation de type
STATIC_KEYS
Si la validation réussit, la passerelle d'API achemine la demande vers l'adresse d'API appropriée.
Si la validation échoue en raison d'un jeton non valide ou manquant dans la demande d'origine, vous indiquez le comportement de la passerelle d'API en définissant la stratégie d'échec de validation de la stratégie d'authentification de jeton comme étant l'un des types suivants :
- Valeur par défaut (HTTP 401 non autorisé) : indiquez ce type de stratégie d'échec de validation si vous voulez que la passerelle d'API renvoie une réponse HTTP-401 au client d'API. Il s'agit de la réponse par défaut. Si vous définissez la spécification de déploiement d'API dans un fichier JSON et que vous souhaitez ce comportement, n'incluez simplement pas de stratégie d'échec de validation.
- Réponse personnalisée : indiquez ce type de stratégie d'échec de validation si vous voulez que la passerelle d'API renvoie une autre réponse (une réponse modifiée) au client d'API, au lieu d'une réponse HTTP-401. Si vous définissez la spécification de déploiement d'API dans un fichier JSON et que vous souhaitez ce comportement, incluez une stratégie d'échec de validation de type
MODIFY_RESPONSE
. - OAuth 2.0 : indiquez ce type de stratégie d'échec de validation si vous voulez que la passerelle d'API obtienne un jeton JWT nouveau et valide auprès du fournisseur d'identités pour les demandes GET (ayant d'abord stocké en toute sécurité les paramètres de requête de demande d'origine). Pour les demandes PUT et POST, vous pouvez indiquer un chemin relatif dans le déploiement d'API en cours vers lequel rediriger les clients d'API. A l'aide de ce type de stratégie d'échec de validation, vous pouvez également définir un back-end de déconnexion pour enlever les cookies de session associés, révoquer les jetons en appelant l'adresse de session de fin du fournisseur d'identités et rediriger vers une URL de post-déconnexion autorisée. Si vous définissez la spécification de déploiement d'API dans un fichier JSON et que vous souhaitez ce comportement, incluez une stratégie d'échec de validation de type
OAUTH2
.Les stratégies d'échec de validation de type OAuth 2.0 prennent actuellement en charge uniquement le flux d'autorisation OpenID Connect et uniquement la génération de jeton JWT (reportez-vous à Remarques sur OAuth 2.0 et OpenID Connect). Dans le cas du flux d'autorisation OpenID Connect, deux jetons nommés
id_token
(toujours encodés par JWT) etaccess_token
(peut être encodés par JWT) sont renvoyés. La passerelle d'API enregistre les valeurs de jeton dans les variables de contexterequest.auth[id_token]
etrequest.auth[access_token]
, ainsi que les demandes personnalisées dans les variables de contexterequest.auth[id_token_claims][<claim-name>]
etrequest.auth[access_token_claims][<claim-name>]
respectivement (reportez-vous à Ajout de variables de contexte aux stratégies et aux définitions de back-end HTTP). A la réception du nouveau jeton JWTid_token
, la passerelle d'API extrait les détails de la demande et reprend le traitement de la demande à l'aide du jeton.
L'emplacement à partir duquel la passerelle d'API obtient un jeton dépend à la fois du type de stratégie de validation (l'une de OAuth 2.0, adresse d'introspection, JWKS distant ou Clés statiques) et du type de stratégie d'échec de validation (l'une de Valeur par défaut (HTTP 401 non autorisé), Réponse personnalisée ou OAuth 2.0), comme suit :
- Si vous indiquez à la fois une stratégie de validation de type OAuth 2.0, adresse d'introspection et une stratégie d'échec de validation de type OAuth 2.0, la passerelle d'API tente d'abord d'obtenir le jeton à partir de l'un ou l'autre des éléments suivants :
- Si vous avez sélectionné l'option Utiliser les cookies pour la session dans la stratégie d'échec de validation, à partir d'un cookie de session.
- Sinon, à partir de l'en-tête X-APIGW-TOKEN de la demande.
Si la passerelle d'API ne peut pas obtenir de jeton à partir de l'emplacement initial, elle obtient le jeton à partir de l'en-tête de demande ou du paramètre de requête indiqué dans la stratégie d'authentification de jeton.
Si la validation de jeton réussit par la suite et que vous avez sélectionné l'option Utiliser les cookies pour la session, la passerelle d'API stocke le jeton généré en tant que chaîne non lisible par l'homme dans un cookie de session. Si le client API effectue une demande ultérieure, le jeton est obtenu à partir du cookie de session. Pour empêcher les attaques CSRF, lorsque le jeton généré est stocké dans un cookie de session, la passerelle d'API renvoie également un jeton CSRF dans un en-tête de réponse X-CSRF-TOKEN (reportez-vous à Remarques sur la protection CSRF (Cross-Site Request Forgery)).
- Si vous n'indiquez pas à la fois une stratégie de validation de type OAuth 2.0, adresse d'introspection et une stratégie d'échec de validation de type OAuth 2.0, la passerelle d'API obtient le jeton à partir de l'en-tête de demande ou du paramètre de requête que vous indiquez dans la stratégie d'authentification par jeton.
Remarques sur les jetons Web JSON (JWT)
Les jetons que vous utilisez pour contrôler l'accès aux API sont généralement des jetons Web JSON (JWT). Un jeton JWT est un jeton d'accès JSON envoyé dans une demande HTTP d'un client d'API vers une ressource. Les JWT sont émis par des fournisseurs d'identités. API Gateway prend en charge l'utilisation de n'importe quel fournisseur d'identités compatible OAuth2, tel qu'OCI IAM avec des domaines d'identité, Oracle Identity Cloud Service (IDCS), Auth0 et Okta. Si un jeton JWT est requis pour accéder à une ressource, la ressource le valide auprès d'un serveur d'autorisation à l'aide d'une clé de vérification publique correspondante, soit en appelant une adresse de validation sur le serveur d'autorisation, soit en utilisant une clé de vérification locale fournie par le serveur d'autorisation.
Un jeton JWT se compose des éléments suivants :
- Un en-tête servant à identifier le type de jeton et l'algorithme de cryptage à utiliser pour générer la signature.
- Une charge utile contenant les demandes relatives à l'identité de l'utilisateur final ainsi que les propriétés du jeton JWT lui-même. Une demande est une paire clé-valeur, où la clé correspond au nom de la demande. L'ajout de charge utile est recommandé (bien que non requis) pour contenir des demandes réservées portant des noms particuliers, comme celles de délai d'expiration (
exp
), de public (aud
), d'émetteur (iss
) et de début de validité (nbf
). La charge utile peut également contenir des demandes personnalisées portant des noms définis par l'utilisateur. - Une signature permettant de valider l'authenticité du jeton JWT (dérivée en encodant l'en-tête et la charge utile en base64).
Lorsque vous utilisez des jetons JWT pour contrôler l'accès aux API, vous pouvez indiquer que les demandes réservées dans la charge utile du jeton JWT doivent avoir des valeurs particulières avant que la passerelle d'API ne considère le jeton JWT comme valide. Par défaut, les passerelles d'API valident les jetons JWT à l'aide des demandes d'expiration (exp
), de public (aud
) et d'émetteur (iss
), ainsi qu'à l'aide de la demande de début de validité (nbf
) si elle est présente. Vous pouvez également spécifier des valeurs acceptables pour les demandes personnalisées. Reportez-vous à Détails de fournisseur d'identités à utiliser pour les demandes iss et aud, ainsi que pour l'URI de l'ensemble de clés Web JSON (JWKS).
Lorsqu'un jeton JWT a été validé, la passerelle d'API extrait les demandes à partir de la charge utile du jeton JWT sous forme de paires clé-valeur et les enregistre sous forme d'enregistrements dans la table de contexte request.auth
afin qu'elles puissent être utilisées par le déploiement d'API. Par exemple, en tant que variables de contexte à utiliser dans une définition de back-end HTTP (reportez-vous à Ajout de variables de contexte aux stratégies et aux définitions de back-end HTTP). Si la charge utile du jeton JWT contient la demande scope
, vous pouvez utiliser les valeurs de la demande dans des stratégies de demande d'autorisation propres à des routages afin d'indiquer les opérations qu'un utilisateur final est autorisé à effectuer.
Remarques sur OAuth 2.0 et OpenID Connect
Le protocole OAuth 2.0 permet d'extraire en toute sécurité des ressources sécurisées tout en protégeant les informations d'identification client. OAuth 2.0 est un protocole flexible et sécurisé qui s'appuie sur SSL (Secure Sockets Layer) pour garantir que les données entre les serveurs Web et les navigateurs restent privées. Bien que OAuth 2.0 soit différent de JWT et utilisé à des fins différentes, OAuth 2.0 et JWT sont compatibles. Etant donné que le protocole OAuth2 ne spécifie pas le format des jetons, les jetons JWT peuvent être intégrés à l'utilisation de OAuth2. Pour plus d'informations sur OAuth 2.0, reportez-vous à la documentation OAuth 2.0.
OpenID Connect est une couche d'identité simple au-dessus du protocole OAuth 2.0. L'utilisation d'OpenID Connect permet aux passerelles d'API de vérifier l'identité d'un client d'API en fonction de l'authentification effectuée par un serveur d'autorisation. OpenID Connect permet également aux passerelles d'API d'obtenir des informations de profil de base sur le client d'API. Pour plus d'informations sur OpenID Connect, reportez-vous à la documentation OpenID Connect.
Remarques concernant la protection CSRF (Cross-Site Request Forgery)
Un attaquant peut monter une attaque CSRF en exploitant l'existence d'un cookie de navigateur pour amener un utilisateur à soumettre une commande non intentionnelle à une application Web, telle qu'une passerelle d'API. Si l'application détermine que l'utilisateur a déjà été authentifié avec succès en raison de l'existence du cookie du navigateur, l'application exécute la commande avec des conséquences potentiellement dommageables.
Lorsque vous définissez une stratégie de validation de type OAuth 2.0, adresse d'introspection et une stratégie d'échec de validation de type OAuth 2.0, vous indiquez comment une passerelle d'API stocke un nouveau jeton JWT obtenu à l'aide du flux d'autorisation OpenID Connect :
- Sélectionnez l'option Utiliser les cookies pour la session si vous souhaitez stocker le nouveau jeton JWT dans un cookie de session. Pour éviter d'éventuelles attaques CSRF, lorsque la passerelle d'API stocke le jeton dans un cookie de session, elle renvoie également un jeton CSRF dans un en-tête de réponse X-CSRF-TOKEN. Les demandes de mutation suivantes adressées à la passerelle d'API (telles que les demandes POST, PUT et DELETE, mais pas les demandes GET) doivent inclure le jeton CSRF dans un en-tête de demande X-CSRF-TOKEN, en plus du jeton JWT dans le cookie de session inclus automatiquement.
La passerelle d'API stocke également le jeton CSRF dans la variable de contexte
request.auth[apigw_csrf_token]
. Si le client d'API ne parvient pas à lire l'en-tête de réponse X-CSRF-TOKEN initial pour une raison quelconque, vous pouvez inclure la variable de contexterequest.auth[apigw_csrf_token]
dans une stratégie de réponse de transformation d'en-tête pour ajouter un en-tête de réponse contenant le jeton CSRF à chaque réponse renvoyée au client d'API. Cette approche garantit que le client API peut extraire le jeton CSRF de l'en-tête de réponse pour l'inclure dans les en-têtes de demande de mutation X-CSRF-TOKEN suivants qu'il envoie à la passerelle API. Voici un exemple de stratégie de réponse de transformation d'en-tête appropriée :"responsePolicies": { "headerTransformations": { "setHeaders": { "items": [ { "name": "MY-CSRF-TOKEN", "values": ["${request.auth[apigw_csrf_token]}"], "ifExists": "OVERWRITE" } ] } } }
Pour plus d'informations sur les stratégies de réponse de transformation d'en-tête, reportez-vous à Ajout de stratégies de réponse de transformation d'en-tête.
- Ne sélectionnez pas l'option Utiliser les cookies pour la session si vous ne voulez pas stocker le nouveau jeton JWT dans un cookie de session. A la place, la passerelle d'API renvoie un jeton non lisible par l'homme dans un en-tête de réponse X-APIGW-TOKEN. Les demandes suivantes adressées à la passerelle d'API doivent inclure le même jeton dans un en-tête de demande X-APIGW-TOKEN.
Pour plus d'informations sur CSRF, effectuez une recherche en ligne.
Remarques sur l'utilisation des stratégies de demande JWT_AUTHENTICATION
Dans les versions antérieures, vous pouviez avoir créé des stratégies de demande d'authentification de type JWT_AUTHENTICATION pour utiliser des jetons JWT pour l'authentification.
Si vous créez des stratégies de demande d'authentification pour utiliser des jetons JWT, nous vous recommandons maintenant de créer des stratégies de demande d'authentification de type TOKEN_AUTHENTICATION à la place (reportez-vous à Utilisation de la console pour ajouter des stratégies de demande d'autorisation et d'authentification de jeton et à Modification d'un fichier JSON pour ajouter des stratégies de demande d'autorisation et d'authentification de jeton). Nous vous recommandons également de migrer les stratégies de demande JWT_AUTHENTICATION existantes vers les stratégies TOKEN_AUTHENTICATION.
Les stratégies de demande JWT_AUTHENTICATION existantes sont toujours prises en charge. Bien que vous puissiez créer des stratégies de demande JWT_AUTHENTICATION (comme décrit dans les instructions d'origine dans la section Utilisation d'une stratégie de demande d'authentification JWT_AUTHENTICATION (plus recommandée)), nous vous recommandons de créer des stratégies de demande d'authentification de type TOKEN_AUTHENTICATION à la place.
Prérequis pour l'authentification par jeton
Afin de pouvoir activer l'authentification et l'autorisation pour les déploiements d'API à l'aide de jetons JWT, vous devez remplir les conditions suivantes :
- Un fournisseur d'identités compatible OAuth2 (par exemple, OCI IAM avec des domaines d'identité, Oracle Identity Cloud Service (IDCS) ou Auth0) doit déjà être configuré afin d'émettre des JWT pour les utilisateurs autorisés à accéder au déploiement d'API.
- Si vous voulez utiliser des demandes personnalisées dans les stratégies d'autorisation, le fournisseur d'identités doit être configuré de façon à ajouter ces demandes personnalisées aux jetons JWT qu'il émet.
Reportez-vous à la documentation du fournisseur d'identités pour plus d'informations (par exemple, la documentation d'OCI IAM avec des domaines d'identité, la documentation d'Oracle Identity Cloud Service (IDCS) ou la documentation Auth0).
Pour valider un jeton JWT à l'aide d'une clé de vérification publique correspondante fournie par le fournisseur d'identités sortant, procédez comme suit :
- L'algorithme de signature utilisé pour générer la signature du jeton JWT doit être RS256, RS384 ou RS512.
- La longueur de la clé de vérification publique doit être comprise en 2048 et 4096 bits.
Pour valider des jetons à l'aide de l'adresse d'introspection d'un serveur d'autorisation, procédez comme suit :
- Vous devez avoir déjà créé et enregistré une application client auprès du serveur d'autorisation pour obtenir des informations d'identification client (un ID client et une clé secrète client). Reportez-vous à la documentation du serveur d'autorisation pour plus d'informations (par exemple, la documentation d'OCI IAM with Identity Domains, la documentation d'Oracle Identity Cloud Service (IDCS) ou la documentation Auth0).
- Vous devez avoir déjà stocké la clé secrète client obtenue à partir du serveur d'autorisation en tant que clé secrète dans un coffre du service Vault (reportez-vous à Création d'une clé secrète dans un coffre), et vous devez connaître l'OCID et le numéro de version de la clé secrète.
- Vous devez déjà avoir configuré une stratégie pour autoriser les passerelles d'API d'un groupe dynamique à accéder à la clé secrète de coffre contenant la clé secrète client (reportez-vous à Création d'une stratégie pour autoriser les passerelles d'API à accéder aux informations d'identification stockées en tant que clés secrètes dans le service Vault).
Utilisation de la console afin d'ajouter des stratégies de demande d'autorisation et d'authentification par jeton
Pour ajouter des stratégies de demande d'authentification et d'autorisation à une spécification de déploiement d'API à l'aide de la console, procédez comme suit :
-
Créez ou mettez à jour un déploiement d'API à l'aide de la console, sélectionnez l'option Entièrement nouveau, puis saisissez les détails sur la page Informations de base.
Pour plus d'informations, reportez-vous à 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.
- Sélectionnez Suivant pour afficher la page Authentification.
-
Sélectionnez Authentification unique pour indiquer que vous souhaitez utiliser un serveur d'authentification unique pour toutes les demandes.
Ces instructions supposent que vous souhaitez utiliser un seul serveur d'authentification. Si vous souhaitez utiliser plusieurs serveurs d'authentification, vous pouvez également sélectionner Authentification multiple et suivre les instructions de la section Utilisation de la console pour ajouter plusieurs serveurs d'authentification au même déploiement d'API.
-
Cochez ou désélectionnez la case Activer l'accès anonyme : pour indiquer si les utilisateurs finals non authentifiés (c'est-à-dire anonymes) peuvent accéder aux routages dans le déploiement d'API.
Par défaut, cette option n'est pas sélectionnée. Si vous voulez que les utilisateurs anonymes ne puissent jamais accéder aux routages, ne sélectionnez pas cette option. Si vous sélectionnez cette option, vous devez également indiquer explicitement tous les routages auxquels l'accès anonyme est autorisé en sélectionnant Anonyme comme type d'autorisation dans la stratégie d'autorisation de chaque routage.
- Sélectionnez OAuth 2.0 / OpenID Connect dans la liste d'options Type d'authentification et indiquez les éléments suivants :
- Emplacement du jeton : indique si les jetons sont contenus dans un en-tête de demande ou dans un paramètre de requête.
-
Détails du jeton d'authentification : selon que les jetons sont contenus dans un en-tête de demande ou un paramètre de requête, indiquez les éléments suivants :
- Nom d'en-tête de jeton : et Modèle d'authentification : si les jetons sont contenus dans un en-tête de demande, renseignez le nom de l'en-tête (par exemple,
Authorization
) et le modèle d'authentification HTTPS (seulBearer
est actuellement pris en charge). - Nom de paramètre de jeton : si des jetons sont contenus dans un paramètre de requête, saisissez le nom de ce dernier.
- Nom d'en-tête de jeton : et Modèle d'authentification : si les jetons sont contenus dans un en-tête de demande, renseignez le nom de l'en-tête (par exemple,
- Indiquer comment la passerelle d'API doit valider les jetons :
-
Si vous voulez que la passerelle d'API valide à la fois les jetons JWT et les jetons non JWT à l'aide d'une adresse d'introspection de serveur d'autorisation OAuth 2.0 à l'aide d'informations d'identification client (y compris une clé secrète client extraite d'un coffre dans le service Vault), sélectionnez OAuth 2.0, adresse d'introspection dans la liste Type et indiquez les éléments suivants :
- ID client : ID client à envoyer à l'adresse d'introspection. Pour obtenir un ID client, créez et enregistrez une application client auprès du serveur d'autorisation. Par exemple :
5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1
. Reportez-vous à Prérequis pour l'authentification par jeton. - Coffre dans <compartment-name> : nom d'un coffre dans le service Vault contenant la clé secrète client à envoyer à l'adresse d'introspection. Pour obtenir une clé secrète client, créez et enregistrez une application client auprès du serveur d'autorisation. Reportez-vous à Prérequis pour l'authentification par jeton.
- Clé secrète de coffre dans <compartment name> : nom d'une clé secrète de coffre contenant la clé secrète client à envoyer à l'adresse d'introspection.
- Numéro de version de clé secrète de coffre : version de la clé secrète de coffre contenant la clé secrète client à envoyer à l'adresse d'introspection.
- URL de repérage : URL connue du serveur d'autorisation à partir duquel la passerelle d'API doit obtenir des adresses de métadonnées d'autorisation. Par exemple,
https://my-idp/oauth2/default/.well-known/openid-configuration
.L'URL doit pouvoir être acheminée à partir du sous-réseau contenant la passerelle d'API sur laquelle l'API est déployée.
- Durée maximale de cache en heures : nombre d'heures (compris entre 1 et 24) pendant lesquelles la passerelle d'API doit mettre en cache la réponse de l'adresse d'introspection.
- Ecart d'horloge maximal en secondes : (facultatif) écart de temps maximal entre les horloges système du serveur d'autorisation qui a émis un jeton et la passerelle d'API. La valeur saisie ici est prise en compte lorsque la passerelle d'API valide un jeton JWT afin de déterminer sa validité à l'aide de la demande de début (
nbf
), si elle est présente, et de la demande d'expiration (exp
) du jeton JWT. La valeur minimale (par défaut) est0
et la valeur maximale est120
. - désactiver la vérification SSL : permet de désactiver la vérification SSL lors de la communication avec le serveur d'autorisation. Par défaut, cette option n'est pas sélectionnée. Oracle vous recommande de ne pas sélectionner cette option car elle peut compromettre la validation du jeton. API Gateway accepte les certificats de plusieurs autorités de certification émis pour OCI IAM avec des domaines d'identité, Oracle Identity Cloud Service (IDCS), Auth0 et Okta.
- ID client : ID client à envoyer à l'adresse d'introspection. Pour obtenir un ID client, créez et enregistrez une application client auprès du serveur d'autorisation. Par exemple :
-
Si vous voulez que la passerelle d'API valide les jetons JWT en extrayant les clés de vérification publiques à partir du fournisseur d'identités lors de l'exécution, sélectionnez JWKS distant dans la liste Type et indiquez les informations suivantes :
-
URI JWKS : URI à partir duquel extraire l'ensemble de clés Web JSON (JWKS) à utiliser pour vérifier la signature sur les jetons JWT. Par exemple, https://www.somejwksprovider.com/oauth2/v3/certs. Pour plus d'informations sur l'URI à indiquer, reportez-vous à Détails de fournisseur d'identités à utiliser pour les demandes iss et aud, ainsi que pour l'URI de l'ensemble de clés Web JSON (JWKS).
Tenez compte des points suivants :
-
L'URI doit pouvoir être acheminé à partir du sous-réseau contenant la passerelle d'API sur laquelle l'API est déployée.
- Si la passerelle d'API ne parvient pas à extraire l'ensemble JWKS, toutes les demandes de déploiement d'API renvoient un code de réponse HTTP 500. Pour plus d'informations sur cette erreur, consultez le journal d'exécution de la passerelle d'API (reportez-vous à Ajout de la journalisation aux déploiements d'API).
- L'ensemble JWKS doit contenir certains paramètres de clé pour vérifier la signature du jeton JWT (reportez-vous à Paramètres de clé requis pour vérifier les signatures de jeton JWT).
- Le JWKS peut contenir jusqu'à dix clés.
-
- Durée maximale de cache en heures : nombre d'heures (compris entre 1 et 24) pendant lesquelles la passerelle d'API doit mettre en mémoire cache JWKS après son extraction.
- désactiver la vérification SSL : permet de désactiver la vérification SSL lors de la communication avec le fournisseur d'identités. Par défaut, cette option n'est pas sélectionnée. Oracle vous recommande de ne pas sélectionner cette option car elle peut compromettre la validation du jeton JWT. API Gateway accepte les certificats de plusieurs autorités de certification émis pour OCI IAM avec des domaines d'identité, Oracle Identity Cloud Service (IDCS), Auth0 et Okta.
-
-
Si vous voulez que la passerelle d'API valide les jetons JWT à l'aide de clés de vérification publiques déjà émises par un fournisseur d'identités (ce qui permet à la passerelle d'API de vérifier les jetons JWT localement sans avoir à contacter le fournisseur d'identités), sélectionnez Clé statique dans la liste Type et indiquez jusqu'à dix clés statiques :
- ID de clé : identificateur de la clé statique utilisée pour signer le jeton JWT. La valeur doit correspondre à la demande
kid
dans l'en-tête du jeton JWT. Par exemple,master_key
. -
Format de clé : format de la clé statique, comme une clé Web JSON ou une clé publique encodée au format PEM.
-
clé Web JSON : si la clé statique est une clé Web JSON, collez-la dans ce champ.
Par exemple :
{ "kty": "RSA", "n": "0vx7agoebGc...KnqDKgw", "e": "AQAB", "alg": "RS256", "use": "sig" }
La clé statique doit contenir certains paramètres pour vérifier la signature du jeton JWT (reportez-vous à Paramètres de clé requis pour vérifier les signatures de jeton JWT). Le seul type de clé (
kty
) actuellement pris en charge estRSA
. -
clé publique codée PEM : si la clé statique est une clé publique codée au format PEM, collez-la dans ce champ. Par exemple :
-----BEGIN PUBLIC KEY----- XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO2mxwlL5/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7plfZVPX7XORvezwqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG6tzobwig8M2KIrPjJ0BmbJAFH -----END PUBLIC KEY-----
Les marqueurs
-----BEGIN PUBLIC KEY-----
et-----END PUBLIC KEY-----
sont requis.
-
- Une autre clé : sélectionnez cette option pour ajouter des clés supplémentaires (dans la limite de dix).
- ID de clé : identificateur de la clé statique utilisée pour signer le jeton JWT. La valeur doit correspondre à la demande
-
- (Facultatif) Indiquez des détails supplémentaires pour la validation de jeton JWT :
-
Dans la section Emetteurs, indiquez les valeurs autorisées dans la demande d'émetteur (
iss
) d'un jeton JWT utilisé pour accéder au déploiement d'API :-
Emetteurs autorisés : indiquez l'URL (ou la chaîne de texte) d'un fournisseur d'identités autorisé dans la demande d'émetteur (
iss
) d'un jeton JWT utilisé pour accéder au déploiement d'API. Par exemple, pour permettre l'utilisation d'un jeton JWT émis par OCI IAM avec des domaines d'identité afin d'accéder au déploiement d'API, entrezhttps://identity.oraclecloud.com/
. Reportez-vous à Détails de fournisseur d'identités à utiliser pour les demandes iss et aud, ainsi que pour l'URI de l'ensemble de clés Web JSON (JWKS). - Autre émetteur : sélectionnez cette option pour ajouter des fournisseurs d'identités supplémentaires (dans la limite de cinq).
-
Emetteurs autorisés : indiquez l'URL (ou la chaîne de texte) d'un fournisseur d'identités autorisé dans la demande d'émetteur (
-
Dans la section Publics, indiquez les valeurs autorisées dans la demande de public (
aud
) d'un jeton JWT utilisé pour accéder au déploiement d'API :-
Publics autorisés : indiquez une valeur autorisée dans la demande de public (
aud
) d'un jeton JWT afin d'identifier le destinataire prévu du jeton. Par exemple, le public peut correspondre, entre autres, au nom d'hôte de la passerelle d'API. Reportez-vous à Détails de fournisseur d'identités à utiliser pour les demandes iss et aud, ainsi que pour l'URI de l'ensemble de clés Web JSON (JWKS). - Autre public : sélectionnez cette option pour ajouter des publics supplémentaires (cinq au maximum).
-
Publics autorisés : indiquez une valeur autorisée dans la demande de public (
-
Validation des demandes : (Facultatif) En plus des valeurs des demandes de public
aud
et d'émetteuriss
que vous avez déjà indiquées, vous pouvez indiquer les noms et les valeurs de demandes supplémentaires à valider dans un jeton JWT. Les noms et les valeurs de clé que vous saisissez sont simplement traités comme des chaînes et doivent correspondre exactement aux noms et aux valeurs du jeton JWT. La correspondance de motifs et les autres types de données ne sont pas pris en charge.- La demande est requise : indiquez si la demande indiquée dans le champ clé de demande doit être incluse dans le jeton JWT.
-
clé de demande : (facultatif) indiquez le nom d'une demande qui peut ou doit être incluse dans un jeton JWT. Si la demande doit être incluse dans le jeton JWT, sélectionnez Requis. Le nom de demande que vous indiquez peut être un nom de demande réservée, comme la demande de sujet (
sub
), ou un nom de demande personnalisée émise par un fournisseur d'identités précis. - Valeur de demande : (facultatif) indiquez une valeur acceptable pour la demande indiquée dans le champ clé de demande. Sélectionnez le signe plus (+) pour saisir une autre valeur acceptable. Si vous indiquez des valeurs acceptables pour la demande, la passerelle d'API vérifie que la demande comporte l'une de ces valeurs.
Vous pouvez indiquer une réclamation dans un jeton JWT sans indiquer de valeur. Pour ce faire, entrez le nom de la réclamation dans le champ Clé de la réclamation, laissez le champ Valeurs de la réclamation vide et définissez La réclamation est requise, le cas échéant.
-
- Indiquez comment la passerelle d'API doit gérer une réponse d'authentification en échec (renvoyée après une tentative infructueuse de validation d'un jeton manquant ou non valide) en configurant une stratégie d'échec de validation :
- Si vous voulez que la passerelle d'API envoie un code de statut HTTP 401 et l'en-tête
WWW-Authenticate
dans la réponse (réponse par défaut à un jeton manquant ou non valide), sélectionnez Par défaut (HTTP 401 non autorisé). -
Si vous voulez que la passerelle d'API utilise un flux d'autorisation OpenID Connect pour obtenir un nouveau jeton d'accès JWT, sélectionnez OAuth 2.0. Cette option n'est disponible que si vous avez sélectionné l'adresse d'introspection OAuth 2.0 dans la liste Type de validation précédemment. Indiquez l'une des valeurs suivantes :
- Portées : portées d'accès à inclure dans une demande
scope
envoyée au serveur d'autorisation. Pour utiliser le flux d'autorisation OpenID Connect, vous devez inclureopenid
comme l'une des portées. Par exemple,openid
,email:read
,profile
. - Type de réponse : type de réponse requis dans le flux d'autorisation. Entrez
code
comme type de réponse. - Chemin de redirection de retour : (facultatif) chemin relatif dans le déploiement d'API en cours vers lequel rediriger les clients d'API si la demande d'origine était une demande PUT ou POST. Par exemple,
/home
Si la demande d'origine était une demande GET, le traitement de la demande reprend avec un nouveau jeton d'accès JWT, de sorte qu'aucun chemin de restauration n'est utilisé.
- Chemin de déconnexion : (facultatif) chemin relatif vers un back-end de déconnexion dans le déploiement d'API en cours. Le chemin spécifié doit correspondre au chemin de routage défini pour le back-end de déconnexion. Par exemple,
/revoke
Un client API peut appeler le back-end de déconnexion pour révoquer les jetons. Un appel vers le back-end de déconnexion peut inclure une URL après déconnexion en tant que paramètre de requête nommé
postLogoutUrl
. Reportez-vous à Ajout de la déconnexion en tant que back-end de passerelle d'API. - Expiration de la réponse en heures : (facultatif) durée de mise en cache du jeton JWT généré par le flux d'autorisation. La valeur par défaut est d'une heure.
- Utilisez les informations d'identification de client d'adresse d'introspection OAuth2 : indiquez si vous souhaitez utiliser les mêmes détails de client que ceux précédemment indiqués pour l'adresse d'introspection OAuth 2.0 afin d'obtenir un nouveau jeton d'accès JWT (ce qui est généralement le cas). Si vous ne souhaitez pas utiliser les détails que vous avez spécifiés précédemment, entrez les différents détails client à utiliser pour obtenir un nouveau jeton d'accès JWT à partir du serveur d'autorisation, comme suit :
- ID client : ID client à envoyer à l'adresse d'introspection. Par exemple,
5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1
- Coffre dans <compartment-name> : nom d'un coffre dans le service Vault contenant la clé secrète client à envoyer à l'adresse d'introspection.
- Clé secrète de coffre dans <compartment name> : nom de la clé secrète de coffre contenant la clé secrète client à envoyer à l'adresse d'introspection.
- Numéro de version de clé secrète de coffre : version de la clé secrète de coffre contenant la clé secrète client à envoyer à l'adresse d'introspection.
- ID client : ID client à envoyer à l'adresse d'introspection. Par exemple,
Vous pouvez éventuellement choisir de stocker dans les cookies les jetons et les valeurs obtenus lors des flux d'autorisation OpenID, en sélectionnant Afficher les options avancées et en sélectionnant :
- Utiliser des cookies pour la session : (facultatif) indiquez comment stocker les jetons JWT nouvellement générés en tant que chaînes non lisibles par l'homme à la fin d'un flux d'autorisation OpenID Connect :
- Sélectionnez cette option si vous souhaitez stocker le nouveau jeton JWT dans un cookie de session. Pour éviter les attaques CSRF potentielles, lorsque la passerelle d'API stocke le jeton dans un cookie de session, elle renvoie également un jeton CSRF dans un en-tête de réponse X-CSRF-TOKEN. Les demandes suivantes adressées à la passerelle d'API (à l'exception des demandes GET) doivent inclure le jeton CSRF dans un en-tête de demande X-CSRF-TOKEN, en plus du jeton JWT dans le cookie de session inclus automatiquement.
- Ne sélectionnez pas cette option si vous ne voulez pas stocker le nouveau jeton JWT dans un cookie de session. Au lieu de cela, la passerelle d'API renvoie un jeton non lisible par l'homme dans un en-tête de réponse X-APIGW-TOKEN. Les demandes suivantes à la passerelle d'API doivent inclure le même jeton dans un en-tête de demande X-APIGW-TOKEN.
Reportez-vous à Remarques concernant la protection CSRF (Cross-Site Request Forgery)
- Utiliser des cookies pour les étapes intermédiaires : (facultatif) indiquez comment stocker les valeurs des étapes intermédiaires du flux d'autorisation (par exemple, les paramètres de demande). Sélectionnez cette option pour stocker les valeurs dans les cookies du navigateur. Désélectionnez cette option pour stocker les valeurs avec la passerelle d'API.
- Utiliser PKCE : (facultatif) indiquez si PKCE (clé de vérification pour l'échange de code) doit être utilisé pour plus de sécurité. PKCE est une extension de sécurité OAuth 2.0 pour empêcher les attaques CSRF (Cross-Site Request Forgery) et d'injection de code d'autorisation. PKCE ne remplace pas une clé secrète client, et PKCE est recommandé même si une clé secrète client est utilisée. Pour plus d'informations sur PKCE, reportez-vous à la documentation OAuth 2.0.
- Portées : portées d'accès à inclure dans une demande
- Si vous voulez personnaliser la réponse en cas d'échec de la tentative de validation d'un jeton manquant ou non valide, sélectionnez Réponse personnalisée et indiquez un code de statut (et un corps de message facultatif) à renvoyer au client d'API :
- Code de statut HTTP : entrez un autre code de statut HTTP. Par exemple :
500
. - Corps du message : entrez un corps de message. Par exemple,
Unfortunately, authentication failed.
Le corps du message peut inclure n'importe quelle variable de contexte (à l'exception derequest.body
). - Vous pouvez éventuellement modifier les en-têtes de la réponse renvoyée par la passerelle d'API au client d'API en indiquant une stratégie de réponse de transformation d'en-tête. Pour plus d'informations sur les stratégies de transformation d'en-tête, reportez-vous à Ajout de stratégies de réponse de transformation d'en-tête.
- Code de statut HTTP : entrez un autre code de statut HTTP. Par exemple :
- Si vous voulez que la passerelle d'API envoie un code de statut HTTP 401 et l'en-tête
-
Sélectionnez Suivant pour saisir les détails de chaque routage dans le déploiement d'API sur la page Routages.
-
Dans la section Routage 1, spécifiez le premier routage du déploiement d'API qui met en correspondance un chemin et des méthodes avec un service back-end :
-
Chemin : chemin pour les appels d'API utilisant les méthodes répertoriées vers le service back-end. Le chemin d'accès que vous spécifiez doit remplir les conditions suivantes :
- Il est relatif au préfixe de chemin de déploiement.
- Il doit être précédé d'une barre oblique (/). Il peut également consister en une unique barre oblique.
- Il peut contenir plusieurs barres obliques (à condition qu'elles ne soient pas adjacentes), ainsi que se terminer par une barre oblique.
- Il peut inclure des caractères alphanumériques en majuscules et minuscules.
- Il peut inclure les caractères spéciaux
$ - _ . + ! * ' ( ) , % ; : @ & =
. - Il peut inclure des paramètres et des caractères génériques (reportez-vous à Ajout de paramètres de chemin et de caractères génériques aux chemins de routage).
- Méthodes : méthodes acceptées par le service back-end, séparées par des virgules. Par exemple,
GET, PUT
. -
Ajouter un seul back-end : ou Ajouter plusieurs back-ends : indique si toutes les demandes doivent être acheminées vers le même back-end ou si elles doivent l'être vers d'autres back-ends en fonction de la variable de contexte et des règles que vous entrez.
Ces instructions supposent que vous souhaitez utiliser un back-end unique. Sélectionnez donc Ajouter un back-end unique. Si vous souhaitez utiliser des back-ends différents, vous pouvez également sélectionner Ajouter plusieurs back-ends et suivre les instructions fournies dans Utilisation de la console pour ajouter une sélection de back-end dynamique à une spécification de déploiement d'API.
-
Type de back-end : type du service back-end :
- HTTP : pour un back-end HTTP, vous devez également spécifier une URL et des détails d'expiration. Vous devez aussi indiquer si la vérification SSL doit être désactivée (reportez-vous à Ajout d'une URL HTTP ou HTTPS en tant que back-end de passerelle d'API).
- Oracle Functions : pour un back-end OCI Functions, vous devez également indiquer l'application et la fonction (reportez-vous à Ajout d'une fonction dans OCI Functions en tant que back-end de passerelle d'API).
- Réponse par défaut : pour un back-end de réponse par défaut, vous devez également indiquer le code de statut HTTP, le contenu du corps de la réponse et des champs d'en-tête HTTP (reportez-vous à Ajout de réponses par défaut en tant que back-end de passerelle d'API).
- Déconnexion : pour un back-end de déconnexion, vous devez également indiquer la liste des URL autorisées vers lesquelles une demande peut être redirigée pour révoquer des jetons et, éventuellement, les données à transmettre à l'URL de déconnexion (reportez-vous à Ajout de la déconnexion en tant que back-end de passerelle d'API).
-
-
Pour indiquer une stratégie d'autorisation qui s'applique à un routage individuel, sélectionnez Afficher les stratégies de demande de routage, sélectionnez le bouton Ajouter en regard du champ Autorisation et indiquez les éléments suivants :
-
Type d'autorisation : mode d'octroi de l'accès au routage. Indiquez l'une des valeurs suivantes :
- Tous : n'accorde l'accès qu'aux utilisateurs finals qui ont été authentifiés, à condition que le jeton JWT comporte une demande
scope
qui inclut au moins l'une des portées d'accès indiquées dans le champ Portée autorisée. Dans ce cas, l'option Activer l'accès anonyme de la stratégie d'authentification n'a aucun effet. - Anonyme : autorise l'accès à tous les utilisateurs finals, même s'ils n'ont pas été authentifiés à l'aide du jeton JWT. Dans ce cas, vous devez avoir sélectionné l'option Activer l'accès anonyme de la stratégie d'authentification.
- Authentification uniquement : n'accorde l'accès qu'aux utilisateurs finals qui ont été authentifiés à l'aide du jeton JWT. Dans ce cas, l'option Activer l'accès anonyme de la stratégie d'authentification n'a aucun effet.
- Tous : n'accorde l'accès qu'aux utilisateurs finals qui ont été authentifiés, à condition que le jeton JWT comporte une demande
- Portée autorisée : si vous avez sélectionné N'importe lequel comme type d'autorisation, entrez la liste des chaînes, séparées par des virgules qui correspondent aux portées d'accès contenues dans le jeton JWT. L'accès ne sera octroyé qu'aux utilisateurs finals qui ont été authentifiés si le jeton JWT comporte une demande
scope
qui inclut l'une des portées d'accès que vous indiquez. Par exemple,read:hello
Remarque
Si vous n'incluez pas de stratégie d'autorisation pour un routage particulier, l'accès est accordé comme si une stratégie existait et que Type d'autorisation était défini sur Authentification uniquement. En d'autres termes, quel que soit le paramétrage de l'option Activer l'accès anonyme de la stratégie d'authentification, les conditions suivantes sont vraies :
- Seuls les utilisateurs finals authentifiés peuvent accéder au routage.
- Tous les utilisateurs finals authentifiés peuvent accéder au routage indépendamment des portées d'accès comprises dans la demande
scope
du jeton JWT. - Les utilisateurs finals anonymes ne peuvent pas accéder au routage.
-
- Sélectionnez Appliquer les modifications, puis Suivant afin de vérifier les détails saisis 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 en l'appelant (reportez-vous à Appel d'une API déployée sur une passerelle d'API).
Modification d'un fichier JSON pour ajouter des stratégies de demande d'autorisation et d'authentification par jeton
Pour ajouter des stratégies de demande d'authentification et d'autorisation à une spécification de déploiement d'API dans un fichier JSON, procédez comme suit :
-
A l'aide de l'éditeur JSON de votre choix, modifiez la spécification de déploiement d'API existante à laquelle vous voulez ajouter la fonctionnalité d'authentification et d'autorisation ou créez une spécification de déploiement d'API (reportez-vous à Création d'une spécification de déploiement d'API).
Au minimum, la spécification de déploiement d'API doit inclure une section
routes
contenant les éléments suivants :- Un chemin. Par exemple,
/hello
. - Des méthodes. Par exemple,
GET
. - La définition d'un back-end. Par exemple, une URL ou l'OCID d'une fonction dans OCI Functions.
Par exemple, la spécification de déploiement d'API de base suivante définit une fonction simple sans serveur Hello World dans OCI Functions en tant que back-end unique :
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
- Un chemin. Par exemple,
-
Insérez une section
requestPolicies
avant la sectionroutes
(si elle n'existe pas déjà) pour créer une stratégie de demandeauthentication
qui s'applique à tous les routages de la spécification de déploiement d'API. Par exemple :{ "requestPolicies": {}, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
-
Ajoutez la stratégie de demande
authentication
comme suit :{ "requestPolicies": { "authentication": { "type": "TOKEN_AUTHENTICATION", <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">, "tokenAuthScheme": "<authentication-scheme>", "isAnonymousAccessAllowed": <true|false>, "maxClockSkewInSeconds": <seconds-difference>, "validationPolicy": {<validation-policy-config>}, } "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
où :
"authentication": {"type": "TOKEN_AUTHENTICATION"...
indique que vous voulez utiliser des jetons pour l'authentification.<"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">
indique s'il s'agit d'un en-tête de demande contenant le jeton (et, le cas échéant, le nom de l'en-tête) ou d'un paramètre de requête contenant le jeton (et, le cas échéant, le nom du paramètre de requête). Vous pouvez spécifier"tokenHeader": "<token-header-name>"
ou"tokenQueryParam": "<token-query-param-name>">
, mais pas les deux. Par exemple,"tokenHeader": "Authorization"
<tokenAuthScheme>
est le nom du modèle d'authentification à utiliser si le jeton est contenu dans un en-tête de demande. Par exemple,"Bearer"
."isAnonymousAccessAllowed": <true|false>
indique éventuellement si les utilisateurs finals non authentifiés (c'est-à-dire anonymes) peuvent accéder aux routages dans la spécification de déploiement d'API. Si vous voulez que les utilisateurs finals anonymes ne puissent jamais accéder aux routages, définissez cette propriété surfalse
. Si vous n'incluez pas cette propriété dans la stratégieauthentication
, la valeur par défautfalse
est utilisée. Si vous incluez cette propriété et que vous la définissez surtrue
, vous devez également indiquer explicitement les routages auxquels l'accès anonyme est autorisé en définissant la propriététype
sur"ANONYMOUS"
dans la stratégieauthorization
de chaque routage.maxClockSkewInSeconds: <seconds-difference>
indique éventuellement l'écart maximal entre les horloges système du fournisseur d'identités qui a émis le jeton JWT et la passerelle d'API. La valeur indiquée est prise en compte lorsque la passerelle d'API valide le JWT afin de déterminer sa validité à l'aide de la demande de début de validité (nbf
), si elle est présente, et de la demande d'expiration (exp
) du JWT. La valeur minimale par défaut est0
et la valeur maximale est120
."validationPolicy": {<validation-policy-config>}
indique une stratégie de validation pour valider les jetons, comme décrit dans les étapes suivantes.
- Si vous voulez que la passerelle d'API valide à la fois les jetons JWT et les jetons non JWT avec une adresse d'introspection de serveur d'autorisation OAuth 2.0 à l'aide d'informations d'identification client (y compris une clé secrète client extraite d'un coffre dans le service Vault), ajoutez la stratégie de validation suivante à la section
validationPolicy
vide :"validationPolicy": { "type": "REMOTE_DISCOVERY", "clientDetails": { "type": "CUSTOM", "clientId": "<client-id>", "clientSecretId": "<secret-ocid>", "clientSecretVersionNumber": <secret-version-number> }, "sourceUriDetails": { "type": "DISCOVERY_URI", "uri": "<well-known-uri>" }, "isSslVerifyDisabled": <true|false>, "maxCacheDurationInHours": <cache-time>, "additionalValidationPolicy": { "issuers": ["<issuer-url>", "<issuer-url>"], "audiences": ["<intended-audience>"], "verifyClaims": [{ "key": "<claim-name>", "values": ["<acceptable-value>", "<acceptable-value>"], "isRequired": <true|false> }] } }
où :
"validationPolicy": {"type": "REMOTE_DISCOVERY"...}
indique que vous voulez valider les jetons avec l'adresse d'introspection d'un serveur d'autorisation OAuth 2.0 à l'aide des informations d'identification client (y compris une clé secrète client extraite d'un coffre dans le service Vault).clientDetails": {"type": "CUSTOM"...}
indique les détails de la clé secrète client à extraire d'un coffre dans le service Vault :"clientId": "<client-id>"
indique l'ID client à envoyer à l'adresse d'introspection. Pour obtenir un ID client, créez et enregistrez une application client auprès du serveur d'autorisation. Par exemple,5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1
. Reportez-vous à Prérequis pour l'authentification par jeton."clientSecretId": "<secret-ocid>"
indique l'OCID de la clé secrète de coffre contenant la clé secrète client à envoyer à l'adresse d'introspection. Par exemple,ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3q
"clientSecretVersionNumber": <secret-version-number>
indique la version de la clé secrète de coffre contenant la clé secrète client à envoyer à l'adresse d'introspection. Par exemple,1
"uri": "<well-known-uri>"
indique l'URL connue d'un serveur d'autorisation à partir duquel la passerelle d'API doit obtenir des adresses de métadonnées d'autorisation. Par exemple,https://my-idp/oauth2/default/.well-known/openid-configuration
. L'URL doit pouvoir être acheminée à partir du sous-réseau contenant la passerelle d'API sur laquelle l'API est déployée."isSslVerifyDisabled": <true|false>
indique si la vérification SSL doit être désactivée lors de la communication avec le serveur d'autorisation. Oracle vous recommande de ne pas définir cette option surtrue
car elle peut compromettre la validation du jeton JWT. API Gateway accepte les certificats de plusieurs autorités de certification émis pour OCI IAM avec des domaines d'identité, Oracle Identity Cloud Service (IDCS), Auth0 et Okta."maxCacheDurationInHours": <cache-time>
indique le nombre d'heures (entre 1 et 24) pendant lesquelles la passerelle d'API doit mettre en cache la réponse à partir de l'adresse d'introspection."additionalValidationPolicy": {"issuers": ...}
indique des détails supplémentaires pour la validation de jeton :<issuer-url>
correspond à l'URL (ou la chaîne de texte) d'un serveur d'autorisation autorisé dans la demande d'émetteur (iss
) d'un jeton JWT utilisé pour accéder au déploiement d'API. Par exemple, pour permettre à un jeton JWT émis par OCI IAM avec des domaines d'identité d'être utilisé pour accéder au déploiement d'API, indiquezhttps://identity.oraclecloud.com/
. Vous pouvez spécifier plusieurs serveurs d'autorisation (dans la limite de cinq). Reportez-vous à Détails de fournisseur d'identités à utiliser pour les demandes iss et aud, ainsi que pour l'URI de l'ensemble de clés Web JSON (JWKS).<intended-audience>
est une valeur autorisée dans la demande de public (aud
) d'un jeton JWT afin d'identifier le destinataire prévu du jeton. Par exemple, le public peut correspondre, entre autres, au nom d'hôte de la passerelle d'API. Vous pouvez spécifier plusieurs publics (dans la limite de cinq). Reportez-vous à Détails de fournisseur d'identités à utiliser pour les demandes iss et aud, ainsi que pour l'URI de l'ensemble de clés Web JSON (JWKS)."verifyClaims": {...}
indique éventuellement les noms et les valeurs de demandes supplémentaires à valider dans un jeton JWT (dans la limite de dix) :"key": "<claim-name>"
est le nom d'une demande pouvant ou devant être incluse dans un jeton JWT. Le nom de demande que vous indiquez peut être un nom de demande réservée, comme la demande de sujet (sub
), ou un nom de demande personnalisée émise par un serveur d'autorisation particulier."values": ["<acceptable-value>", "<acceptable-value>"]
(facultatif) indique des valeurs acceptables pour la demande."isRequired": <true|false>
indique si la demande doit être incluse dans le jeton JWT.
Les noms et les valeurs de clé que vous saisissez sont simplement traités comme des chaînes et doivent correspondre exactement aux noms et aux valeurs du jeton JWT. La correspondance de motifs et les autres types de données ne sont pas pris en charge.
Par exemple, la stratégie
authentication
suivante configure la passerelle d'API pour valider un jeton dans l'en-tête de demande d'autorisation à l'aide des informations d'identification client (y compris une clé secrète client extraite d'un coffre dans le service Vault) transmises à une adresse d'introspection OAuth 2.0) :{ "requestPolicies": { "authentication": { "type": "TOKEN_AUTHENTICATION", "tokenHeader": "Authorization", "tokenAuthScheme": "Bearer", "isAnonymousAccessAllowed": false, "maxClockSkewInSeconds": 10, "validationPolicy": { "type": "REMOTE_DISCOVERY", "clientDetails": { "type": "CUSTOM", "clientId": "5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1", "clientSecretId": "ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3q", "clientSecretVersionNumber": 1 }, "sourceUriDetails": { "type": "DISCOVERY_URI", "uri": "https://my-idp/oauth2/default/.well-known/openid-configuration" }, "isSslVerifyDisabled": false, "maxCacheDurationInHours": 2, "additionalValidationPolicy": { "issuers": ["https://identity.oraclecloud.com/"], "audiences": ["api.dev.io"], "verifyClaims": [{ "key": "is_admin", "values": ["service:app", "read:hello"], "isRequired": true }] } } } }, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
-
Pour que la passerelle d'API valide les jetons JWT en extrayant les clés de vérification publiques du fournisseur d'identités lors de l'exécution, ajoutez la stratégie de validation suivante à la section
validationPolicy
vide :"validationPolicy": { "type": "REMOTE_JWKS", "uri": "<uri-for-jwks>", "isSslVerifyDisabled": <true|false>, "maxCacheDurationInHours": <cache-time>, "additionalValidationPolicy": { "issuers": ["<issuer-url>", "<issuer-url>"], "audiences": ["<intended-audience>"], "verifyClaims": [{ "key": "<claim-name>", "values": ["<acceptable-value>", "<acceptable-value>"], "isRequired": <true|false> }] } }
où :
"validationPolicy": {"type": "REMOTE_JWKS"...
indique que vous voulez configurer la passerelle d'API de façon à extraire jusqu'à dix clés de vérification publiques du fournisseur d'identités lors de l'exécution."uri": "<uri-for-jwks>"
indique l'URI à partir duquel extraire l'ensemble de clés Web JSON (JWKS) à utiliser pour vérifier la signature sur les jetons JWT. Pour plus d'informations sur l'URI à indiquer, reportez-vous à Détails de fournisseur d'identités à utiliser pour les demandes iss et aud, ainsi que pour l'URI de l'ensemble de clés Web JSON (JWKS). Tenez compte des points suivants :- L'URI doit pouvoir être acheminé à partir du sous-réseau contenant la passerelle d'API sur laquelle l'API est déployée.
- Si la passerelle d'API ne parvient pas à extraire l'ensemble JWKS, toutes les demandes de déploiement d'API renvoient un code de réponse HTTP 500. Pour plus d'informations sur cette erreur, consultez le journal d'exécution de la passerelle d'API (reportez-vous à Ajout de la journalisation aux déploiements d'API).
- L'ensemble JWKS doit contenir certains paramètres de clé pour vérifier la signature du jeton JWT (reportez-vous à Paramètres de clé requis pour vérifier les signatures de jeton JWT).
- Le JWKS peut contenir jusqu'à dix clés.
"isSslVerifyDisabled": <true|false>
indique si la vérification SSL doit être désactivée lors de la communication avec le fournisseur d'identités. Oracle vous recommande de ne pas définir cette option surtrue
car elle peut compromettre la validation du jeton JWT. API Gateway accepte les certificats de plusieurs autorités de certification émis pour OCI IAM avec des domaines d'identité, Oracle Identity Cloud Service (IDCS), Auth0 et Okta."maxCacheDurationInHours": <cache-time>
indique le nombre d'heures (compris entre 1 et 24) pendant lesquelles la passerelle d'API doit mettre en cache le service JWKS après son extraction."additionalValidationPolicy": {"issuers": ...}
indique des détails supplémentaires pour la validation de jeton :<issuer-url>
correspond à l'URL (ou la chaîne de texte) d'un fournisseur d'identités autorisé dans la demande d'émetteur (iss
) d'un jeton JWT utilisé pour accéder au déploiement d'API. Par exemple, pour permettre l'utilisation d'un jeton JWT émis par OCI IAM avec des domaines d'identité afin d'accéder au déploiement d'API, entrezhttps://identity.oraclecloud.com/
. Vous pouvez indiquer plusieurs fournisseurs d'identités (dans la limite de cinq). Reportez-vous à Détails de fournisseur d'identités à utiliser pour les demandes iss et aud, ainsi que pour l'URI de l'ensemble de clés Web JSON (JWKS).<intended-audience>
est une valeur autorisée dans la demande de public (aud
) d'un jeton JWT afin d'identifier le destinataire prévu du jeton. Par exemple, le public peut correspondre, entre autres, au nom d'hôte de la passerelle d'API. Vous pouvez spécifier plusieurs publics (dans la limite de cinq). Reportez-vous à Détails de fournisseur d'identités à utiliser pour les demandes iss et aud, ainsi que pour l'URI de l'ensemble de clés Web JSON (JWKS).verifyClaims
indique éventuellement les noms et les valeurs de demandes supplémentaires à valider dans un jeton JWT (dans la limite de dix)."key": "<claim-name>"
est le nom d'une demande pouvant ou devant être incluse dans un jeton JWT. Le nom de demande que vous indiquez peut être un nom de demande réservée, comme la demande de sujet (sub
), ou un nom de demande personnalisée émise par un fournisseur d'identités précis."values": ["<acceptable-value>", "<acceptable-value>"]
(facultatif) indique des valeurs acceptables pour la demande."isRequired": <true|false>
indique si la demande doit être incluse dans le jeton JWT.
Les noms et les valeurs de clé que vous saisissez sont simplement traités comme des chaînes et doivent correspondre exactement aux noms et aux valeurs du jeton JWT. La correspondance de motifs et les autres types de données ne sont pas pris en charge.
Par exemple, la stratégie
authentication
suivante configure la passerelle d'API pour valider le jeton JWT dans l'en-tête de demande d'autorisation en extrayant les clés de vérification publiques du fournisseur d'identités lors de l'exécution :{ "requestPolicies": { "authentication": { "type": "TOKEN_AUTHENTICATION", "tokenHeader": "Authorization", "tokenAuthScheme": "Bearer", "isAnonymousAccessAllowed": false, "validationPolicy": { "type": "REMOTE_JWKS", "uri": "https://my-tenant-id.identity.oraclecloud.com/admin/v1/SigningCert/jwk", "isSslVerifyDisabled": false, "maxCacheDurationInHours": 2, "additionalValidationPolicy": { "issuers": ["https://identity.oraclecloud.com/"], "audiences": ["api.dev.io"], "verifyClaims": [{ "key": "is_admin", "values": ["service:app", "read:hello"], "isRequired": true }] } } } }, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
-
Si vous voulez que la passerelle d'API valide les JWT à l'aide de clés de vérification publiques déjà émises par un fournisseur d'identités (ce qui permet à la passerelle d'API de vérifier les JWT localement sans avoir à contacter le fournisseur d'identités), ajoutez la stratégie de validation suivante à la section
validationPolicy
vide :"validationPolicy": { "type": "STATIC_KEYS", "keys": [{<key-config>}], "isSslVerifyDisabled": <true|false>, "maxCacheDurationInHours": <cache-time>, "additionalValidationPolicy": { "issuers": ["<issuer-url>", "<issuer-url>"], "audiences": ["<intended-audience>"], "verifyClaims": [{ "key": "<claim-name>", "values": ["<acceptable-value>", "<acceptable-value>"], "isRequired": <true|false> }] } }
où :
"validationPolicy": {"type": "STATIC_KEYS"...
indique que vous voulez configurer la passerelle d'API avec jusqu'à dix clés de vérification publiques déjà émises par un fournisseur d'identités (ce qui permet à la passerelle d'API de vérifier les JWT localement sans avoir à contacter le fournisseur d'identités)."keys": [{<key-config>}]
indique l'identificateur de la clé statique utilisée pour signer le jeton JWT. Les détails à fournir dépendent du format de la clé déjà émise par le fournisseur d'identités (quel que soit le format, vous pouvez indiquer jusqu'à dix clés) :-
Si la clé statique est une clé Web JSON, indiquez
"format": "JSON_WEB_KEY"
, renseignez l'identificateur de la clé statique utilisée pour signer le jeton JWT en tant que valeur du paramètre"kid"
, puis saisissez les valeurs des autres paramètres afin de vérifier la signature du jeton JWT.Par exemple :
"keys": [ { "format": "JSON_WEB_KEY", "kid": "master_key", "kty": "RSA", "n": "0vx7agoebGc...KnqDKgw", "e": "AQAB", "alg": "RS256", "use": "sig" } ]
La clé statique doit contenir certains paramètres pour vérifier la signature du jeton JWT (reportez-vous à Paramètres de clé requis pour vérifier les signatures de jeton JWT). Le seul type de clé (
kty
) actuellement pris en charge estRSA
. -
Si la clé statique est une clé publique encodée au format PEM, indiquez
"format": "PEM"
, renseignez l'identificateur de la clé statique utilisée pour signer le jeton JWT en tant que valeur du paramètre"kid"
, puis indiquez la clé en tant que valeur du paramètre"key"
.Par exemple :
"keys": [ { "format": "PEM", "kid": "master_key" "key": -----BEGIN PUBLIC KEY-----XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO2mxwlL5/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7plfZVPX7XORvezwqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG6tzobwig8M2KIrPjJ0BmbJAFH-----END PUBLIC KEY----- } ]
Les marqueurs
-----BEGIN PUBLIC KEY-----
et-----END PUBLIC KEY-----
sont requis.
-
"isSslVerifyDisabled": <true|false>
indique si la vérification SSL doit être désactivée lors de la communication avec le fournisseur d'identités. Oracle vous recommande de ne pas définir cette option surtrue
car elle peut compromettre la validation du jeton JWT. API Gateway accepte les certificats de plusieurs autorités de certification émis pour OCI IAM avec des domaines d'identité, Oracle Identity Cloud Service (IDCS), Auth0 et Okta."maxCacheDurationInHours": <cache-time>
indique le nombre d'heures (compris entre 1 et 24) pendant lesquelles la passerelle d'API doit mettre en cache le service JWKS après son extraction."additionalValidationPolicy": {"issuers": ...}
indique des détails supplémentaires pour la validation de jeton :<issuer-url>
correspond à l'URL (ou la chaîne de texte) d'un fournisseur d'identités autorisé dans la demande d'émetteur (iss
) d'un jeton JWT utilisé pour accéder au déploiement d'API. Par exemple, pour permettre l'utilisation d'un jeton JWT émis par OCI IAM avec des domaines d'identité afin d'accéder au déploiement d'API, entrezhttps://identity.oraclecloud.com/
. Vous pouvez indiquer plusieurs fournisseurs d'identités (dans la limite de cinq). Reportez-vous à Détails de fournisseur d'identités à utiliser pour les demandes iss et aud, ainsi que pour l'URI de l'ensemble de clés Web JSON (JWKS).<intended-audience>
est une valeur autorisée dans la demande de public (aud
) d'un jeton JWT afin d'identifier le destinataire prévu du jeton. Par exemple, le public peut correspondre, entre autres, au nom d'hôte de la passerelle d'API. Vous pouvez spécifier plusieurs publics (dans la limite de cinq). Reportez-vous à Détails de fournisseur d'identités à utiliser pour les demandes iss et aud, ainsi que pour l'URI de l'ensemble de clés Web JSON (JWKS).verifyClaims
indique éventuellement les noms et les valeurs de demandes supplémentaires à valider dans un jeton JWT (dans la limite de dix)."key": "<claim-name>"
est le nom d'une demande pouvant ou devant être incluse dans un jeton JWT. Le nom de demande que vous indiquez peut être un nom de demande réservée, comme la demande de sujet (sub
), ou un nom de demande personnalisée émise par un fournisseur d'identités précis."values": ["<acceptable-value>", "<acceptable-value>"]
(facultatif) indique des valeurs acceptables pour la demande."isRequired": <true|false>
indique si la demande doit être incluse dans le jeton JWT.
Les noms et les valeurs de clé que vous saisissez sont simplement traités comme des chaînes et doivent correspondre exactement aux noms et aux valeurs du jeton JWT. La correspondance de motifs et les autres types de données ne sont pas pris en charge.
Par exemple, la stratégie
authentication
suivante configure la passerelle d'API avec une clé de vérification publique déjà émise par un fournisseur d'identités afin de valider le jeton JWT dans l'en-tête de demande d'autorisation :{ "requestPolicies": { "authentication": { "type": "TOKEN_AUTHENTICATION", "tokenHeader": "Authorization", "tokenAuthScheme": "Bearer", "isAnonymousAccessAllowed": false, "validationPolicy": { "type": "STATIC_KEYS", "keys": [ { "format": "JSON_WEB_KEY", "kid": "master_key", "kty": "RSA", "n": "0vx7agoebGc...KnqDKgw", "e": "AQAB", "alg": "RS256", "use": "sig" } ], "isSslVerifyDisabled": false, "maxCacheDurationInHours": 2, "additionalValidationPolicy": { "issuers": ["https://identity.oraclecloud.com/"], "audiences": ["api.dev.io"], "verifyClaims": [{ "key": "is_admin", "values": ["service:app", "read:hello"], "isRequired": true }] } } } }, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
- (Facultatif) Vous pouvez indiquer comment la passerelle d'API doit gérer une réponse d'authentification en échec (renvoyée après une tentative infructueuse de validation d'un jeton manquant ou non valide) en configurant une stratégie d'échec de validation :
- Si vous voulez que la passerelle d'API envoie un code de statut HTTP 401 et l'en-tête
WWW-Authenticate
dans la réponse (réponse par défaut à un jeton manquant ou non valide), ne définissez pas de stratégie d'échec de validation. -
Si vous voulez que la passerelle d'API utilise un flux d'autorisation OpenID Connect pour obtenir un nouveau jeton d'accès JWT, définissez une stratégie d'échec de validation de type
OAUTH2
. Cette option n'est disponible que si vous avez indiqué un élémentvalidationPolicy
de typeREMOTE_DISCOVERY
précédemment. Indiquez l'une des valeurs suivantes :{ "requestPolicies": { "authentication": { "type": "TOKEN_AUTHENTICATION", ... "validationPolicy": { "type": "REMOTE_DISCOVERY", ... }, "validationFailurePolicy": { "type": "OAUTH2", "scopes": ["<scope>", "<scope"], "clientDetails": { "type": "<VALIDATION_BLOCK|CUSTOM>", "clientId": "<client-id>", "clientSecretId": "<secret-ocid>", "clientSecretVersionNumber": <secret-version-number> }, "sourceUriDetails": { "type": "VALIDATION_BLOCK" }, "maxExpiryDurationInHours": <number-of-hours>, "useCookiesForSession": <true|false>, "useCookiesForIntermediateSteps": <true|false>, "usePkce": <true|false>, "responseType": "code", "fallbackRedirectPath": "<redirect-path>", "logoutPath": "<logout-path>" } } }, "routes": [ ... ] }
où :
"scopes": ["<scope>", "<scope"]
indique des portées d'accès à inclure dans une demandescope
envoyée au serveur d'autorisation. Pour utiliser le flux d'autorisation OpenID Connect, vous devez inclureopenid
comme l'une des portées. Par exemple,"scopes": ["openid", "email:read", "profile"]
clientDetails": {...}
indique les détails du client à utiliser pour obtenir un nouveau jeton d'accès JWT à partir du serveur d'autorisation, comme suit :"type": "<VALIDATION_BLOCK|CUSTOM>"
indique si les détails du client doivent être identiques ou différents de ceux indiqués dans la versionvalidationPolicy
précédente. Si vous voulez utiliser les mêmes détails client qu'auparavant (ce qui est généralement le cas), indiquez"type": "VALIDATION_BLOCK"
et ne fournissez pas de détails supplémentaires. Si vous voulez utiliser des détails de client différents, indiquez"type": "CUSTOM"
et définissez des valeurs pour"clientId"
,"clientSecretId"
et"clientSecretVersionNumber"
."clientId": "<client-id>"
indique l'ID client à envoyer à l'adresse d'introspection. Utilisé uniquement si"type": "CUSTOM"
. Par exemple,5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1
"clientSecretId": "<secret-ocid>"
indique l'OCID de la clé secrète de coffre contenant la clé secrète client à envoyer à l'adresse d'introspection. Utilisé uniquement si"type": "CUSTOM"
. Par exemple,ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3q
"clientSecretVersionNumber": <secret-version-number>
indique la version de la clé secrète de coffre contenant la clé secrète client à envoyer à l'adresse d'introspection. Utilisé uniquement si"type": "CUSTOM"
. Par exemple,1
"sourceUriDetails": {"type": "VALIDATION_BLOCK"}
indique que vous voulez utiliser la même URL que celle indiquée dans la versionvalidationPolicy
précédente, ainsi que l'URL connue d'un serveur d'autorisation à partir duquel la passerelle d'API doit obtenir des adresses de métadonnées d'autorisation."maxExpiryDurationInHours": <number-of-hours>
indique la durée de mise en cache du jeton JWT généré par le flux d'autorisation. Valeur par défaut : 1."useCookiesForSession": <true|false>
indique comment stocker les jetons JWT nouvellement générés en tant que chaînes non lisibles par l'utilisateur à la fin d'un flux d'autorisation OpenID Connect :- Définissez cette option sur
true
si vous voulez stocker le nouveau jeton JWT dans un cookie de session. Pour éviter les attaques CSRF potentielles, lorsque la passerelle d'API stocke le jeton dans un cookie de session, elle renvoie également un jeton CSRF dans un en-tête de réponse X-CSRF-TOKEN. Les demandes suivantes (à l'exception des demandes GET) doivent inclure le jeton CSRF dans un en-tête de demande X-CSRF-TOKEN, en plus du jeton JWT dans le cookie de session inclus automatiquement. - Définissez cette option sur
false
si vous ne voulez pas stocker le nouveau jeton JWT dans un cookie de session. Au lieu de cela, la passerelle d'API renvoie un jeton non lisible par l'homme dans un en-tête de réponse X-APIGW-TOKEN. Les demandes suivantes à la passerelle d'API doivent inclure le même jeton dans un en-tête de demande X-APIGW-TOKEN.
Reportez-vous à Remarques concernant la protection CSRF (Cross-Site Request Forgery)
- Définissez cette option sur
"useCookiesForIntermediateSteps": <true|false>
indique comment stocker les valeurs d'étape intermédiaire de flux d'autorisation (par exemple, les paramètres de demande). Définissez cette option surtrue
pour stocker les valeurs dans les cookies du navigateur. Définissez cette option surfalse
pour stocker les valeurs avec la passerelle d'API."usePkce": <true|false>
indique s'il faut utiliser PKCE (clé de vérification pour l'échange de code) pour plus de sécurité. PKCE est une extension de sécurité OAuth 2.0 pour empêcher les attaques CSRF (Cross-Site Request Forgery) et d'injection de code d'autorisation. PKCE ne remplace pas une clé secrète client, et PKCE est recommandé même si une clé secrète client est utilisée. Pour plus d'informations sur PKCE, reportez-vous à la documentation OAuth 2.0."responseType": "code"
indique le type de réponse requis par le flux d'autorisation. Indiquezcode
comme type de réponse."fallbackRedirectPath": "/home"
indique éventuellement un chemin relatif dans le déploiement d'API en cours vers lequel rediriger les clients d'API si la demande d'origine était une demande PUT ou POST. Par exemple,/home
.Si la demande d'origine était une demande GET, le traitement de la demande reprend avec un nouveau jeton d'accès JWT, de sorte qu'aucun chemin de restauration n'est utilisé.
"logoutPath": "<revoke-path>"
indique éventuellement un chemin relatif vers un back-end de déconnexion dans le déploiement d'API en cours. Le chemin que vous indiquez doit correspondre au chemin de routage défini pour le back-end de déconnexion. Par exemple,"logoutPath": "/revoke"
.Un client API peut appeler le back-end de déconnexion pour révoquer les jetons. Un appel vers le back-end de déconnexion peut inclure une URL après déconnexion en tant que paramètre de requête nommé
postLogoutUrl
. Reportez-vous à Ajout de la déconnexion en tant que back-end de passerelle d'API.
Par exemple :
{ "requestPolicies": { "authentication": { "type": "TOKEN_AUTHENTICATION", ... "validationPolicy": { "type": "REMOTE_DISCOVERY", ... }, "validationFailurePolicy": { "type": "OAUTH2", "scopes": ["openid", "email:read", "profile"], "clientDetails": { "type": "VALIDATION_BLOCK" }, "sourceUriDetails": { "type": "VALIDATION_BLOCK" }, "maxExpiryDurationInHours": 2, "useCookiesForSession": true, "useCookiesForIntermediateSteps": true, "usePkce": true, "responseType": "code", "fallbackRedirectPath": "/home", "logoutPath": "/revoke" } } }, "routes": [ ... ] }
- Pour personnaliser la réponse à une tentative infructueuse de validation d'un jeton manquant ou non valide, définissez une stratégie d'échec de validation de type
MODIFY_RESPONSE
et indiquez un code de statut (et un corps de message facultatif) à renvoyer au client d'API, comme suit :{ "requestPolicies": { "authentication": { "type": "TOKEN_AUTHENTICATION", ... "validationPolicy": { ... }, "validationFailurePolicy": { "type": "MODIFY_RESPONSE", "responseCode": "<alternative-response-code>", "responseMessage": "<custom-message-body>", "responseTransformations": { "headerTransformations": { <valid-header-transformation-response-policy> } } } } }, "routes": [ ... ] }
où :
responseCode
: indique un autre code de statut HTTP. Par exemple,500
.responseMessage
: (facultatif) indique un corps de message. Par exemple,Unfortunately, authentication failed.
Le corps du message peut inclure n'importe quelle variable de contexte (à l'exception derequest.body
).responseTransformations
: (facultatif) modifie les en-têtes de la réponse que la passerelle d'API renvoie au client d'API en indiquant une stratégie de réponse de transformation d'en-tête. Pour plus d'informations sur les stratégies de transformation d'en-tête, reportez-vous à Ajout de stratégies de réponse de transformation d'en-tête.
Par exemple :
{ "requestPolicies": { "authentication": { "type": "TOKEN_AUTHENTICATION", ... "validationPolicy": { ... }, "validationFailurePolicy": { "type": "MODIFY_RESPONSE", "responseCode": "500", "responseMessage": "Unfortunately, authentication failed.", } } }, "routes": [ ... ] }
- Si vous voulez que la passerelle d'API envoie un code de statut HTTP 401 et l'en-tête
-
Ajoutez une stratégie de demande
authorization
à chaque routage dans la spécification de déploiement d'API :-
Insérez une section
requestPolicies
après la sectionbackend
du premier routage, s'il n'en existe pas déjà une. Par exemple :{ "requestPolicies": { "authentication": { "type": "TOKEN_AUTHENTICATION", "tokenHeader": "Authorization", "tokenAuthScheme": "Bearer", "isAnonymousAccessAllowed": false, "validationPolicy": { "type": "STATIC_KEYS", "keys": [ { "format": "JSON_WEB_KEY", "kid": "master_key", "kty": "RSA", "n": "0vx7agoebGc...KnqDKgw", "e": "AQAB", "alg": "RS256", "use": "sig" } ], "isSslVerifyDisabled": false, "maxCacheDurationInHours": 2, "additionalValidationPolicy": { "issuers": ["https://identity.oraclecloud.com/"], "audiences": ["api.dev.io"], "verifyClaims": [{ "key": "is_admin", "values": ["service:app", "read:hello"], "isRequired": true }] } } } }, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": {} } ] }
-
Ajoutez la stratégie
authorization
suivante à la nouvelle sectionrequestPolicies
:"requestPolicies": { "authorization": { "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">, "allowedScope": [ "<scope>" ] } }
où :
-
"type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">
indique comment accorder l'accès au routage :"AUTHENTICATION_ONLY"
: n'accorde l'accès qu'aux utilisateurs finals qui ont été authentifiés. Dans ce cas, la propriété"isAnonymousAccessAllowed"
dans la stratégieauthentication
de la spécification de déploiement d'API n'a aucun effet."ANY_OF"
: n'accorde l'accès qu'aux utilisateurs finals qui ont été authentifiés, à condition que la demandescope
du jeton JWT comporte l'une des portées d'accès que vous avez indiquées dans la propriétéallowedScope
. Dans ce cas, la propriété"isAnonymousAccessAllowed"
dans la stratégieauthentication
de la spécification de déploiement d'API n'a aucun effet."ANONYMOUS"
: accorde l'accès à tous les utilisateurs finals, même s'ils n'ont pas été authentifiés. Dans ce cas, vous devez définir explicitement la propriété"isAnonymousAccessAllowed"
surtrue
dans la stratégieauthentication
de la spécification de déploiement d'API.
-
"allowedScope": [ "<scope>" ]
est une liste de chaînes séparées par des virgules correspondant aux portées d'accès contenues dans la demandescope
du jeton JWT. Dans ce cas, vous devez définir la propriététype
sur"ANY_OF"
(la propriété"allowedScope"
est ignorée si la propriététype
est définie sur"AUTHENTICATION_ONLY"
ou"ANONYMOUS"
). Si vous indiquez plusieurs portées, l'accès au routage est accordé si l'une des portées que vous indiquez est comprise dans la demandescope
du jeton JWT.
Par exemple, la stratégie de demande suivante définit un routage
/hello
auquel seuls les utilisateurs finals authentifiés avec la portéeread:hello
peuvent accéder :{ "requestPolicies": { "authentication": { "type": "TOKEN_AUTHENTICATION", "tokenHeader": "Authorization", "tokenAuthScheme": "Bearer", "isAnonymousAccessAllowed": false, "validationPolicy": { "type": "STATIC_KEYS", "keys": [ { "format": "JSON_WEB_KEY", "kid": "master_key", "kty": "RSA", "n": "0vx7agoebGc...KnqDKgw", "e": "AQAB", "alg": "RS256", "use": "sig" } ], "isSslVerifyDisabled": false, "maxCacheDurationInHours": 2, "additionalValidationPolicy": { "issuers": ["https://identity.oraclecloud.com/"], "audiences": ["api.dev.io"], "verifyClaims": [{ "key": "is_admin", "values": ["service:app", "read:hello"], "isRequired": true }] } } } }, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "authorization": { "type": "ANY_OF", "allowedScope": [ "read:hello" ] } } } ] }
-
- Ajoutez une stratégie de demande
authorization
pour tous les routages restants dans la spécification de déploiement d'API.
Remarque
Si vous n'incluez pas de stratégie
authorization
pour un routage particulier, l'accès est accordé comme si une stratégie existait et que la propriététype
était définie sur"AUTHENTICATION_ONLY"
. En d'autres termes, quel que soit le paramètre de la propriétéisAnonymousAccessAllowed
dans la stratégieauthentication
de la spécification de déploiement d'API, les conditions suivantes sont vraies :- Seuls les utilisateurs finals authentifiés peuvent accéder au routage.
- Tous les utilisateurs finals authentifiés peuvent accéder au routage indépendamment des portées d'accès comprises dans la demande
scope
du jeton JWT. - Les utilisateurs finals anonymes ne peuvent pas accéder au routage.
-
- Enregistrez le fichier JSON qui contient la spécification de déploiement d'API.
-
Utilisez 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 Télécharger une API existante,
- spécifiant le fichier JSON dans une demande adressée à l'API REST d'API Gateway.
Pour plus d'informations, reportez-vous à 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 en l'appelant (reportez-vous à Appel d'une API déployée sur une passerelle d'API).
Détails de fournisseur d'identités à utiliser pour les demandes iss et aud, ainsi que pour l'URI de l'ensemble de clés Web JSON (JWKS)
Le fournisseur d'identités qui a émis le jeton JWT détermine les valeurs autorisées que vous devez indiquer dans les demandes d'émetteur (iss
) et de public (aud
) du jeton JWT. Il détermine également l'URI à partir duquel extraire l'ensemble de clés Web JSON (JWKS) pour vérifier la signature sur le jeton JWT.
Notez que, quel que soit le fournisseur d'identités, un JWKS peut contenir un maximum de dix clés.
Reportez-vous au tableau suivant afin de savoir ce qu'il convient d'indiquer pour les jetons JWT émis par OCI IAM avec des fournisseurs d'identités Identity Domains, Oracle Identity Cloud Service (IDCS), Okta et Auth0.
Fournisseur d'identités | Demande d'émetteur ( |
Demande de public ( |
Format de l'URI à partir duquel extraire l'ensemble JWKS |
---|---|---|---|
OCI IAM avec des domaines d'identité | https://identity.oraclecloud.com |
Propre au client. Reportez-vous à Gestion des applications dans la documentation OCI IAM avec des domaines d'identité. |
https://<tenant-base-url>/admin/v1/SigningCert/jwk |
IDCS | https://identity.oraclecloud.com/ |
Propre au client. Reportez-vous à Validation des jetons d'accès dans la documentation Oracle Identity Cloud Service. |
https://<tenant-base-url>/admin/v1/SigningCert/jwk Pour obtenir l'ensemble JWKS sans se connecter à Oracle Identity Cloud Service, reportez-vous à Modification des paramètres par défaut dans la documentation Oracle Identity Cloud Service. |
Okta | https://<your-okta-tenant-name>.com |
Propre au client. Public configuré pour le serveur d'autorisation dans la console de développement Okta. Reportez-vous à Validation supplémentaire pour les jetons d'accès dans la documentation Okta. |
https://<your-okta-tenant-name>.com/oauth2/<auth-server-id> /v1/keys Reportez-vous à la documentation Okta. |
Auth0 | https://<your-account-name>.auth0.com/ |
Propre au client. Reportez-vous à Public dans la documentation Auth0. |
https://<your-account-name>.auth0.com/.well-known/jwks.json |
Paramètres de clé requis pour vérifier les signatures de jeton JWT
Pour vérifier la signature d'un jeton JWT, les passerelles d'API requièrent la présence des paramètres de clé suivants dans l'ensemble JWKS renvoyé à partir d'un URI ou dans la clé Web JSON statique que vous indiquez.
Paramètre de clé | Remarques |
---|---|
kid
|
Identificateur de la clé utilisée pour signer le jeton JWT. La valeur doit correspondre à la demande kid dans l'en-tête du jeton JWT. Par exemple, master_key . |
kty
|
Type de clé utilisé pour signer le jeton JWT. RSA est actuellement le seul type de clé pris en charge. |
use ou key_ops |
Si le paramètre |
n
|
Modulo de la clé publique. |
e
|
Exposant de la clé publique. |
alg
|
L'algorithme de signature (le cas échéant) doit être défini sur RS256, RS384 ou RS512. |
Utilisation d'une stratégie de demande d'authentification JWT_AUTHENTICATION (plus recommandée)
Dans les versions antérieures, vous pouviez avoir créé des stratégies de demande d'authentification de type JWT_AUTHENTICATION pour utiliser des jetons JWT pour l'authentification.
Si vous créez des stratégies de demande d'authentification pour utiliser des jetons JWT, nous vous recommandons maintenant de créer des stratégies de demande d'authentification de type TOKEN_AUTHENTICATION à la place (reportez-vous à Utilisation de la console pour ajouter des stratégies de demande d'autorisation et d'authentification de jeton et à Modification d'un fichier JSON pour ajouter des stratégies de demande d'autorisation et d'authentification de jeton). Nous vous recommandons également de migrer les stratégies de demande JWT_AUTHENTICATION existantes vers les stratégies TOKEN_AUTHENTICATION.
Les stratégies de demande JWT_AUTHENTICATION existantes sont toujours prises en charge. Bien que vous puissiez créer des stratégies de demande JWT_AUTHENTICATION en définissant la spécification de déploiement d'API dans un fichier JSON (comme décrit dans les instructions d'origine de cette section), nous vous recommandons de créer des stratégies de demande d'authentification de type TOKEN_AUTHENTICATION à la place.
Lors de l'utilisation d'une stratégie de demande d'authentification de type JWT_AUTHENTICATION, pour qu'un utilisateur final puisse accéder à un déploiement d'API qui utilise des JWT pour l'authentification et l'autorisation, il doit obtenir un JWT auprès d'un fournisseur d'identités.
Lorsqu'il appelle une API déployée sur une passerelle d'API, l'utilisateur final doit fournir le jeton JWT en tant que paramètre de requête ou dans l'en-tête de la demande. La passerelle d'API valide le jeton JWT à l'aide d'une clé de vérification publique correspondante fournie par le fournisseur d'identités. La stratégie de demande d'authentification JWT_AUTHENTICATION du déploiement d'API vous permet de configurer la façon dont la passerelle d'API valide les jetons JWT :
- Vous pouvez configurer la passerelle d'API de façon à extraire les clés de vérification publiques du fournisseur d'identités lors de l'exécution. Dans ce cas, le fournisseur d'identités fait office de serveur d'autorisation.
- Vous pouvez configurer la passerelle d'API à l'avance avec des clés de vérification publiques déjà émises par un fournisseur d'identités (appelées clés statiques). La passerelle d'API peut ainsi vérifier les JWT localement lors de l'exécution sans avoir à contacter le fournisseur d'identités. Cela permet de valider plus rapidement les jetons.
Pour ajouter une nouvelle stratégie de demande d'authentification et d'autorisation JWT_AUTHENTICATION à une spécification de déploiement d'API dans un fichier JSON, procédez comme suit :
-
Ajoutez une stratégie de demande
authentication
qui s'applique à tous les routages de la spécification de déploiement d'API :-
Insérez une section
requestPolicies
avant la sectionroutes
, si elle n'existe pas déjà. Par exemple :{ "requestPolicies": {}, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
-
Ajoutez la stratégie
authentication
suivante à la nouvelle sectionrequestPolicies
.{ "requestPolicies": { "authentication": { "type": "JWT_AUTHENTICATION", "isAnonymousAccessAllowed": <true|false>, "issuers": ["<issuer-url>", "<issuer-url>"], <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">, "tokenAuthScheme": "<authentication-scheme>", "audiences": ["<intended-audience>"], "publicKeys": { "type": <"REMOTE_JWKS"|"STATIC_KEYS">, <public-key-config> }, "verifyClaims": [ {"key": "<claim-name>", "values": ["<acceptable-value>", "<acceptable-value>"], "isRequired": <true|false> } ], "maxClockSkewInSeconds": <seconds-difference> } }, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
où :
"isAnonymousAccessAllowed": <true|false>
indique éventuellement si les utilisateurs finals non authentifiés (c'est-à-dire anonymes) peuvent accéder aux routages dans la spécification de déploiement d'API. Si vous voulez que les utilisateurs finals anonymes ne puissent jamais accéder aux routages, définissez cette propriété surfalse
. Si vous n'incluez pas cette propriété dans la stratégieauthentication
, la valeur par défautfalse
est utilisée. Si vous incluez cette propriété et que vous la définissez surtrue
, vous devez également indiquer explicitement les routages auxquels l'accès anonyme est autorisé en définissant la propriététype
sur"ANONYMOUS"
dans la stratégieauthorization
de chaque routage.-
<issuer-url>
correspond à l'URL (ou la chaîne de texte) d'un fournisseur d'identités autorisé dans la demande d'émetteur (iss
) d'un jeton JWT utilisé pour accéder au déploiement d'API. Par exemple, pour permettre l'utilisation d'un jeton JWT émis par OCI IAM avec des domaines d'identité afin d'accéder au déploiement d'API, entrezhttps://identity.oraclecloud.com/
. Vous pouvez indiquer plusieurs fournisseurs d'identités (dans la limite de cinq). Reportez-vous à Détails de fournisseur d'identités à utiliser pour les demandes iss et aud, ainsi que pour l'URI de l'ensemble de clés Web JSON (JWKS). <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">
indique s'il s'agit d'un en-tête de demande contenant le JWT (et, le cas échéant, le nom de l'en-tête) ou d'un paramètre de requête contenant le JWT (et, le cas échéant, le nom du paramètre de requête). Vous pouvez spécifier"tokenHeader": "<token-header-name>"
ou"tokenQueryParam": "<token-query-param-name>">
, mais pas les deux.<tokenAuthScheme>
est le nom du modèle d'authentification à utiliser si le jeton JWT est contenu dans un en-tête de demande. Par exemple,"Bearer"
.<intended-audience>
est une valeur autorisée dans la demande de public (aud
) d'un jeton JWT afin d'identifier le destinataire prévu du jeton. Par exemple, le public peut correspondre, entre autres, au nom d'hôte de la passerelle d'API. Vous pouvez spécifier plusieurs publics (dans la limite de cinq). Reportez-vous à Détails de fournisseur d'identités à utiliser pour les demandes iss et aud, ainsi que pour l'URI de l'ensemble de clés Web JSON (JWKS)."type": <"REMOTE_JWKS"|"STATIC_KEYS">
indique comment la passerelle d'API doit valider les jetons JWT à l'aide des clés de vérification publiques. IndiquezREMOTE_JWKS
pour configurer la passerelle d'API de façon à extraire jusqu'à dix clés de vérification publiques du fournisseur d'identités lors de l'exécution. IndiquezSTATIC_KEYS
pour configurer la passerelle d'API avec jusqu'à dix clés de vérification publiques déjà émises par un fournisseur d'identités (ce qui permet à la passerelle d'API de vérifier les jetons JWT localement sans avoir à contacter le fournisseur d'identités).-
<public-key-config>
fournit les détails suivant sur la validation du jeton JWT en fonction de la valeur"type":
que vous avez indiquée ("REMOTE_JWKS"
ou"STATIC_KEYS"
) :-
Si vous avez indiqué
"type": "REMOTE_JWKS"
pour configurer la passerelle d'API de façon à valider les jetons JWT en récupérant les clés de vérification publiques du fournisseur d'identités lors de l'exécution, renseignez les détails suivants :"publicKeys": { "type": "REMOTE_JWKS", "uri": "<uri-for-jwks>", "maxCacheDurationInHours": <cache-time>, "isSslVerifyDisabled": <true|false> }
où :
"uri": "<uri-for-jwks>"
indique l'URI à partir duquel extraire l'ensemble de clés Web JSON (JWKS) à utiliser pour vérifier la signature sur les jetons JWT. Pour plus d'informations sur l'URI à indiquer, reportez-vous à Détails de fournisseur d'identités à utiliser pour les demandes iss et aud, ainsi que pour l'URI de l'ensemble de clés Web JSON (JWKS). Tenez compte des points suivants :- L'URI doit pouvoir être acheminé à partir du sous-réseau contenant la passerelle d'API sur laquelle l'API est déployée.
- Si la passerelle d'API ne parvient pas à extraire l'ensemble JWKS, toutes les demandes de déploiement d'API renvoient un code de réponse HTTP 500. Pour plus d'informations sur cette erreur, consultez le journal d'exécution de la passerelle d'API (reportez-vous à Ajout de la journalisation aux déploiements d'API).
- L'ensemble JWKS doit contenir certains paramètres de clé pour vérifier la signature du jeton JWT (reportez-vous à Paramètres de clé requis pour vérifier les signatures de jeton JWT).
- Le JWKS peut contenir jusqu'à dix clés.
"maxCacheDurationInHours": <cache-time>
indique le nombre d'heures (compris entre 1 et 24) pendant lesquelles la passerelle d'API doit mettre en cache le service JWKS après son extraction."isSslVerifyDisabled": <true|false>
indique si la vérification SSL doit être désactivée lors de la communication avec le fournisseur d'identités. Oracle vous recommande de ne pas définir cette option surtrue
car elle peut compromettre la validation du jeton JWT. API Gateway accepte les certificats de plusieurs autorités de certification émis pour OCI IAM avec des domaines d'identité, Oracle Identity Cloud Service (IDCS), Auth0 et Okta.
Par exemple :
"publicKeys": { "type": "REMOTE_JWKS", "uri": "https://www.somejwksprovider.com/oauth2/v3/certs", "maxCacheDurationInHours": 3, "isSslVerifyDisabled": false }
-
Si vous avez indiqué
"type": "STATIC_KEYS"
, les détails à fournir dépendent du format de la clé déjà émise par le fournisseur d'identités (quel que soit le format, vous pouvez indiquer jusqu'à dix clés) :-
Si la clé statique est une clé Web JSON, indiquez
"format": "JSON_WEB_KEY"
, renseignez l'identificateur de la clé statique utilisée pour signer le jeton JWT en tant que valeur du paramètre"kid"
, puis saisissez les valeurs des autres paramètres afin de vérifier la signature du jeton JWT.Par exemple :
"publicKeys": { "type": "STATIC_KEYS", "keys": [ { "format": "JSON_WEB_KEY", "kid": "master_key", "kty": "RSA", "n": "0vx7agoebGc...KnqDKgw", "e": "AQAB", "alg": "RS256", "use": "sig" } ]
La clé statique doit contenir certains paramètres pour vérifier la signature du jeton JWT (reportez-vous à Paramètres de clé requis pour vérifier les signatures de jeton JWT). Le seul type de clé (
kty
) actuellement pris en charge estRSA
. -
Si la clé statique est une clé publique encodée au format PEM, indiquez
"format": "PEM"
, renseignez l'identificateur de la clé statique utilisée pour signer le jeton JWT en tant que valeur du paramètre"kid"
, puis indiquez la clé en tant que valeur du paramètre"key"
.Par exemple :
"publicKeys": { "type": "STATIC_KEYS", "keys": [ { "format": "PEM", "kid": "master_key" "key": -----BEGIN PUBLIC KEY-----XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO2mxwlL5/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7plfZVPX7XORvezwqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG6tzobwig8M2KIrPjJ0BmbJAFH-----END PUBLIC KEY----- } ]
Les marqueurs
-----BEGIN PUBLIC KEY-----
et-----END PUBLIC KEY-----
sont requis.
-
-
verifyClaims
indique éventuellement les noms et les valeurs de demandes supplémentaires à valider dans un jeton JWT (dans la limite de dix)."key": "<claim-name>"
est le nom d'une demande pouvant ou devant être incluse dans un jeton JWT. Le nom de demande que vous indiquez peut être un nom de demande réservée, comme la demande de sujet (sub
), ou un nom de demande personnalisée émise par un fournisseur d'identités précis."values": ["<acceptable-value>", "<acceptable-value>"]
(facultatif) indique des valeurs acceptables pour la demande."isRequired": <true|false>
indique si la demande doit être incluse dans le jeton JWT.
Les noms et les valeurs de clé que vous saisissez sont simplement traités comme des chaînes et doivent correspondre exactement aux noms et aux valeurs du jeton JWT. La correspondance de motifs et les autres types de données ne sont pas pris en charge.
-
maxClockSkewInSeconds: <seconds-difference>
indique éventuellement l'écart maximal entre les horloges système du fournisseur d'identités qui a émis le jeton JWT et la passerelle d'API. La valeur indiquée est prise en compte lorsque la passerelle d'API valide le jeton JWT afin de déterminer sa validité à l'aide de la demande de début de validité (nbf
), si elle est présente, et de la demande d'expiration (exp
) du jeton JWT. La valeur minimale (par défaut) est0
et la valeur maximale est120
.
Par exemple, la stratégie
authentication
suivante configure la passerelle d'API avec une clé de vérification publique déjà émise par un fournisseur d'identités afin de valider le jeton JWT dans l'en-tête de demande d'autorisation :{ "requestPolicies": { "authentication": { "type": "JWT_AUTHENTICATION", "isAnonymousAccessAllowed": false, "issuers": ["https://identity.oraclecloud.com/"], "tokenHeader": "Authorization", "tokenAuthScheme": "Bearer", "audiences": ["api.dev.io"], "publicKeys": { "type": "STATIC_KEYS", "keys": [ { "format": "JSON_WEB_KEY", "kid": "master_key", "kty": "RSA", "n": "0vx7agoebGc...KnqDKgw", "e": "AQAB", "alg": "RS256", "use": "sig" } ] }, "verifyClaims": [ { "key": "is_admin", "values": ["service:app", "read:hello"], "isRequired": true } ], "maxClockSkewInSeconds": 10 } }, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
-
-
Ajoutez une stratégie de demande
authorization
à chaque routage dans la spécification de déploiement d'API :-
Insérez une section
requestPolicies
après la sectionbackend
du premier routage, s'il n'en existe pas déjà une. Par exemple :{ "requestPolicies": { "authentication": { "type": "JWT_AUTHENTICATION", "isAnonymousAccessAllowed": false, "issuers": ["https://identity.oraclecloud.com/"], "tokenHeader": "Authorization", "tokenAuthScheme": "Bearer", "audiences": ["api.dev.io"], "publicKeys": { "type": "STATIC_KEYS", "keys": [ { "format": "JSON_WEB_KEY", "kid": "master_key", "kty": "RSA", "n": "0vx7agoebGc...KnqDKgw", "e": "AQAB", "alg": "RS256", "use": "sig" } ] }, "verifyClaims": [ { "key": "is_admin", "values": ["service:app", "read:hello"], "isRequired": true } ], "maxClockSkewInSeconds": 10 } }, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": {} } ] }
-
Ajoutez la stratégie
authorization
suivante à la sectionrequestPolicies
:{ "requestPolicies": { "authentication": { "type": "JWT_AUTHENTICATION", "isAnonymousAccessAllowed": false, "issuers": ["https://identity.oraclecloud.com/"], "tokenHeader": "Authorization", "tokenAuthScheme": "Bearer", "audiences": ["api.dev.io"], "publicKeys": { "type": "STATIC_KEYS", "keys": [ { "format": "JSON_WEB_KEY", "kid": "master_key", "kty": "RSA", "n": "0vx7agoebGc...KnqDKgw", "e": "AQAB", "alg": "RS256", "use": "sig" } ] }, "verifyClaims": [ { "key": "is_admin", "values": ["service:app", "read:hello"], "isRequired": true } ], "maxClockSkewInSeconds": 10 } }, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "authorization": { "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">, "allowedScope": [ "<scope>" ] } } } ] }
où :
-
"type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">
indique comment accorder l'accès au routage :"AUTHENTICATION_ONLY"
: n'accorde l'accès qu'aux utilisateurs finals qui ont été authentifiés. Dans ce cas, la propriété"isAnonymousAccessAllowed"
dans la stratégieauthentication
de la spécification de déploiement d'API n'a aucun effet."ANY_OF"
: n'accorde l'accès qu'aux utilisateurs finals qui ont été authentifiés, à condition que la demandescope
du jeton JWT comporte l'une des portées d'accès que vous avez indiquées dans la propriétéallowedScope
. Dans ce cas, la propriété"isAnonymousAccessAllowed"
dans la stratégieauthentication
de la spécification de déploiement d'API n'a aucun effet."ANONYMOUS"
: accorde l'accès à tous les utilisateurs finals, même s'ils n'ont pas été authentifiés. Dans ce cas, vous devez définir explicitement la propriété"isAnonymousAccessAllowed"
surtrue
dans la stratégieauthentication
de la spécification de déploiement d'API.
-
"allowedScope": [ "<scope>" ]
est une liste de chaînes séparées par des virgules correspondant aux portées d'accès contenues dans la demandescope
du jeton JWT. Dans ce cas, vous devez définir la propriététype
sur"ANY_OF"
(la propriété"allowedScope"
est ignorée si la propriététype
est définie sur"AUTHENTICATION_ONLY"
ou"ANONYMOUS"
). Si vous indiquez plusieurs portées, l'accès au routage est accordé si l'une des portées que vous indiquez est comprise dans la demandescope
du jeton JWT.
Par exemple, la stratégie de demande suivante définit un routage
/hello
auquel seuls les utilisateurs finals authentifiés avec la portéeread:hello
peuvent accéder :{ "requestPolicies": { "authentication": { "type": "JWT_AUTHENTICATION", "isAnonymousAccessAllowed": false, "issuers": ["https://identity.oraclecloud.com/"], "tokenHeader": "Authorization", "tokenAuthScheme": "Bearer", "audiences": ["api.dev.io"], "publicKeys": { "type": "STATIC_KEYS", "keys": [ { "format": "JSON_WEB_KEY", "kid": "master_key", "kty": "RSA", "n": "0vx7agoebGc...KnqDKgw", "e": "AQAB", "alg": "RS256", "use": "sig" } ] }, "verifyClaims": [ { "key": "is_admin", "values": ["service:app", "read:hello"], "isRequired": true } ], "maxClockSkewInSeconds": 10 } }, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "authorization": { "type": "ANY_OF", "allowedScope": [ "read:hello" ] } } } ] }
-
- Ajoutez une stratégie de demande
authorization
pour tous les routages restants dans la spécification de déploiement d'API.
Remarque
Si vous n'incluez pas de stratégie
authorization
pour un routage particulier, l'accès est accordé comme si une stratégie existait et que la propriététype
était définie sur"AUTHENTICATION_ONLY"
. En d'autres termes, quel que soit le paramètre de la propriétéisAnonymousAccessAllowed
dans la stratégieauthentication
de la spécification de déploiement d'API, les conditions suivantes sont vraies :- Seuls les utilisateurs finals authentifiés peuvent accéder au routage.
- Tous les utilisateurs finals authentifiés peuvent accéder au routage indépendamment des portées d'accès comprises dans la demande
scope
du jeton JWT. - Les utilisateurs finals anonymes ne peuvent pas accéder au routage.
-
- Enregistrez le fichier JSON qui contient la spécification de déploiement d'API.
-
Utilisez 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 Télécharger une API existante,
- spécifiant le fichier JSON dans une demande adressée à l'API REST d'API Gateway.
Pour plus d'informations, reportez-vous à 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 en l'appelant (reportez-vous à Appel d'une API déployée sur une passerelle d'API).
Exemple : migration d'une stratégie de demande JWT_AUTHENTICATION vers une stratégie de demande TOKEN_AUTHENTICATION
Cette section présente un exemple de stratégie de demande JWT_AUTHENTICATION existante migrée vers une stratégie TOKEN_AUTHENTICATION.
Une façon d'aborder la migration consiste à créer une stratégie de demande TOKEN_AUTHENTICATION vide, puis à la remplir avec les valeurs de la stratégie de demande JWT_AUTHENTICATION
Avant la migration :
Stratégie de demande JWT_AUTHENTICATION d'origine, avant la migration :
{
"requestPolicies": {
"authentication": {
"type": "JWT_AUTHENTICATION",
"isAnonymousAccessAllowed": false,
"issuers": ["https://identity.oraclecloud.com/"],
"tokenHeader": "Authorization",
"tokenAuthScheme": "Bearer",
"audiences": ["api.dev.io"],
"publicKeys": {
"type": "STATIC_KEYS",
"keys": [
{
"format": "JSON_WEB_KEY",
"kid": "master_key",
"kty": "RSA",
"n": "0vx7agoebGc...KnqDKgw",
"e": "AQAB",
"alg": "RS256",
"use": "sig"
}
]
},
"verifyClaims": [
{
"key": "is_admin",
"values": ["service:app", "read:hello"],
"isRequired": true
}
],
"maxClockSkewInSeconds": 10
}
},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
},
"requestPolicies": {
"authorization": {
"type": "ANY_OF",
"allowedScope": [ "read:hello" ]
}
}
}
]
}
Après la migration :
La nouvelle stratégie de demande TOKEN_AUTHENTICATION est remplie avec les valeurs de la stratégie de demande JWT_AUTHENTICATION d'origine :
{
"requestPolicies": {
"authentication": {
"type": "TOKEN_AUTHENTICATION",
"isAnonymousAccessAllowed": false,
"tokenHeader": "Authorization",
"tokenAuthScheme": "Bearer",
"maxClockSkewInSeconds": 10,
"validationPolicy": {
"type": "STATIC_KEYS",
"keys": [
{
"format": "JSON_WEB_KEY",
"kid": "master_key",
"kty": "RSA",
"n": "0vx7agoebGc...KnqDKgw",
"e": "AQAB",
"alg": "RS256",
"use": "sig"
}
],
"additionalValidationPolicy": {
"audiences": [
"api.dev.io"
],
"verifyClaims": [
{
"key": "is_admin",
"values": [
"service:app",
"read:hello"
],
"isRequired": true
}
],
"issuers": [
"https://identity.oraclecloud.com/"
]
}
}
}
},
"routes": [
{
"path": "/hello",
"methods": [
"GET"
],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
},
"requestPolicies": {
"authorization": {
"type": "ANY_OF",
"allowedScope": [
"read:hello"
]
}
}
}
]
}