.. _idmEsterno_oauth:

Integrazione delle Console con un Authorization Server tramite OIDC/OAuth
--------------------------------------------------------------------------

La presente sezione fornisce i dettagli necessari alla configurazione delle console per l’integrazione con un authorization server conforme agli standard OpenID Connect (OIDC) e OAuth 2.0.

Come riferimento viene utilizzato l’authorization server `Keycloak <https://www.keycloak.org/>`_.

**Configurazione di esempio (scenario demo)**

Per un rapido scenario dimostrativo, Keycloak è stato configurato come segue:

- Creazione di un realm denominato 'GovWay'.
- Creazione di un client con client_id e name impostati a 'govway_console', associato all’Authentication Standard Flow, per implementare l’Authorization Code Flow previsto dallo standard OpenID Connect. Sono state definite come valid redirect URIs le seguenti URL:

    - http://127.0.0.1:8080/govwayConsole/oauth2/callback
    - http://127.0.0.1:8080/govwayConsole/login.do*
- Creazione di un secondo client con client_id e name impostati a 'govway_monitor', anch’esso configurato con lo Standard Flow. Sono state definite come valid redirect URIs le seguenti URL:

    - http://127.0.0.1:8080/govwayMonitor/oauth2/callback
    - http://127.0.0.1:8080/govwayMonitor/public/*
- Creazione di due utenze applicative utilizzate come utenze di default per le console:

    - amministratore
    - operatore

- Creazione delle ulteriori utenze applicative i cui username devono corrispondere a quelli registrati nella console di gestione.


**Configurazione lato Console**

Per abilitare l’autenticazione tramite Keycloak è necessario intervenire sui seguenti file di configurazione:

- Console di gestione (govwayConsole): *<directory-lavoro>/console_local.properties*;
- Console di monitoraggio (govwayMonitor): *<directory-lavoro>/monitor_local.properties*

1. Disabilitazione dell’autenticazione locale:

     ::

        login.application=false

2. Definizione della modalità di accesso all’identità autenticata tramite Keycloak:

     ::

        login.tipo=oauth2

3. Configurazione delle URL di Keycloak per la negoziazione dei token:

     ::

        # Url di autenticazione
        login.props.oauth2.authorization.endpoint=https://localhost:8543/realms/GovWay/protocol/openid-connect/auth
        # Url dove richiedere il token
        login.props.oauth2.token.endpoint=https://localhost:8543/realms/GovWay/protocol/openid-connect/token
        # Url dove scaricare le indormazioni utente
        login.props.oauth2.userInfo.endpoint=https://localhost:8543/realms/GovWay/protocol/openid-connect/userinfo
        # URL di validazione dei certificati JWT
        login.props.oauth2.jwks.endpoint=https://localhost:8543/realms/GovWay/protocol/openid-connect/certs
        # URL del servizio logout federato
        login.props.oauth2.logout.endpoint=https://localhost:8543/realms/GovWay/protocol/openid-connect/logout

   .. note::
      L'endpoint 'login.props.oauth2.userInfo.endpoint' è richiesto solo se il principal viene letto dall'endpoint */userinfo* (impostazione di default 'login.props.oauth2.userInfo.source=userinfo'). Qualora il principal venga invece estratto direttamente dal token JWT (modalità 'id_token' o 'access_token', vedi punto 6), tale endpoint non viene utilizzato e può essere omesso.

4. Impostazione del Client ID e della Redirect URI (/oauth2/callback). Per la console di gestione (govway_console):

     ::

        # Client ID rilasciato dal server OAuth2
        login.props.oauth2.clientId=govway_console
        # URL dove viene rediretto l'utente dopo l'autenticazione
        login.props.oauth2.redirectUri=http://127.0.0.1:8080/govwayConsole/oauth2/callback        

   Per la console di monitoraggio (govway_monitor):

     ::

        # Client ID rilasciato dal server OAuth2
        login.props.oauth2.clientId=govway_monitor
        # URL dove viene rediretto l'utente dopo l'autenticazione
        login.props.oauth2.redirectUri=http://127.0.0.1:8080/govwayMonitor/oauth2/callback

5. Definizione dello Scope e del Claim contenente lo username:

     ::

        # Scope dell'autenticazione
        login.props.oauth2.scope=openid
        # Nome del claim da dove leggere il principal
        login.props.oauth2.principalClaim=preferred_username

