Ricerca

InterAction+™ Integration Answer Center

Autorizzazione

  • Aggiornato

L’API Cloud di InterAction+™ utilizza OAuth 2.0 come framework di autorizzazione, consentendo alle applicazioni client di terze parti di accedere in modo sicuro ai dati utente di un tenant senza che gli utenti debbano condividere le proprie password. L’autorizzazione è gestita dal server di autorizzazione InterAction+™, che rilascia token di accesso e di aggiornamento sicuri per garantire un accesso controllato all’API Cloud di InterAction+™.

Flusso di autorizzazione OAuth 2.0

La nostra implementazione supporta il flusso Authorization Code Grant di OAuth 2.0, garantendo autenticazione e autorizzazione sicure per le interazioni tra sistemi. Questo flusso assicura che solo i client di terze parti autenticati e autorizzati possano interagire in modo sicuro con l’API Cloud di InterAction+™, mantenendo un controllo rigoroso sui permessi di accesso.

Partecipanti principali

  • Amministratore del tenant InterAction+™: Avvia il processo di autorizzazione per concedere a un client di terze parti l’accesso all’API Cloud di InterAction+™. Un amministratore deve fornire il consenso per l’accesso ai dati di InterAction+™, assicurando che l’accesso all’API sia concesso solo ai client di terze parti autorizzati. Inoltre, l’amministratore deve designare un singolo utente per le transazioni API. Si consiglia di creare e selezionare un utente di sistema dedicato, privo di dati personali, per questo scopo.
  • Client di terze parti: Richiede un token di accesso al server di autorizzazione InterAction+™ per interagire con l’API Cloud di InterAction+™ per conto del tenant. L’accesso viene concesso solo per gli ambiti richiesti e nei limiti della configurazione del client di terze parti.
  • Identity Provider (IdP) del tenant: Autentica l’amministratore del tenant InterAction+™ prima di rilasciare un codice di autorizzazione.
  • Server di autorizzazione InterAction+™: Rilascia i token di accesso e di aggiornamento dopo un’autorizzazione avvenuta con successo.

Fasi dell’autorizzazione

