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.

Configurazione di esempio (scenario demo)

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

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

    Nota

    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

    Nota

    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

    Nota

    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

    Avvertimento

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