4. Claim JSON Web Token e Parametri di Risposta Introspection

È utile disporre di meccanismi definiti per esprimere la delega all'interno di un token nonché per esprimere l'autorizzazione a delegare o impersonare. Sebbene il protocollo di scambio di token qui descritto possa essere utilizzato con qualsiasi tipo di token, questa sezione definisce i claim per esprimere tale semantica specificamente per i JWT e in una risposta OAuth 2.0 Token Introspection [RFC7662]. Definizioni simili per altri tipi di token sono possibili ma esulano dall'ambito di questa specifica.

Si noti che i claim non stabiliti qui ma utilizzati negli esempi e nelle descrizioni, come "iss", "sub", "exp", ecc., sono definiti da [JWT].

4.1. Claim "act" (Actor)

Il claim "act" (attore) fornisce un mezzo all'interno di un JWT per esprimere che è avvenuta una delega e identificare la parte agente a cui è stata delegata l'autorità. Il valore del claim "act" è un oggetto JSON e i membri nell'oggetto JSON sono claim che identificano l'attore. I claim che costituiscono il claim "act" identificano e possibilmente forniscono informazioni aggiuntive sull'attore. Ad esempio, la combinazione dei due claim "iss" e "sub" potrebbe essere necessaria per identificare in modo univoco un attore.

Tuttavia, i claim all'interno del claim "act" riguardano solo l'identità dell'attore e non sono rilevanti per la validità del JWT contenente allo stesso modo dei claim di primo livello. Di conseguenza, i claim non di identità (ad esempio, "exp", "nbf" e "aud") non sono significativi se utilizzati all'interno di un claim "act" e pertanto non vengono utilizzati.

La Figura 5 illustra il claim "act" (attore) all'interno di un JWT Claims Set. I claim del token stesso riguardano [email protected] mentre il claim "act" indica che [email protected] è l'attore corrente.

{
  "aud":"https://consumer.example.com",
  "iss":"https://issuer.example.com",
  "exp":1443904177,
  "nbf":1443904077,
  "sub":"[email protected]",
  "act":
  {
    "sub":"[email protected]"
  }
}

Figura 5: Claim Actor

Una catena di delega può essere espressa nidificando un claim "act" all'interno di un altro. Il claim "act" più esterno rappresenta l'attore corrente mentre i claim "act" nidificati rappresentano gli attori precedenti. L'attore meno recente è il più profondamente nidificato. I claim "act" nidificati servono come una traccia storica che collega la richiesta iniziale e il soggetto attraverso i vari passaggi di delega intrapresi prima di raggiungere l'attore corrente. In questo senso, l'attore corrente è considerato includere l'intera cronologia di autorizzazione/delega, portando naturalmente alla struttura nidificata descritta qui.

Ai fini dell'applicazione della politica di controllo degli accessi, il consumatore di un token DEVE considerare solo i claim di primo livello del token e la parte identificata come attore corrente dal claim "act". Gli attori precedenti identificati da qualsiasi claim "act" nidificato sono solo informativi e non devono essere presi in considerazione nelle decisioni di controllo degli accessi.

Il seguente esempio nella Figura 6 illustra i claim "act" (attore) nidificati all'interno di un JWT Claims Set. I claim del token stesso riguardano [email protected] mentre il claim "act" indica che il sistema <https://service16.example.com> è l'attore corrente e <https://service77.example.com> era un attore precedente. Tale token potrebbe derivare dal fatto che service16 riceve un token in una chiamata da service77 e lo scambia con un token adatto per chiamare service26 mentre il server di autorizzazione nota la situazione nel token appena emesso.

{
  "aud":"https://service26.example.com",
  "iss":"https://issuer.example.com",
  "exp":1443904100,
  "nbf":1443904000,
  "sub":"[email protected]",
  "act":
  {
    "sub":"https://service16.example.com",
    "act":
    {
      "sub":"https://service77.example.com"
    }
  }
}

Figura 6: Claim Actor Nidificato

Quando incluso come membro di primo livello di una risposta di introspezione token OAuth, "act" ha la stessa semantica e formato del claim con lo stesso nome.

4.2. Claim "scope" (Scopes)

Il valore del claim "scope" è una stringa JSON contenente un elenco separato da spazi di ambiti associati al token, nel formato descritto nella Sezione 3.3 della [RFC6749].

La Figura 7 illustra il claim "scope" all'interno di un JWT Claims Set.

{
  "aud":"https://consumer.example.com",
  "iss":"https://issuer.example.com",
  "exp":1443904177,
  "nbf":1443904077,
  "sub":"dgaf4mvfs75Fci_FL3heQA",
  "scope":"email profile phone address"
}

Figura 7: Claim Scopes

OAuth 2.0 Token Introspection [RFC7662] definisce già il parametro "scope" per trasmettere gli ambiti associati al token.

4.3. Claim "client_id" (Client Identifier)

Il claim "client_id" trasporta l'identificatore client del client OAuth 2.0 [RFC6749] che ha richiesto il token.

Il seguente esempio nella Figura 8 illustra il claim "client_id" all'interno di un JWT Claims Set che indica un client OAuth 2.0 con "s6BhdRkqt3" come identificatore.

{
  "aud":"https://consumer.example.com",
  "iss":"https://issuer.example.com",
  "exp":1443904177,
  "sub":"[email protected]",
  "client_id":"s6BhdRkqt3"
}

Figura 8: Claim Client Identifier

OAuth 2.0 Token Introspection [RFC7662] definisce già il parametro "client_id" come identificatore client per il client OAuth 2.0 che ha richiesto il token.

4.4. Claim "may_act" (Authorized Actor)

Il claim "may_act" dichiara che una parte è autorizzata a diventare l'attore e ad agire per conto di un'altra parte. Il claim potrebbe essere utilizzato, ad esempio, quando un "subject_token" viene presentato all'endpoint del token in una richiesta di scambio di token e il claim "may_act" nel subject token può essere utilizzato dal server di autorizzazione per determinare se il client (o la parte identificata nell'"actor_token") è autorizzato a impegnarsi nella delega o nell'impersonificazione richiesta.

Il valore del claim è un oggetto JSON e i membri nell'oggetto JSON sono claim che identificano la parte che si afferma essere idonea ad agire per la parte identificata dal JWT contenente il claim. I claim che costituiscono il claim "may_act" identificano e possibilmente forniscono informazioni aggiuntive sull'attore autorizzato. Ad esempio, la combinazione dei due claim "iss" e "sub" è talvolta necessaria per identificare in modo univoco un attore autorizzato, mentre il claim "email" potrebbe essere utilizzato per fornire ulteriori informazioni utili su quella parte.

Tuttavia, i claim all'interno del claim "may_act" riguardano solo l'identità di quella parte e non sono rilevanti per la validità del JWT contenente allo stesso modo dei claim di primo livello. Di conseguenza, i claim come "exp", "nbf" e "aud" non sono significativi se utilizzati all'interno di un claim "may_act" e pertanto non vengono utilizzati.

La Figura 9 illustra il claim "may_act" all'interno di un JWT Claims Set. I claim del token stesso riguardano [email protected] mentre il claim "may_act" indica che [email protected] è autorizzato ad agire per conto di [email protected].

{
  "aud":"https://consumer.example.com",
  "iss":"https://issuer.example.com",
  "exp":1443904177,
  "nbf":1443904077,
  "sub":"[email protected]",
  "may_act":
  {
    "sub":"[email protected]"
  }
}

Figura 9: Claim Authorized Actor

Quando incluso come membro di primo livello di una risposta di introspezione token OAuth, "may_act" ha la stessa semantica e formato del claim con lo stesso nome.