API OAuth 2.0 Avanzato

Auris fornisce implementazioni delle specifiche OAuth 2.0 e OIDC avanzate per scenari enterprise. Queste funzionalità includono il Device Authorization Flow per dispositivi senza browser, il Token Exchange per impersonation e delegation, i token DPoP (Demonstrating Proof of Possession) vincolati al mittente, l’autenticazione CIBA (Client-Initiated Backchannel Authentication) e la valutazione del rischio con MFA adattivo.

Tutte le funzionalità avanzate OAuth 2.0 devono essere abilitate per ogni applicazione nella Console di Auris (Console > Applicazioni > [Nome App] > OAuth Avanzato) prima di poter essere usate.

Device Authorization Flow (RFC 8628)

Il Device Authorization Flow consente ai dispositivi con capacità di input limitate (smart TV, terminali CLI, apparecchi IoT) di ottenere token OAuth 2.0. Il dispositivo mostra un codice utente corto e un URL; l’utente completa l’autenticazione su un dispositivo separato.

Corpo della richiesta

{
  "client_id": "app_abc123",
  "scope": "openid profile email"
}

Risposta di successo

{
  "ok": true,
  "data": {
    "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
    "user_code": "WDJB-MJHT",
    "verification_uri": "https://api.altovar.net/hosted/device",
    "verification_uri_complete": "https://api.altovar.net/hosted/device?user_code=WDJB-MJHT",
    "expires_in": 1800,
    "interval": 5
  }
}

Codici di errore

Polling per il Token

Una volta mostrato il user_code all’utente, il dispositivo deve fare polling sull’endpoint token finché l’utente autorizza la richiesta, il codice scade o l’utente nega l’accesso.

{
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "client_id": "app_abc123"
}

Token Exchange (RFC 8693)

Il Token Exchange consente a un servizio di ottenere token agendo come un altro utente (impersonation) o per conto di un altro utente (delegation). Entrambi richiedono permessi espliciti e generano voci di audit log complete.

Impersonation

Il servizio richiedente agisce completamente come l’utente target. Il token risultante ha come sub l’ID dell’utente target. Tutti gli eventi di audit mostrano l’impersonation.

{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "eyJhbGciOiJSUzI1NiJ9...",
  "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "exchange_type": "impersonation",
  "target_user_id": "usr_target123"
}

Risposta — token standard con "sub": "usr_target123"

Delegation

Il servizio richiedente agisce per conto dell’utente originale. Il soggetto originale è preservato nel token. Il claim act identifica il principale che sta agendo.

{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "eyJhbGciOiJSUzI1NiJ9...",
  "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "exchange_type": "delegation"
}

Payload JWT risultante

{
  "sub": "usr_original123",
  "act": {
    "sub": "usr_acting_service456"
  },
  "scope": "read:data"
}

Campi della richiesta

Codici di errore

DPoP — Demonstrating Proof of Possession (RFC 9449)

I token DPoP sono crittograficamente vincolati al client che li ha ottenuti. A differenza dei token Bearer standard, i token DPoP non possono essere usati da un attaccante che li intercetta perché le chiamate API richiedono una prova JWT fresca firmata con la chiave privata del client.

Come Funziona il DPoP

1. Generazione delle chiavi: Il client genera una coppia di chiavi a curva ellittica (EC P-256 o RSA). La chiave privata non lascia mai il client.
2. Creazione della prova: Per ogni richiesta, il client crea un JWT di prova DPoP firmato con la chiave privata, includendo il metodo HTTP, l’URL e un jti univoco.
3. Binding del token: Il server valida la prova, estrae il thumbprint JWK e vincola il token emesso a quella chiave pubblica.
4. Chiamate API: Le chiamate API successive richiedono sia il token DPoP che una nuova prova DPoP fresca per quella specifica richiesta.

Struttura della Prova DPoP

DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik...

Il JWT di prova DPoP ha la seguente struttura:

Header

{
  "typ": "dpop+jwt",
  "alg": "ES256",
  "jwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
    "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
  }
}

Payload

{
  "htm": "POST",
  "htu": "https://api.altovar.net/api/auth/token",
  "iat": 1707300000,
  "jti": "unique-id-per-request-abc123",
  "nonce": "server-provided-nonce"
}

Token DPoP nella Risposta

Quando si ottiene un token usando DPoP, la risposta include "token_type": "DPoP" anziché "Bearer". Il JWT del token di accesso contiene un claim cnf.jkt con il JWK thumbprint:

{
  "sub": "usr_abc123",
  "cnf": {
    "jkt": "0ZcOCORZNYy-DWpqq30jZyJGHTN0d2HglBV3uiguA4I"
  }
}

