Création d'une fonction d'autorisation

Pour créer une fonction d'autorisation qui accepte un jeton d'accès à arguments multiples défini par l'utilisateur, procédez comme suit :

1. Ecrivez le code dans la fonction d'autorisation qui accepte le format JSON comme entrée à partir d'API Gateway :

   
   {
     "type": "USER_DEFINED",
     "data": {
       "<argument-n>": "<context-variable-value>",
       "<argument-n>": "<context-variable-value>",
       "<argument-n>": "<context-variable-value>"
     }
   }

   où :

   • "type": "USER_DEFINED" indique que les arguments et les valeurs transmis à la fonction d'autorisation sont définis dans la spécification de déploiement d'API.
   • "<argument-n>" est un nom d'argument correspondant à un nom d'argument défini par l'utilisateur indiqué dans la section parameters de la spécification de déploiement d'API. Par exemple, "state", "xapikey"
   • "<context-variable-value>" est la valeur de la variable de contexte indiquée dans la section parameters de la spécification de déploiement d'API. Par exemple, la valeur de la variable de contexte de paramètre de requête request.query[state], la valeur de la variable de contexte de paramètre d'en-tête request.headers[X-Api-Key]. Lors de la transmission de plusieurs valeurs à la fonction d'autorisation à partir des en-têtes de demande et des paramètres de requête, "<context-variable-value>" est transmis à la fonction d'autorisation en tant que tableau. Notez également que si la valeur d'une variable de contexte n'est pas présente dans la demande d'origine adressée à la passerelle d'API, la variable de contexte n'est pas transmise à la fonction d'autorisation.

   Par exemple, vous pouvez souhaiter que la fonction d'autorisation accepte les valeurs de la variable de contexte de paramètre de requête request.query[state] et de la variable de contexte de paramètre d'en-tête request.headers[X-Api-Key] en tant qu'entrée à partir d'API Gateway. Par exemple, si les valeurs de la variable de contexte de paramètre de requête request.query[state] et de la variable de contexte de paramètre d'en-tête request.headers[X-Api-Key] sont respectivement california et abc123def456fhi789, la fonction d'autorisation doit accepter l'entrée JSON suivante :

   
   {
     "type": "USER_DEFINED",
     "data": {
       "state": "california",
       "xapikey": "abc123def456fhi789"
     }
   }

   Si l'en-tête X-API-Key n'est pas présent dans la demande d'origine à la passerelle d'API, la variable de contexte xapikey n'est pas transmise du tout à la fonction d'autorisation (plutôt que d'être transmise avec une valeur NULL).

2. Ecrivez le code dans la fonction d'autorisation qui renvoie le JSON suivant à API Gateway en tant que réponse HTTP 200 lorsque le jeton d'accès à arguments multiples défini par l'utilisateur a été vérifié auprès d'un fournisseur d'identités et que ce dernier a déterminé que le jeton est valide :

   {
     "active": true,
     "scope": ["<scopes>"],
     "expiresAt": "<date-time>",
     "context": {
       "<key>": "<value>", ... 
     }
   }

   où :

   • "active": true indique que le fournisseur d'identités a déterminé que le jeton d'accès initialement transmis à la fonction d'autorisation est valide. Ce champ booléen est facultatif, mais sa valeur par défaut est false s'il n'est pas inclus dans la réponse JSON.
   • "scope": ["<scopes>"] est éventuellement les portées d'accès obtenues par la fonction d'autorisation auprès du fournisseur d'identités. ["<scopes>"] peut être un tableau JSON de chaînes séparées par des virgules, telles que ["list:hello", "read:hello", "create:hello"], ou une chaîne séparée par des espaces, telle que "list:hello read:hello create:hello". Ce champ est obligatoire si la propriété type de la stratégie de demande d'autorisation est définie sur ANY_OF .
   • "expiresAt": "<date-time>" est éventuellement une chaîne date/heure au format ISO-8601, ce qui indique quand le jeton d'accès initialement transmis à la fonction d'autorisation doit expirer. Cette valeur est utilisée lors de la détermination de la durée de mise en mémoire cache des résultats après l'appel de la fonction d'autorisation. Vous pouvez mettre les résultats en cache pendant au moins 60 secondes et au maximum 1 heure. Si ce champ n'est pas inclus dans la réponse JSON ou si "<date-time>" n'est pas valide, les résultats sont mis en cache pendant 60 secondes.
   • "context": {"<key>": "<value>", ... } est une liste facultative de paires clé-valeur séparées par des virgules au format JSON à renvoyer à API Gateway. La fonction d'autorisation peut renvoyer n'importe quelle paire clé-valeur devant être utilisée par le déploiement d'API (par exemple, le nom utilisateur ou l'adresse électronique de l'utilisateur final). Pour plus d'informations sur l'utilisation de la valeur de la paire clé-valeur renvoyée par une fonction d'autorisation en tant que variable de contexte 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.

   Par exemple :

   {
     "active": true,
     "scope": ["list:hello", "read:hello", "create:hello", "update:hello", "delete:hello", "someScope"],
     "expiresAt": "2019-05-30T10:15:30+01:00",
     "context": {
       "email": "john.doe@example.com"
     }
   }

   Lorsque la fonction d'autorisation renvoie une réponse HTTP 200 et active: true dans le corps JSON de la réponse, API Gateway renvoie une réponse HTTP 200 au client d'API.

3. Ecrivez le code dans la fonction d'autorisation qui renvoie le JSON suivant à API Gateway en tant que réponse HTTP 200 lorsque le jeton d'accès à arguments multiples défini par l'utilisateur a été vérifié auprès d'un fournisseur d'identités, mais que le fournisseur d'identités a déterminé que le jeton n'est pas valide :

   {
     "active": false,
     "wwwAuthenticate": "<directive>"
   }

   où :

   • "active": false indique que le fournisseur d'identités a déterminé que le jeton d'accès initialement transmis à la fonction d'autorisation n'est pas valide. Ce champ est facultatif, mais sa valeur par défaut est false s'il n'est pas présent dans la réponse JSON.
   • "wwwAuthenticate": "<directive>" est éventuellement la valeur de l'en-tête WWW-Authenticate qui doit être renvoyée par la fonction d'autorisation si le jeton d'accès n'est pas valide. Elle indique le type d'authentification requis (par exemple, de base ou service support). Par exemple, "wwwAuthenticate": "Bearer realm=\"example.com\"". Pour plus d'informations, reportez-vous à Authentification HTTP RFC 2617 : authentification d'accès de base et condensée.

   Par exemple :

   {
     "active": false,
     "wwwAuthenticate": "Bearer realm=\"example.com\""
   }

   Vous pouvez éventuellement inclure une section validationFailurePolicy dans la spécification de déploiement d'API afin de modifier le code de réponse, le message de réponse et les en-têtes de réponse renvoyés au client d'API. Si vous n'incluez pas de section validationFailurePolicy, API Gateway renvoie l'en-tête WWW-Authenticate dans la réponse au client d'API, ainsi qu'un code de statut 401. Reportez-vous à Remarques sur les stratégies d'échec de validation et la gestion des réponses d'authentification ayant échoué à partir de fonctions d'autorisation à arguments multiples.

4. Ecrivez du code dans la fonction d'autorisation qui renvoie une réponse HTTP 5xx si le jeton n'a pas pu être vérifié auprès du fournisseur d'identités (on ne sait donc pas si le jeton est valide ou non valide), ou en cas d'erreur dans la fonction d'autorisation ou dans OCI Functions.

   Lorsque la fonction d'autorisation renvoie une réponse HTTP 5xx, API Gateway renvoie une réponse HTTP 502 au client d'API. Tout JSON dans le corps de la réponse est ignoré.

Pour créer une fonction d'autorisation qui accepte un jeton d'accès à argument unique comprenant une valeur unique contenue dans un en-tête de demande ou un paramètre de requête, procédez comme suit :

1. Ecrivez le code dans la fonction d'autorisation qui accepte l'entrée JSON suivante à partir d'API Gateway :

   
   {
     "type": "TOKEN",
     "token": "<token-value>"
   }

   où :

   • "type": "TOKEN" indique que la valeur transmise à la fonction d'autorisation est un jeton d'authentification.
   • "token": "<token-value>" est le jeton d'authentification transmis à la fonction d'autorisation.

   Par exemple :

   
   {
     "type": "TOKEN",
     "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1nHyDtTwR3SEJ3z489..."
   }

2. Ecrivez le code dans la fonction d'autorisation qui renvoie le JSON suivant à API Gateway en tant que réponse HTTP 200 lorsque le jeton d'accès a été vérifié auprès d'un fournisseur d'identités et que le fournisseur d'identités a déterminé que le jeton est valide :

   {
     "active": true,
     "scope": ["<scopes>"],
     "expiresAt": "<date-time>",
     "context": {
       "<key>": "<value>", ... 
     }
   }

   où :

   • "active": true indique que le fournisseur d'identités a déterminé que le jeton d'accès initialement transmis à la fonction d'autorisation est valide. Ce champ booléen est facultatif, mais sa valeur par défaut est false s'il n'est pas inclus dans la réponse JSON.
   • "scope": ["<scopes>"] est éventuellement les portées d'accès obtenues par la fonction d'autorisation auprès du fournisseur d'identités. ["<scopes>"] peut être un tableau JSON de chaînes séparées par des virgules, telles que ["list:hello", "read:hello", "create:hello"], ou une chaîne séparée par des espaces, telle que "list:hello read:hello create:hello". Ce champ est obligatoire si la propriété type de la stratégie de demande d'autorisation est définie sur ANY_OF .
   • "expiresAt": "<date-time>" est éventuellement une chaîne date/heure au format ISO-8601, ce qui indique quand le jeton d'accès initialement transmis à la fonction d'autorisation doit expirer. Cette valeur est utilisée lors de la détermination de la durée de mise en mémoire cache des résultats après l'appel de la fonction d'autorisation. Vous pouvez mettre les résultats en cache pendant au moins 60 secondes et au maximum 1 heure. Si ce champ n'est pas inclus dans la réponse JSON ou si "<date-time>" n'est pas valide, les résultats sont mis en cache pendant 60 secondes.
   • "context": {"<key>": "<value>", ... } est une liste facultative de paires clé-valeur séparées par des virgules au format JSON à renvoyer à API Gateway. La fonction d'autorisation peut renvoyer toute paire clé-valeur devant être utilisée par le déploiement d'API (par exemple, le nom utilisateur ou l'adresse électronique d'un utilisateur final). Pour plus d'informations sur l'utilisation de la valeur de la paire clé-valeur renvoyée par une fonction d'autorisation en tant que variable de contexte 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.

   Par exemple :

   {
     "active": true,
     "scope": ["list:hello", "read:hello", "create:hello", "update:hello", "delete:hello", "someScope"],
     "expiresAt": "2019-05-30T10:15:30+01:00",
     "context": {
       "email": "john.doe@example.com"
     }
   }

   Lorsque la fonction d'autorisation renvoie une réponse HTTP 200 et active: true dans le corps JSON de la réponse, API Gateway renvoie une réponse HTTP 200 au client d'API.

   Notez que la réponse de la fonction d'autorisation à argument unique a le même format qu'une réponse d'une fonction d'autorisation à arguments multiples (reportez-vous à Création d'une fonction d'autorisation à arguments multiples (recommandée)).

3. Ecrivez le code dans la fonction d'autorisation qui renvoie le JSON suivant à API Gateway en tant que réponse HTTP 200 lorsque le jeton d'accès a été vérifié auprès d'un fournisseur d'identités, mais que le fournisseur d'identités a déterminé que le jeton n'est pas valide :

   {
     "active": false,
     "wwwAuthenticate": "<directive>"
   }

   où :

   • "active": false indique que le fournisseur d'identités a déterminé que le jeton d'accès initialement transmis à la fonction d'autorisation n'est pas valide. Ce champ est facultatif, mais sa valeur par défaut est false s'il n'est pas présent dans la réponse JSON.
   • "wwwAuthenticate": "<directive>" est éventuellement la valeur de l'en-tête WWW-Authenticate qui doit être renvoyée par la fonction d'autorisation si le jeton d'accès n'est pas valide. Elle indique le type d'authentification requis (par exemple, de base ou service support). Par exemple, "wwwAuthenticate": "Bearer realm=\"example.com\"". Pour plus d'informations, reportez-vous à Authentification HTTP RFC 2617 : authentification d'accès de base et condensée.

   Par exemple :

   {
     "active": false,
     "wwwAuthenticate": "Bearer realm=\"example.com\""
   }

   API Gateway renvoie l'en-tête WWW-Authenticate dans la réponse au client d'API, ainsi qu'un code de statut 401.

   Notez que la réponse de la fonction d'autorisation à argument unique a le même format qu'une réponse d'une fonction d'autorisation à arguments multiples (reportez-vous à Création d'une fonction d'autorisation à arguments multiples (recommandée)).

4. Ecrivez du code dans la fonction d'autorisation qui renvoie une réponse HTTP 5xx si le jeton n'a pas pu être vérifié auprès du fournisseur d'identités (on ne sait donc pas si le jeton est valide ou non valide), ou en cas d'erreur dans la fonction d'autorisation ou dans OCI Functions.

   Lorsque la fonction d'autorisation renvoie une réponse HTTP 5xx, API Gateway renvoie une réponse HTTP 502 au client d'API. Tout JSON dans le corps de la réponse est ignoré.

Pour consulter un tutoriel de développeur connexe contenant un exemple de fonction d'autorisation, reportez-vous à Functions : validation d'une clé d'API avec API Gateway.