Création d'une fonction d'autorisation

Pour créer une fonction d'autorisation qui accepte un jeton d'accès à plusieurs arguments défini par l'utilisateur :

1. Écrivez un code dans la fonction d'autorisation, qui accepte le format JSON suivant en tant qu'entrée depuis le service de passerelle d'API :

   
   {
     "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 spécifié 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 spécifiée dans la section parameters de la spécification de déploiement d'API. Par exemple, la valeur de la variable de contexte du paramètre d'interrogation request.query[state], la valeur de la variable de contexte du paramètre d'en-tête request.headers[X-Api-Key]. Notez que lors de la transmission de plusieurs valeurs à la fonction d'autorisation à partir des en-têtes de demande et des paramètres d'interrogation, "<context-variable-value>" est transmis à la fonction d'autorisation sous forme de tableau. Notez également que si la valeur d'une variable de contexte n'est pas présente dans la demande initiale à la passerelle d'API, la variable de contexte n'est pas transmise à la fonction d'autorisation.

   Par exemple, vous pouvez vouloir que la fonction d'autorisation accepte les valeurs de la variable de contexte de paramètre d'interrogation 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 de la passerelle d'API. Ainsi, par exemple, si les valeurs de la variable de contexte de paramètre d'interrogation 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"
     }
   }

   Notez que si l'en-tête X-API-Key n'est pas présent dans la demande initiale à la passerelle d'API, la variable de contexte xapikey n'est pas transmise du tout à la fonction d'autorisation (au lieu d'être transmise avec une valeur nulle).

2. Écrivez un code dans la fonction d'autorisation qui retourne le code JSON suivant dans la passerelle d'API en tant que réponse HTTP 200 lorsque le jeton d'accès à plusieurs arguments défini par l'utilisateur a été vérifié auprès d'un fournisseur d'identités et que celui-ci 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. Notez que ce champ booléen est facultatif, mais la valeur par défaut est false s'il n'est pas inclus dans la réponse JSON.
   • "scope": ["<scopes>"] est facultativement les étendues d'accès obtenues par la fonction d'autorisation auprès du fournisseur d'identités. Notez que ["<scopes>"] peut être un tableau JSON de chaînes délimité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". Notez que ce champ est obligatoire si la propriété type de la politique de demande d'autorisation est réglée à ANY_OF.
   • "expiresAt": "<date-time>" est facultativement une chaîne de date et d'heure au format ISO-8601, qui indique le moment où le jeton d'accès initialement transmis à la fonction d'autorisation expirera. Cette valeur sert à déterminer pendant combien de temps les résultats doivent être mis en mémoire cache après l'appel de la fonction d'autorisation. Vous pouvez mettre les résultats en mémoire cache pendant au moins 60 secondes et au maximum 1 heure. Notez que 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 mémoire cache pendant 60 secondes.
   • "context": {"<key>": "<value>", ... } est une liste facultative séparée par des virgules, contenant les paires clé-valeur au format JSON à retourner au service Passerelle d'API. La fonction d'autorisation peut retourner toute paire clé-valeur à utiliser avec le déploiement d'API (par exemple, le nom d'utilisateur ou l'adresse de courriel de l'utilisateur final). Pour plus d'informations sur l'utilisation de la valeur dans la paire clé-valeur retournée par une fonction d'autorisation en tant que variable de contexte dans une définition d'élément dorsal HTTP, voir Ajout de variables de contexte aux politiques et aux définitions d'élément dorsal 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 retourne une réponse HTTP 200 et active: true dans le corps JSON de la réponse, la passerelle d'API retourne une réponse HTTP 200 au client d'API.

3. Écrivez un code dans la fonction d'autorisation qui retourne le code JSON suivant dans la passerelle d'API en tant que réponse HTTP 200 lorsque le jeton d'accès à plusieurs arguments 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. Notez que ce champ est facultatif, mais que la valeur par défaut est false s'il ne figure pas dans la réponse JSON.
   • "wwwAuthenticate": "<directive>" est facultativement la valeur de l'en-tête WWW-Authenticate que la fonction d'autorisation doit retourner si le jeton d'accès n'est pas valide, indiquant le type d'authentification obligatoire (par exemple, de base ou porteur). Par exemple, "wwwAuthenticate": "Bearer realm=\"example.com\"". Pour plus d'informations, voir Authentification HTTP RFC 2617 : Authentification d'accès de base et Digest.

   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 pour modifier le code de réponse, le message de réponse et les en-têtes de réponse retournés au client d'API. Si vous n'incluez pas de section validationFailurePolicy, le service de passerelle d'API retourne l'en-tête WWW-Authenticate dans la réponse au client d'API, avec le code de statut 401. Voir Notes sur les politiques d'échec de validation et le traitement des réponses d'authentification ayant échoué à partir de fonctions d'autorisation à plusieurs arguments.