Per usare un token DPoP, includi l’intestazione Authorization: DPoP <token> insieme a un’intestazione DPoP: <fresh-proof>.

Gestione del Nonce

Il server può richiedere un nonce per prevenire replay. Includi il nonce nelle prove DPoP successive:

DPoP-Nonce: eyJ...server-issued-nonce...

Questo nonce deve essere incluso nel claim nonce del tuo prossimo JWT di prova DPoP. Se invii una prova senza nonce quando è richiesto, riceverai un errore use_dpop_nonce con un nonce fresco nell’intestazione della risposta.

Codici di errore

CIBA — Autenticazione Backchannel (Client-Initiated Backchannel Authentication)

CIBA consente a un servizio di avviare un’autenticazione in background su un dispositivo o canale separato (come una notifica push su mobile) senza reindirizzare il browser. Utile per call center, autenticazione a distanza e app su dispositivi separati.

Corpo della richiesta

{
  "client_id": "app_abc123",
  "client_secret": "app_secret_xyz",
  "scope": "openid profile",
  "login_hint": "[email protected]",
  "binding_message": "Autorizza pagamento $50 a Jane",
  "requested_expiry": 300
}

Risposta di successo

{
  "ok": true,
  "data": {
    "auth_req_id": "1c266114-a1be-4252-8ad1-04986c5b9ac9",
    "expires_in": 300,
    "interval": 5
  }
}

Modi di Notifica

Il modo in cui il tuo servizio riceve il risultato dell’autenticazione dipende dalla modalità CIBA configurata per l’applicazione:

Polling CIBA

Per la modalità poll, esegui polling sull’endpoint token:

{
  "grant_type": "urn:openid:params:grant-type:ciba",
  "auth_req_id": "1c266114-a1be-4252-8ad1-04986c5b9ac9",
  "client_id": "app_abc123",
  "client_secret": "app_secret_xyz"
}

Le risposte di polling funzionano allo stesso modo del Device Flow: AUTHORIZATION_PENDING, SLOW_DOWN, EXPIRED_TOKEN, ACCESS_DENIED, o un token di successo.

Codici di errore

Valutazione del Rischio e MFA Adattivo

Auris valuta il rischio di ogni evento di autenticazione in tempo reale. Sulla base del punteggio di rischio, può consentire il login, richiedere un passaggio MFA aggiuntivo, o bloccare completamente il tentativo di autenticazione.

Fattori di Rischio

Ogni fattore contribuisce per il 20% al punteggio di rischio complessivo:

Livelli di Rischio

Claim JWT ACR e AMR

I token Auris includono claim standard OIDC che descrivono come l’utente si è autenticato:

Claim acr (Authentication Context Class Reference)

Claim amr (Authentication Methods References)

Array di metodi usati durante l’autenticazione: pwd, otp, sms, webauthn, social, magic_link, sso

{
  "sub": "usr_abc123",
  "acr": "urn:auris:acr:mfa",
  "amr": ["pwd", "otp"]
}

API Valutazione del Rischio

Parametri query

Risposta di esempio

{
  "ok": true,
  "data": [
    {
      "id": "risk_abc123",
      "userId": "usr_xyz789",
      "score": 72,
      "level": "HIGH",
      "factors": {
        "ipReputation": 20,
        "deviceTrust": 0,
        "geoAnomaly": 20,
        "behavior": 12,
        "actionSensitivity": 20
      },
      "actionTaken": "step_up_mfa",
      "ipAddress": "203.0.113.42",
      "country": "IT",
      "city": "Milano",
      "createdAt": "2025-02-18T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "pages": 8
  }
}

Regole di Rischio Personalizzate

Puoi estendere il motore di valutazione del rischio con regole custom che sovrascrivono o aumentano il comportamento predefinito.

Corpo della richiesta

{
  "name": "Blocca accessi da proxy noti",
  "condition": {
    "field": "ipReputation.isProxy",
    "operator": "equals",
    "value": true
  },
  "action": "block",
  "scoreModifier": 50,
  "isActive": true
}

Campi condizione disponibili

Operatori disponibili

equals, not_equals, greater_than, less_than, contains, in

Riferimento Permessi

Correlati

• Concetto DPoP — Come funziona il binding della chiave DPoP
• Concetto Device Flow — Device Authorization Flow spiegato
• Concetto CIBA — Autenticazione backchannel
• Concetto Token Exchange — Impersonation e delegation
• Uso di DPoP — Implementazione dei token DPoP
• Device Flow — Guida al Device Flow
• CIBA — Configurazione dell’autenticazione backchannel
• Token Exchange — Guida all’exchange dei token
• OAuth Avanzato Admin — Configurazione dalla Console