Documentazione di Oracle Cloud Infrastructure

Aggiunta del logout come backend del gateway API

Scopri come definire un back-end di logout con API Gateway.

Un requisito comune è che le API forniscano la funzionalità per consentire ai client API di eseguire il logout in modo pulito revocando i token di accesso e potenzialmente richiamando altri URL per eseguire ulteriori task successivi al logout. Gateway API consente di definire i backend di logout per fornire tale funzionalità quando si utilizza un criterio di autenticazione token OAuth 2.0 per una distribuzione API. Le richieste al back-end di logout possono facoltativamente includere un URL successivo al logout come valore di un parametro di query denominato postLogoutUrl.

Quando si definisce un criterio di autenticazione token OAuth 2.0 , è possibile specificare facoltativamente un percorso del back-end di logout (il percorso di logout) per revocare i token di accesso in caso di errore di autenticazione. Vedere Convalida dei token per l'aggiunta di autenticazione e autorizzazione alle distribuzioni API.

La definizione del back-end di logout include facoltativamente:

  • Lista di URL successivi al logout consentiti a cui è possibile reindirizzare una richiesta per revocare i token di accesso. Se il parametro di query postLogoutUrl è incluso nella richiesta, il relativo valore deve essere uno di questi URL. Gli URL nella lista possono essere percorsi assoluti o percorsi relativi e gli URL possono includere variabili di contesto. Tenere presente che se si specifica un percorso relativo (ovvero un altro instradamento nella distribuzione dell'API), sia la distribuzione dell'API che l'instradamento devono consentire l'accesso anonimo. Inoltre, se non si includono in modo esplicito uno o più URL nella lista, è consentito qualsiasi URL successivo al logout.
  • Dati da passare agli URL di logout quando la richiesta viene reindirizzata, come valore del parametro di query state. I dati possono includere solo variabili di contesto (non valori statici).

Alla ricezione di una richiesta al percorso di logout da un client API, il gateway API controlla che il client API sia autenticato per richiamare il back-end di logout, controlla che sia consentito qualsiasi URL successivo al logout incluso nella richiesta e rimuove qualsiasi informazione memorizzata sulla sessione del client API (ad esempio, nei cookie). Supponendo che l'URL successivo al logout sia consentito, l'operazione successiva dipende dal fatto che il client API sia autenticato e dal fatto che la risposta inserita nella cache in precedenza dall'URL di ricerca automatica specificato nel criterio di autenticazione del token OAuth 2.0 abbia fornito un endpoint della sessione finale:

  • Se il client API non è autenticato, il gateway API reindirizza la richiesta di logout all'URL successivo al logout.
  • Se il client API è stato autenticato, ma il criterio di autenticazione del token OAuth 2.0 non ha fornito un endpoint della sessione finale, il gateway API reindirizza la richiesta di logout all'URL successivo al logout e passa le informazioni sullo stato specificate nella definizione del back-end di logout.
  • Se il client API è stato autenticato e il criterio di autenticazione del token OAuth 2.0 ha fornito un endpoint della sessione finale, il gateway API reindirizza la richiesta di logout a tale endpoint della sessione finale e passa l'URL successivo al logout e qualsiasi informazione sullo stato specificata nella definizione del back-end di logout. In questo caso, è responsabilità del provider di identità reindirizzare la richiesta all'URL successivo al logout.

È possibile aggiungere un backend di logout a una specifica di distribuzione API effettuando le operazioni riportate di seguito.

  • utilizzo di Console
  • modifica di un file JSON

Utilizzo della console per aggiungere backend di logout a una specifica di distribuzione API

Per aggiungere back-end di logout a una specifica di distribuzione API utilizzando la console:

  1. Creare o aggiornare una distribuzione API utilizzando la console, selezionare l'opzione Da zero e immettere i dettagli nella pagina Informazioni di base.

    Per ulteriori informazioni, vedere Distribuzione di un'interfaccia API in un gateway API mediante la creazione di una distribuzione API e Aggiornamento di un gateway API o di una distribuzione API.

  2. Nella pagina Autenticazione specificare le opzioni di autenticazione.

    Per ulteriori informazioni sulle opzioni di autenticazione, vedere Aggiunta di autenticazione e autorizzazione alle distribuzioni API.

  3. Nella pagina Cicli creare un nuovo instradamento e specificare:

    • Percorso: un percorso per le chiamate API che utilizzano i metodi elencati per il servizio backend. Tenere presente che il percorso di instradamento specificato è il seguente:

    • Metodi: uno o più metodi accettati dal servizio backend. Nel caso di back-end di logout, è accettato solo GET.
    • Tipo backend: il tipo di servizio backend è Logout.
    • URI post logout consentiti: (facoltativo) lista di uno o più URL consentiti ai quali è possibile reindirizzare una richiesta di logout per revocare i token. Gli URL nella lista possono essere percorsi assoluti o percorsi relativi e gli URL possono includere variabili di contesto. Ad esempio, ["https://${request.header[tenant-id].page.html}", "https://fixed-path.page.html", "/logout_html"].

      Nota:

      • Un URL successivo al logout può essere incluso in una richiesta al back-end di logout come valore di un parametro di query denominato postLogoutUrl.
      • Se si specifica un percorso relativo (ovvero un altro instradamento nella distribuzione API), sia la distribuzione API che l'instradamento devono consentire l'accesso anonimo.
      • Se non si includono in modo esplicito uno o più URL nella lista, è consentito qualsiasi URL successivo al logout.
    • Stato successivo al logout: (facoltativo) dati da passare quando una richiesta di logout viene reindirizzata a un endpoint della sessione finale e/o a un URL successivo al logout. I dati possono includere solo variabili di contesto (non valori statici). Ad esempio, request.query[region]

      I dati vengono passati come valore del parametro di query state.

  4. (Facoltativo) Fare clic su Altro instradamento per immettere i dettagli degli instradamenti aggiuntivi.
  5. Fare clic su Successivo per esaminare i dettagli immessi per la distribuzione API.
  6. Fare clic su Crea o su Salva modifiche per creare o aggiornare la distribuzione API.
  7. (Facoltativo) Confermare che l'interfaccia API sia stata distribuita correttamente chiamandola (vedere Chiamata di un'interfaccia API distribuita in un gateway API).