4. Écrivez du code dans la fonction d'autorisation qui retourne une réponse HTTP 5xx si le jeton n'a pas pu être vérifié auprès du fournisseur d'identités (il n'est donc pas connu si le jeton est valide ou non valide), ou en cas d'erreur dans la fonction d'autorisation ou dans le service des fonctions pour OCI.

   Lorsque la fonction d'autorisation retourne une réponse HTTP 5xx, la passerelle d'API retourne 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 à un seul argument comprenant une valeur unique contenue dans un en-tête de demande ou un paramètre d'interrogation :

1. Écrivez un code dans la fonction d'autorisation, qui accepte l'entrée JSON suivante du service Passerelle d'API :

   
   {
     "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. Écrivez un code dans la fonction d'autorisation qui retourne le code JSON suivant dans API Gateway en tant que réponse HTTP 200 lorsque le jeton d'accès est 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. Notez que ce champ booléen est facultatif, mais la valeur par défaut est false s'il n'est pas inclus dans la réponse JSON.
   • "scope": ["<scopes>"] est facultativement les étendues d'accès obtenues par la fonction d'autorisation auprès du fournisseur d'identités. Notez que ["<scopes>"] peut être un tableau JSON de chaînes délimité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". Notez que ce champ est obligatoire si la propriété type de la politique de demande d'autorisation est réglée à ANY_OF.
   • "expiresAt": "<date-time>" est facultativement une chaîne de date et d'heure au format ISO-8601, qui indique le moment où le jeton d'accès initialement transmis à la fonction d'autorisation expirera. Cette valeur sert à déterminer pendant combien de temps les résultats doivent être mis en mémoire cache après l'appel de la fonction d'autorisation. Vous pouvez mettre les résultats en mémoire cache pendant au moins 60 secondes et au maximum 1 heure. Notez que 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 mémoire cache pendant 60 secondes.
   • "context": {"<key>": "<value>", ... } est une liste facultative séparée par des virgules, contenant les paires clé-valeur au format JSON à retourner au service Passerelle d'API. La fonction d'autorisation peut retourner toute paire clé- valeur à utiliser avec le déploiement d'API (par exemple, le nom d'utilisateur ou l'adresse de courriel d'un utilisateur final). Pour plus d'informations sur l'utilisation de la valeur dans la paire clé-valeur retournée par une fonction d'autorisation en tant que variable de contexte dans une définition d'élément dorsal HTTP, voir Ajout de variables de contexte aux politiques et aux définitions d'élément dorsal 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 retourne une réponse HTTP 200 et active: true dans le corps JSON de la réponse, la passerelle d'API retourne une réponse HTTP 200 au client d'API.

   Notez que la réponse de la fonction d'autorisation à un seul argument a le même format qu'une réponse d'une fonction d'autorisation à plusieurs arguments (voir Création d'une fonction d'autorisation à plusieurs arguments (recommandée)).

3. Écrivez un code dans la fonction d'autorisation qui retourne le code JSON suivant dans API Gateway en tant que réponse HTTP 200 lorsque le jeton d'accès est vérifié auprès d'un fournisseur d'identités, mais 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. Notez que ce champ est facultatif, mais que la valeur par défaut est false s'il ne figure pas dans la réponse JSON.
   • "wwwAuthenticate": "<directive>" est facultativement la valeur de l'en-tête WWW-Authenticate que la fonction d'autorisation doit retourner si le jeton d'accès n'est pas valide, indiquant le type d'authentification obligatoire (par exemple, de base ou porteur). Par exemple, "wwwAuthenticate": "Bearer realm=\"example.com\"". Pour plus d'informations, voir Authentification HTTP RFC 2617 : Authentification d'accès de base et Digest.

   Par exemple :

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

   Le service Passerelle d'API retourne l'en-tête WWW-Authenticate dans la réponse au client d'API, avec le code de statut 401.

   Notez que la réponse de la fonction d'autorisation à un seul argument a le même format qu'une réponse d'une fonction d'autorisation à plusieurs arguments (voir Création d'une fonction d'autorisation à plusieurs arguments (recommandée)).

4. Écrivez du code dans la fonction d'autorisation qui retourne une réponse HTTP 5xx si le jeton n'a pas pu être vérifié auprès du fournisseur d'identités (il n'est donc pas connu si le jeton est valide ou non valide), ou en cas d'erreur dans la fonction d'autorisation ou dans le service des fonctions pour OCI.

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

Pour un tutoriel pour développeurs connexe contenant un exemple de fonction d'autorisation, voir Fonctions : Valider une clé d'API avec le service de passerelle d'API.