I passaggi descritti illustrano ogni singola richiesta effettuata al server di autorizzazione InterAction+™ durante il flusso Authorization Code Grant di OAuth 2.0. Sebbene questi dettagli offrano una comprensione più approfondita del processo, molti strumenti (ad esempio, Postman) e framework gestiscono automaticamente queste richieste. In questi casi, è sufficiente configurare l’URL di autorizzazione, l’URL del token di accesso e l’URL del token di aggiornamento per abilitare l’autenticazione e lo scambio dei token.

  1. L'amministratore del tenant InterAction+™ autorizza il client di terze parti: Per concedere a un client di terze parti l'accesso all'API Cloud di InterAction+™, l'amministratore del tenant InterAction+™ deve avviare il processo di configurazione dall'interfaccia del client di terze parti. Una volta avviato, il client di terze parti invia una richiesta all'endpoint di autorizzazione, invitando l'amministratore del tenant InterAction+™ a completare i seguenti passaggi prima di ottenere un codice di autorizzazione:
    • Autenticazione con Identity Provider (IdP): L'amministratore del tenant InterAction+™ deve accedere utilizzando le credenziali IdP della propria organizzazione per verificare la propria identità. Questo passaggio garantisce un'autenticazione sicura prima di concedere l'accesso.

    • Concedi il consenso per l'accesso del client di terze parti: Dopo l'autenticazione, l'amministratore del tenant InterAction+™ dovrà esaminare e approvare la richiesta del client di terze parti per accedere ai dati del tenant InterAction+™. 

    • Designare un utente API: L'amministratore del tenant InterAction+™ deve assegnare un utente specifico responsabile della gestione delle transazioni InterAction+™ Cloud API all'interno del tenant. L'amministratore del tenant InterAction+™ deve assegnare un utente specifico responsabile della gestione delle transazioni InterAction+™ Cloud API all'interno del tenant.

    • Endpoint:  

      GET {InterAction+™ Tenant Authority URL}/connect/authorize 

      Parametro 

      Descrizione 
      response_type=code  Richiede un codice di autorizzazione.
      client_id  L'identificativo univoco del client di terze parti.
      redirect_uri  L'URL di ritorno OAuth dove verrà inviato il codice di autorizzazione (registrato durante l'onboarding del client).
      scope  I permessi richiesti (ad esempio, openid offline_access public.contact.read).
      state  Un valore casuale per prevenire attacchi CSRF.

    • Ambiti: Gli ambiti definiscono il livello di accesso concesso al Client di terze parti. Il token di accesso all’API InterAction+™ Cloud emesso dal server di autorizzazione InterAction+™ include gli ambiti richiesti dal Client di terze parti nei limiti della sua configurazione.

      Ambito 

      Descrizione 
      openid  Abilita il supporto OpenID Connect, permettendo la verifica dell'identità.
      offline_access  Consente di richiedere un refresh token, così il client di terze parti può ottenere nuovi access token senza richiedere l'interazione dell'utente.
      public.activity.read  Leggi le attività
      public.activity.modify  Modifica le attività
      public.contact.read  Leggi i contatti e le informazioni correlate
      public.contact.modify  Modifica contatti e informazioni correlate
      public.list.read  Visualizza le liste
      public.list.modify  Modifica liste e informazioni correlate

    • Esempio di richiesta di autorizzazione:  

      {InterAction+™ Tenant Authority URL}/connect/authorize?response_type=code&client_id=third-party-client-id&redirect_uri=https://thirdpartyapp.com/oauth/callback&scope=openid offline_access public.contact.read&state=xyz123 
  2. Scambia il codice di autorizzazione per i token di accesso e refresh: Una volta ottenuto il codice di autorizzazione, il client di terze parti deve scambiarlo con un token di accesso e un token di refresh effettuando una richiesta all’endpoint dei token.

    • Endpoint del token:  

      POST {InterAction+™ Tenant Authority URL}/connect/token 

      Parametro 

      Descrizione 
      grant_type=authorization_code  Specifica il tipo di grant Authorization Code.
      code  Il codice di autorizzazione ricevuto dal passaggio precedente.
      redirect_uri  L'URL di ritorno OAuth dove verranno inviati i token (registrato durante l'onboarding del client).
      client_id  L'identificativo del client di terze parti.
      client_secret  Il segreto del client di terze parti.

    • Esempio di richiesta di scambio token:

      POST {InterAction+™ Tenant Authority URL}/connect/token
      Content-Type: application/x-www-form-urlencoded
      grant_type=authorization_code&client_id=third-party-client-