6. Sorgente da cui leggere il principal (opzionale). Per default il claim contenente il principal (definito in 'login.props.oauth2.principalClaim') viene ricercato nella risposta dell'endpoint */userinfo* dell'authorization server (proprietà 'login.props.oauth2.userInfo.endpoint'). È possibile modificare tale comportamento tramite la proprietà 'login.props.oauth2.userInfo.source', che accetta i seguenti valori:

   - **userinfo** (default): il principal viene ricercato nella risposta dell'endpoint */userinfo*, recuperata tramite chiamata HTTP;
   - **id_token**: il principal viene ricercato nel payload del JWT 'id_token' restituito dall'authorization server, senza alcuna chiamata HTTP aggiuntiva;
   - **access_token**: il principal viene ricercato nel payload del JWT 'access_token', senza alcuna chiamata HTTP aggiuntiva.

     ::

        # Sorgente da cui leggere il principal dell'utente loggato.
        # Valori ammessi: userinfo (default), id_token, access_token
        login.props.oauth2.userInfo.source=userinfo

   .. note::
      Le modalità **id_token** e **access_token** sono utili nei casi in cui l'endpoint */userinfo* non sia disponibile oppure non restituisca il claim da utilizzare come principal dell'utente.

7. Validazione opzionale dei claim nel token. È possibile abilitare controlli aggiuntivi sui claim presenti nel token:

     ::

        # Validazione dei claim del token
        # Inserire una riga per ogni claim da validare nella forma: login.props.oauth2.claims.validation.claimName=claimValues (lista di valori separati da virgola)
        #login.props.oauth2.claims.validation.claimName=claimValue1,claimValue2,...
        login.props.oauth2.claims.validation.iss=https://localhost:8543/realms/GovWay
        login.props.oauth2.claims.validation.aud=account

   È possibile validare anche claim annidati all'interno di oggetti JSON, utilizzando la notazione con il punto per navigare la struttura. Ad esempio, dato un token contenente:

     ::

        {
          ...
          "realm_access": {
            "roles": ["offline_access", "default-roles-govway", "uma_authorization"]
          },
          "resource_access": {
            "account": {
              "roles": ["manage-account", "manage-account-links", "view-profile"]
            }
          }
        }

   Per i claim il cui valore è un array, il confronto esatto potrebbe non essere sufficiente. È possibile utilizzare un prefisso speciale nel valore della proprietà per attivare una logica di confronto basata sugli elementi dell'array:

   - **[or]** oppure **[]**: almeno uno dei valori indicati deve essere presente nell'array del claim (logica OR);
   - **[and]**: tutti i valori indicati devono essere presenti nell'array del claim (logica AND).

   Esempio:

     ::

        # Verifica che il claim 'realm_access.roles' contenga almeno uno tra i valori indicati (OR)
        login.props.oauth2.claims.validation.realm_access.roles=[]offline_access,default-roles-govway

        # Verifica che il claim 'resource_access.account.roles' contenga tutti i valori indicati (AND)
        login.props.oauth2.claims.validation.resource_access.account.roles=[and]manage-account,manage-account-links

8. Parametri di connessione verso Keycloak:

     ::

        # Parametri timeout connessione verso il server OAuth2
        #login.props.oauth2.readTimeout=15000
        #login.props.oauth2.connectTimeout=10000

        # Truststore https
        #login.props.oauth2.https.hostnameVerifier=true
        #login.props.oauth2.https.trustAllCerts=false
        #login.props.oauth2.https.trustStore=PATH
        #login.props.oauth2.https.trustStore.password=changeme
        #login.props.oauth2.https.trustStore.type=jks
        #login.props.oauth2.https.trustStore.crl=PATH

        # Keystore https
        #login.props.oauth2.https.keyStore=PATH
        #login.props.oauth2.https.keyStore.password=changeme
        #login.props.oauth2.https.keyStore.type=jks
        #login.props.oauth2.https.key.alias=mykey
        #login.props.oauth2.https.key.password=changeme

9. Abilitazione di PKCE (Proof Key for Code Exchange) per maggiore sicurezza. PKCE è un'estensione di OAuth 2.0 (RFC 7636) che migliora la sicurezza del flusso Authorization Code, particolarmente raccomandata per client pubblici e applicazioni web:

     ::

        # Abilita PKCE (Proof Key for Code Exchange) - RFC 7636
        login.props.oauth2.pkce.enabled=true

        # Metodo PKCE da utilizzare (valori: S256, plain)
        # - S256: usa SHA-256 hash del code_verifier (RACCOMANDATO, default)
        # - plain: usa il code_verifier direttamente (solo se il server non supporta S256)
        login.props.oauth2.pkce.method=S256

   .. note::
      **PKCE** protegge contro attacchi di intercettazione del codice di autorizzazione. Il metodo **S256** (default) è raccomandato in quanto più sicuro. Il metodo **plain** dovrebbe essere usato solo se l'authorization server non supporta SHA-256.

10. Abilitazione del log di debug (opzionale). Per facilitare la diagnosi della configurazione in fase di set-up è possibile abilitare la produzione di log di debug aggiuntivi nei vari punti del flusso OAuth2/OIDC (token ricevuto dall'authorization server, informazioni utente prelevate dalla sorgente configurata, ecc.):

     ::

        # Abilita i log di debug della libreria OAuth2/OIDC (default: false)
        login.props.oauth2.debug=true

    .. warning::
       Il log di debug può contenere token di sessione e claim con informazioni personali sensibili. Si raccomanda di non abilitarlo in ambienti di produzione.