Modifica di un file JSON per aggiungere backend di logout a una specifica di distribuzione API

Per aggiungere back-end di logout a una specifica di distribuzione API in un file JSON, effettuare le operazioni riportate di seguito. 

  1. Utilizzando l'editor JSON preferito, modificare la specifica di distribuzione API esistente alla quale si desidera aggiungere un backend di logout o creare una nuova specifica di distribuzione API (vedere Creazione di una specifica di distribuzione API).

    Ad esempio, la seguente specifica di distribuzione API di base definisce una semplice funzione serverless Hello World in Oracle Functions come un singolo backend:

    {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}

  2. Nella sezione routes, includere una nuova sezione per un back-end di logout:

    {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    },
    {
      "path": "<logout-route-path>",
      "methods": ["<method-list>"],
      "backend": {
        "type": "OAUTH2_LOGOUT",
        "allowedPostLogoutUris": ["<url>", "<url"],
        "postLogoutState": "<logout-data>"
      }
    }
  ]
}

    dove:

    • <logout-route-path> specifica un percorso per le chiamate che utilizzano i metodi elencati per il back-end di logout. Tenere presente che il percorso di instradamento specificato è il seguente:

    • <method-list> specifica uno o più metodi accettati dal back-end di logout, separati da virgole. Nel caso di back-end di logout, è accettato solo GET.
    • "type": "OAUTH2_LOGOUT" specifica che il backend è un backend di logout.

    • "allowedPostLogoutUris": ["<url>", "<url>"] specifica facoltativamente una lista di uno o più URL consentiti ai quali è possibile reindirizzare una richiesta di logout per revocare i token. Gli URL nella lista possono essere percorsi assoluti o percorsi relativi e gli URL possono includere variabili di contesto. Ad esempio, ["https://${request.header[tenant-id].page.html}", "https://fixed-path.page.html", "/logout_html"].

      Nota:

      • Un URL successivo al logout può essere incluso in una richiesta al back-end di logout come valore di un parametro di query denominato postLogoutUrl.
      • Se si specifica un percorso relativo (ovvero un altro instradamento nella distribuzione API), sia la distribuzione API che l'instradamento devono consentire l'accesso anonimo.
      • Se non si includono in modo esplicito uno o più URL nella lista, è consentito qualsiasi URL successivo al logout.

    • "postLogoutState": "<logout-data>" specifica facoltativamente i dati da passare quando una richiesta di logout viene reindirizzata a un endpoint della sessione finale e/o a un URL successivo al logout. I dati possono includere solo variabili di contesto (non valori statici). Ad esempio, request.query[region]

      I dati vengono passati come valore del parametro di query state.

    In questo esempio, una richiesta al backend /logout può includere uno degli URL specificati per allowedPostLogoutUris come valore del parametro di query postLogoutUrl. Quando viene richiamato l'URL successivo al logout, il valore della variabile di contesto request.query[region] viene passato all'URL. In questo esempio, uno dei valori allowedPostLogoutUris ("/logout_html") è un percorso relativo al back-end di risposta stock /logout_html nella stessa distribuzione API. Poiché si tratta di un percorso relativo a un altro instradamento nella stessa distribuzione API, il backend /logout_html deve includere un criterio di autorizzazione di tipo ANONYMOUS, come mostrato qui.

    {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    },
    {
      "path": "/logout",
      "methods": ["GET"],
      "backend": {
        "type": "OAUTH2_LOGOUT",
        "allowedPostLogoutUris": ["https://${request.header[tenant-id].page.html}", "/logout_html"],
        "postLogoutState": "request.query[region]"
      }
    },
    {
      "path": "/logout_html",
      "methods": ["GET"],
      "backend": {
        "type": "STOCK_RESPONSE_BACKEND",
        "body": "Token could not be revoked."
      },
      "requestPolicies": {
        "authorization": {
          "type": "ANONYMOUS"
        }
      }
    }
  ]
}
  3. Salvare il file JSON contenente la specifica di distribuzione API.

  4. Utilizzare la specifica di distribuzione API quando si crea o si aggiorna una distribuzione API nei modi riportati di seguito.

    • specificando il file JSON nella console quando si seleziona l'opzione Carica un'interfaccia API esistente
    • specificando il file JSON in una richiesta all'API REST del gateway API

    Per ulteriori informazioni, vedere Distribuzione di un'interfaccia API in un gateway API mediante la creazione di una distribuzione API e Aggiornamento di un gateway API o di una distribuzione API.

  5. (Facoltativo) Confermare che l'interfaccia API sia stata distribuita correttamente chiamandola (vedere Chiamata di un'interfaccia API distribuita in un gateway API).