Creazione di una funzione del responsabile autorizzazioni

Per creare una funzione del responsabile autorizzazioni che accetti un token di accesso a più argomenti definito dall'utente, procedere come segue.

1. Scrivere il codice nella funzione del responsabile autorizzazioni che accetta JSON nel seguente formato come input da API Gateway:

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

   dove:

   • "type": "USER_DEFINED" indica che gli argomenti e i valori passati alla funzione del responsabile autorizzazioni sono definiti nella specifica di distribuzione API.
   • "<argument-n>" è un nome di argomento corrispondente a un nome di argomento definito dall'utente specificato nella sezione parameters della specifica di distribuzione API. Ad esempio, "state", "xapikey"
   • "<context-variable-value>" è il valore della variabile di contesto specificata nella sezione parameters della specifica di distribuzione API. Ad esempio, il valore della variabile di contesto del parametro di query request.query[state], ovvero il valore della variabile di contesto del parametro di intestazione request.headers[X-Api-Key]. Quando si passano più valori alla funzione del responsabile autorizzazioni dalle intestazioni di richiesta e dai parametri di query, "<context-variable-value>" viene passato alla funzione del responsabile autorizzazioni come array. Inoltre, se il valore di una variabile di contesto non è presente nella richiesta originale al gateway API, la variabile di contesto non viene passata alla funzione del responsabile autorizzazioni.

   Ad esempio, è possibile che la funzione del responsabile autorizzazioni accetti i valori della variabile di contesto del parametro di query request.query[state] e della variabile di contesto del parametro di intestazione request.headers[X-Api-Key] come input da API Gateway. Ad esempio, se i valori della variabile di contesto del parametro di query request.query[state] e della variabile di contesto del parametro di intestazione request.headers[X-Api-Key] sono rispettivamente california e abc123def456fhi789, la funzione del responsabile autorizzazioni deve accettare il seguente input JSON:

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

   Tenere presente che se l'intestazione X-API-Key non è presente nella richiesta originale al gateway API, la variabile di contesto xapikey non viene passata alla funzione del responsabile autorizzazioni (anziché essere passata con un valore nullo).

2. Scrivere il codice nella funzione del responsabile autorizzazioni che restituisce il seguente JSON a Gateway API come risposta HTTP 200 quando il token di accesso multiargomento definito dall'utente è stato verificato correttamente con un provider di identità e il provider di identità ha determinato che il token è valido:

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

   dove:

   • "active": true indica che il provider di identità ha determinato che il token di accesso originariamente passato alla funzione del responsabile autorizzazioni è valido. Si noti che questo campo booleano è facoltativo, ma per impostazione predefinita viene utilizzato false se non è incluso nella risposta JSON.
   • "scope": ["<scopes>"] è facoltativamente l'ambito di accesso ottenuto dalla funzione del responsabile autorizzazioni dal provider di identità. Si noti che ["<scopes>"] può essere un array JSON di stringhe delimitate da virgole, ad esempio ["list:hello", "read:hello", "create:hello"], oppure una stringa separata da spazi, ad esempio "list:hello read:hello create:hello". Si noti che questo campo è obbligatorio se la proprietà type del criterio di richiesta di autorizzazione è impostata su ANY_OF.
   • "expiresAt": "<date-time>" è facoltativamente una stringa di data e ora in formato ISO-8601 che indica quando scadrà il token di accesso passato originariamente alla funzione del responsabile autorizzazioni. Questo valore viene utilizzato per determinare per quanto tempo inserire i risultati nella cache dopo aver richiamato la funzione del responsabile autorizzazioni. È possibile inserire i risultati nella cache per un minimo di 60 secondi e un massimo di 1 ora. Tenere presente che se questo campo non è incluso nella risposta JSON o se "<date-time>" non è valido, i risultati vengono inseriti nella cache per 60 secondi.
   • "context": {"<key>": "<value>", ... } è una lista facoltativa delimitata da virgole di coppie chiave-valore in formato JSON per tornare a Gateway API. La funzione del responsabile autorizzazioni può restituire qualsiasi coppia chiave-valore utilizzata dalla distribuzione dell'API (ad esempio, il nome utente o l'indirizzo di posta elettronica dell'utente finale). Per ulteriori informazioni sull'uso del valore nella coppia chiave-valore restituita da una funzione del responsabile autorizzazioni come variabile di contesto in una definizione backend HTTP, vedere Aggiunta di variabili di contesto ai criteri e alle definizioni backend HTTP.

   Ad esempio:

   {
     "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"
     }
   }

   Quando la funzione del responsabile autorizzazioni restituisce una risposta HTTP 200 e active: true nel corpo JSON della risposta, Gateway API restituisce una risposta HTTP 200 al client API.