id&client_secret=third-party-client-
secret&code=AUTHORIZATION_CODE_FROM_STEP_1&redirect_uri=https://third-
party-app.com/oauth/callback

    • Esempio di risposta del token:

      {
    "id_token": "eyJhbGciOiJIUzI1NiIsInR...",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR...",
    "expires_in": 3600,
    "refresh_token": "def5020072b36c9b...",
    "token_type": "Bearer",
    "scope": "openid public.activity.read …”
}

      Token 

      Descrizione 
      id_token  JWT che contiene le informazioni di autenticazione dell’utente.
      access_token  Token JWT utilizzato per accedere all’API Cloud di InterAction+™.
      expires_in  Tempo di scadenza dell’Access Token (in secondi).
      refresh_token  Refresh Token utilizzato per richiedere un nuovo Access Token senza interazione dell’utente.
      token_type  Sempre Bearer, utilizzato negli header di autorizzazione.
      scope 
             		Il livello di accesso concesso al Cliente Terzo.
  3. Effettuare richieste API con il token di accesso: Una volta ottenuto il token di accesso, il client di terze parti lo include nell'intestazione Authorization delle richieste API. Questo meccanismo garantisce che solo gli utenti autenticati con un token di accesso JWT valido possano accedere all'API Cloud di InterAction+™.

    • Esempio di richiesta API: 

      POST {URL API Cloud di InterAction+™ }
      Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR...
      Body: Richiesta GraphQL
  4. Aggiornamento del token di accesso: Poiché i token di accesso hanno una durata limitata, il refresh token consente al client di terze parti di ottenere un nuovo token di accesso senza richiedere l'interazione dell'utente.

    • Endpoint del token:  

      POST {InterAction+™ Tenant Authority URL}/connect/token 

      Parametro 

      Descrizione 
      grant_type=refresh_token  Specifica il tipo di grant per ottenere il refresh token.
      refresh_token  Il Refresh Token ricevuto dal passaggio precedente.
      client_id  L'identificativo del client di terze parti.
      client_secret  Il segreto del client di terze parti.

  • Esempio di richiesta:

    POST {InterAction+™ Tenant Authority URL}/connect/token 
    Content-Type: application/x-www-form-urlencoded 
    grant_type=refresh_token&client_id=third-party-client-id&client_secret=third-party-client-secret&refresh_token=REFRESH_TOKEN 

  • Esempio di risposta con Refresh Token:

    { 
    "id_token": "nuovo_id_token_qui",
    "access_token": "nuovo_access_token_qui",
    "expires_in": 3600,
    "refresh_token": "nuovo_refresh_token_qui",
    "token_type": "Bearer"
     "scope": "openid public.activity.read …”
}

    Token 

    Description 
    id_token  JWT che contiene le informazioni di autenticazione dell'utente.
    access_token  Token JWT utilizzato per accedere all'API Cloud di InterAction+™.
    expires_in  Tempo di scadenza dell'Access Token (in secondi).
    refresh_token  Refresh Token utilizzato per richiedere un nuovo Access Token senza interazione dell'utente.
    token_type  Sempre Bearer, utilizzato nelle intestazioni Authorization.
    scope  Il livello di accesso concesso al client di terze parti.

Ciclo di vita dei token

  • Scadenza dell’Access Token: L’Access Token è valido per un’ora.
  • Scadenza del Refresh Token: Il Refresh Token è valido per 30 giorni. Se il Refresh Token scade, l’amministratore del tenant InterAction+™ deve riavviare il processo di autorizzazione per ottenere nuovi token.
  • Revoca dei token: L’amministratore del tenant InterAction+™ può revocare in qualsiasi momento gli access token per un client di terze parti, interrompendo immediatamente l’accesso API dall’amministrazione del tenant in CIM. Consulta il Client Insights Answer Center per ulteriori informazioni per utenti Hybrid o SaaS.

Utilizzo del Refresh Token

La nostra configurazione implementa refresh token monouso per garantire una gestione sicura dei token.

  • Quando un client di terze parti utilizza un refresh token per ottenere un nuovo access token, viene emessa una nuova coppia di access token e refresh token.
  • Il refresh token utilizzato in precedenza viene immediatamente revocato e non può più essere usato.

Se un client di terze parti invia un refresh token già utilizzato o sostituito da un token più recente, la richiesta non andrà a buon fine e restituirà un errore perché il token non è più valido o presente nel nostro archivio token.

Best practice

  • Dopo ogni refresh riuscito, sostituisci il refresh token memorizzato con quello nuovo e utilizza solo l’ultimo token ricevuto per le richieste di refresh future.
  • Non tentare di riutilizzare o tornare a refresh token precedenti.
  • Evita di inviare più richieste di refresh in parallelo, poiché la prima richiesta farà ruotare il token e le successive che utilizzano il vecchio token falliranno.
"Questo articolo di assistenza è stato tradotto con l’AI e potrebbe contenere inesattezze. Se hai dubbi su qualche informazione, consulta la versione originale in inglese."