3. Scrivere il codice nella funzione del responsabile autorizzazioni che restituisce il seguente JSON a Gateway API come risposta HTTP 200 quando il token di accesso multiargomento definito dall'utente è stato verificato correttamente con un provider di identità, ma il provider di identità ha determinato che il token non è valido:

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

   dove:

   • "active": false indica che il provider di identità ha determinato che il token di accesso passato originariamente alla funzione del responsabile autorizzazioni non è valido. Tenere presente che questo campo è facoltativo, ma l'impostazione predefinita è false se non è presente nella risposta JSON.
   • "wwwAuthenticate": "<directive>" è facoltativamente il valore dell'intestazione WWW-Authenticate che deve essere restituita dalla funzione del responsabile autorizzazioni se il token di accesso non è valido, indicando il tipo di autenticazione richiesto (ad esempio Basic o Bearer). Ad esempio, "wwwAuthenticate": "Bearer realm=\"example.com\"". Per ulteriori informazioni, vedere RFC 2617 HTTP Authentication: Basic and Digest Access Authentication.

   Ad esempio:

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

   Facoltativamente, è possibile includere una sezione validationFailurePolicy nella specifica di distribuzione API per modificare il codice di risposta, il messaggio di risposta e le intestazioni di risposta restituite al client API. Se non si include una sezione validationFailurePolicy, API Gateway restituisce l'intestazione WWW-Authenticate nella risposta al client API, insieme a un codice di stato 401. Vedere Note sui criteri di errore di convalida e gestione delle risposte di autenticazione non riuscite dalle funzioni del responsabile autorizzazioni più argomenti.

4. Scrivere il codice nella funzione del responsabile autorizzazioni che restituisce una risposta HTTP 5xx se non è stato possibile verificare il token con il provider di identità (per cui non è noto se il token è valido o non valido) o in caso di errore nella funzione del responsabile autorizzazioni o nelle funzioni OCI.

   Quando la funzione del responsabile autorizzazioni restituisce una risposta HTTP 5xx, Gateway API restituisce una risposta HTTP 502 al client API. Qualsiasi JSON nel corpo della risposta viene ignorato.

Per creare una funzione del responsabile autorizzazioni che accetti un token di accesso a un singolo argomento che comprenda un singolo valore contenuto in un'intestazione di richiesta o in un parametro di query, procedere come segue.

1. Scrivere il codice nella funzione del responsabile autorizzazioni che accetta il seguente input JSON dal gateway API:

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

   dove:

   • "type": "TOKEN" indica che il valore passato alla funzione del responsabile autorizzazioni è un token di autenticazione.
   • "token": "<token-value>" è il token di autenticazione passato alla funzione del responsabile autorizzazioni.

   Ad esempio:

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

2. Scrivere il codice nella funzione del responsabile autorizzazioni che restituisce il seguente JSON a Gateway API come risposta HTTP 200 quando il token di accesso è stato verificato correttamente con un provider di identità e il provider di identità ha determinato che il token è valido:

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

   dove:

   • "active": true indica che il provider di identità ha determinato che il token di accesso originariamente passato alla funzione del responsabile autorizzazioni è valido. Si noti che questo campo booleano è facoltativo, ma per impostazione predefinita viene utilizzato false se non è incluso nella risposta JSON.
   • "scope": ["<scopes>"] è facoltativamente l'ambito di accesso ottenuto dalla funzione del responsabile autorizzazioni dal provider di identità. Si noti che ["<scopes>"] può essere un array JSON di stringhe delimitate da virgole, ad esempio ["list:hello", "read:hello", "create:hello"], oppure una stringa separata da spazi, ad esempio "list:hello read:hello create:hello". Si noti che questo campo è obbligatorio se la proprietà type del criterio di richiesta di autorizzazione è impostata su ANY_OF.
   • "expiresAt": "<date-time>" è facoltativamente una stringa di data e ora in formato ISO-8601 che indica quando scadrà il token di accesso passato originariamente alla funzione del responsabile autorizzazioni. Questo valore viene utilizzato per determinare per quanto tempo inserire i risultati nella cache dopo aver richiamato la funzione del responsabile autorizzazioni. È possibile inserire i risultati nella cache per un minimo di 60 secondi e un massimo di 1 ora. Tenere presente che se questo campo non è incluso nella risposta JSON o se "<date-time>" non è valido, i risultati vengono inseriti nella cache per 60 secondi.
   • "context": {"<key>": "<value>", ... } è una lista facoltativa delimitata da virgole di coppie chiave-valore in formato JSON per tornare a Gateway API. La funzione del responsabile autorizzazioni può restituire qualsiasi coppia chiave-valore utilizzata dalla distribuzione API (ad esempio, il nome utente o l'indirizzo di posta elettronica di un utente finale). Per ulteriori informazioni sull'uso del valore nella coppia chiave-valore restituita da una funzione del responsabile autorizzazioni come variabile di contesto in una definizione backend HTTP, vedere Aggiunta di variabili di contesto ai criteri e alle definizioni backend HTTP.

   Ad esempio:

   {
     "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"
     }
   }

   Quando la funzione del responsabile autorizzazioni restituisce una risposta HTTP 200 e active: true nel corpo JSON della risposta, Gateway API restituisce una risposta HTTP 200 al client API.

   Tenere presente che la risposta della funzione di autorizzazione a singolo argomento ha lo stesso formato di una risposta di una funzione di autorizzazione a più argomenti (vedere Creazione di una funzione di autorizzazione a più argomenti (consigliata)).

3. Scrivere il codice nella funzione del responsabile autorizzazioni che restituisce il seguente JSON a Gateway API come risposta HTTP 200 quando il token di accesso è stato verificato correttamente con un provider di identità, ma il provider di identità ha determinato che il token non è valido:

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

   dove:

   • "active": false indica che il provider di identità ha determinato che il token di accesso passato originariamente alla funzione del responsabile autorizzazioni non è valido. Tenere presente che questo campo è facoltativo, ma l'impostazione predefinita è false se non è presente nella risposta JSON.
   • "wwwAuthenticate": "<directive>" è facoltativamente il valore dell'intestazione WWW-Authenticate che deve essere restituita dalla funzione del responsabile autorizzazioni se il token di accesso non è valido, indicando il tipo di autenticazione richiesto (ad esempio Basic o Bearer). Ad esempio, "wwwAuthenticate": "Bearer realm=\"example.com\"". Per ulteriori informazioni, vedere RFC 2617 HTTP Authentication: Basic and Digest Access Authentication.

   Ad esempio:

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

   Gateway API restituisce l'intestazione WWW-Authenticate nella risposta al client API, insieme a un codice di stato 401.

   Tenere presente che la risposta della funzione di autorizzazione a singolo argomento ha lo stesso formato di una risposta di una funzione di autorizzazione a più argomenti (vedere Creazione di una funzione di autorizzazione a più argomenti (consigliata)).

4. Scrivere il codice nella funzione del responsabile autorizzazioni che restituisce una risposta HTTP 5xx se non è stato possibile verificare il token con il provider di identità (per cui non è noto se il token è valido o non valido) o in caso di errore nella funzione del responsabile autorizzazioni o nelle funzioni OCI.

   Quando la funzione del responsabile autorizzazioni restituisce una risposta HTTP 5xx, Gateway API restituisce una risposta HTTP 502 al client API. Qualsiasi JSON nel corpo della risposta viene ignorato.

Per un'esercitazione per sviluppatori correlata contenente una funzione di esempio del responsabile autorizzazioni, vedere Funzioni: convalida una chiave API con gateway API.