FAQ - HYPERPLANNING

  • Come posso configurare l'applicazione per ottenere l'autorizzazione ad inviare e-mail tramite il protocollo OAuth?

    Presentazione generale

    Il protocollo OAuth evita di dare a un'applicazione un identificativo e una password che le permetterebbe di fare qualsiasi cosa quando accede a un servizio, ma concede solo le autorizzazioni necessarie per fare quello che deve fare.
    Tali autorizzazioni sono concesse sotto forma di due "token":

    • un token di accesso (access token), valido per un periodo molto breve, di solito un'ora,
    • un token di aggiornamento (refresh token), valido per un periodo molto più lungo e che permette di rinnovare il token di accesso senza dover chiedere continuamente un intervento dell'utente.

    Per ottenere i token, l'utente è invitato ad autenticarsi in un browser web separato dall'applicazione (in modo che quest'ultima non intercetti le credenziali).
    Questa fase di autenticazione è gestita interamente dal servizio e non dall'applicazione.
    Potrebbe essere un'autenticazione a più fattori, ad esempio con un codice di verifica inviato tramite SMS o e-mail.
    Solo una volta che l'utente è autenticato e ha dato il suo consenso alle autorizzazioni richieste, i token vengono comunicati all'applicazione.

    L'utente può in qualsiasi momento riconnettersi direttamente al proprio servizio per consultare o invalidare le autorizzazioni già concesse.
    Tutto per evitare che identificativo e password siano compromessi.


    Identificazione dell'applicazione presso il servizio
    I servizi concedono autorizzazioni solo ad applicazioni conosciute. Occorre quindi una dichiarazione preliminare che permetta di ottenere:
    • un identificativo (client ID) per identificare l'applicazione,
    • un segreto (client secret) che deve essere nascosto e che evita che un'applicazione si faccia passare per un'altra.

    faq-hyperplanning-795-0-6604.jpg

    Per il server SMTP di Microsoft smtp.office365.com, vi viene proposto di utilizzare un'applicazione predefinita di Index Education. Non dovrete quindi occuparvi di questa fase.
    In caso contrario, è necessario dichiarare l'applicazione per ottenere un identificativo e un segreto. In questo documento è possibile consultare queste due sezioni:
    • Dichiarare l'applicazione a un servizio Google;
    • Dichiarare l'applicazione a un servizio Microsoft.

    Parametro importante: le applicazioni Index Éducation utilizzano come URI di reindirizzamento https://execonnect.index-education.com/callback


    Identificazione del servizio dell'applicazione

    L'applicazione ha bisogno di più URL chiamate endpoint per avviare gli scambi con il servizio. È possibile ottenere questi endpoint nell'interfaccia in cui è stata dichiarata l'applicazione.

    Nel caso dell'applicazione predefinita di Index Éducation, questi endpoint sono precompilati.


    Dichiarare l'applicazione a un servizio Google

    Côté service

    Per iniziare, dovete connettervi all'indirizzo https://console.cloud.google.com/home/dashboard, poi cliccate a sinistra su API e servizi.

    1. Crea un nuovo progetto, dategli un nome (senza caratteri accentati) e assicuratevi che il nuovo progetto sia selezionato. Questo nome non è quello che vedrà l'utente.
    2. Poi cliccate a sinistra su Libreria e cliccate su Gmail API. Abilitate le API Gmail.
    3. In alto a sinistra, cliccate sul menu di navigazione (menu burger) e ritornate su API e servizi.
    4. Poi cliccate a sinistra la voce Schermata consenso OAuth e completate le informazioni.
    5. Nella seconda schermata Ambiti, cliccate sul tasto AGGIUNGI O RIMUOVI AMBITI. Sotto Aggiungi ambiti manualmente, incollate https://mail.google.com/, cliccate su AGGIUNGI ALLA TABELLA, poi su AGGIORNA.
    6. Alla domanda Quali funzionalità utilizzerai?, scegliete Client di posta.
    7. Terminate la configurazione.
    8. Cliccate poi a sinistra su Credenziali, poi su + CREA CREDENZIALI, ID client OAuth.
      • Tipo di applicazione : applicazione Web
      • Nome : execonnect.index-education.com
      • URI di reindirizzamento autorizzati : https://execonnect.index-education.com/callback
    9. Viene visualizzata una finestra con un identificativo e un segreto: entrambi i parametri devono essere conservati per essere inseriti nell'applicazione.


    Lato applicazione

    Nell'applicazione, inserite gli elementi seguenti:
    • Identificativo, Segreto: incollate qui i valori salvati precedentemente
    • Endpoint dell'autorizzazione : https://accounts.google.com/o/oauth2/v2/auth?prompt=consent&access_type=offline
    • Endpoint del token : https://oauth2.googleapis.com/token
    • Autorizzazioni richieste : https://mail.google.com/

    È quindi possibile richiedere dei token OAuth.

    Note:
    - I parametri prompt=consent&access_type=offline sono necessari per ottenere un token di accesso e un token di aggiornamento.
    - L'autorizzazione https://www.googleapis.com/auth/gmail.send (Invia e-mail a tuo nome) non è sufficiente per inviare un'e-mail tramite un server SMTP, necessita https://mail.google.com/ (accesso completo alla casella di posta). Vedi OAuth 2.0 Mechanism


    Dichiarare l'applicazione a un servizio Microsoft

    Lato servizio

    Per iniziare, dovete connettervi all'indirizzo https://portal.azure.com/, poi cliccate su Azure Active Directory.

    1. Cliccate a sinistra su Registrazioni app, poi in alto su + Nuova registrazione. Scegliete in base ai vostri bisogni i tipi di account da prendere in carico, poi nella sezione URI di reindirizzamento, scegliete Client pubblico/nativo (per dispositivi mobili e desktop) con l'URI https://execonnect.index-education.com/callback.
    2. Una volta registrata l'applicazione, cliccate a sinistra su Personalizzazione e proprietà, completate i campi e cliccate su Salva.
    3. Cliccate a sinistra su Autenticazione, poi in basso su
      Consenti i flussi client pubblici
      , spuntate . Cliccate su Salva.
    4. Cliccate a sinistra su Autorizzazioni API, poi su + Aggiungi un'autorizzazione, Microsoft Graph, Autorizzazioni delegate. Sotto User, togliete la spunta a User.Read, poi sotto SMTP, spuntate SMTP.Send. Cliccate poi su Aggiungi autorizzazioni.
    5. Cliccate a sinistra su Panoramica.
    6. Copiate il valore accanto a ID applicazione (client), e conservatelo per l'inserimento nell'applicazione.
    7. Cliccate in alto su Endpoint e copiate i primi due valori, Endpoint di autorizzazione OAuth 2.0 (v2) et Endpoint di token OAuth 2.0 (v2) per l'inserimento nell'applicazione.


    Lato applicazione

    Nell'applicazione, inserite gli elementi seguenti:
    • Identificativo: incollate qui il primo valore conservato precedentemente
    • Segreto: lasciate questo campo vuoto, le applicazioni pubbliche sono autorizzate
    • Endpoint di autorizzazione e dei token: incollate gli altri due valori conservati precedentemente
    • Autorizzazioni richieste : https://outlook.office.com/SMTP.Send offline_access

    È quindi possibile richiedere dei token OAuth.

    Note:
    - L'autorizzazione https://outlook.office.com/SMTP.Send è diversa da quella dichiarata nell'applicazione (SMTP.Send di Microsoft Graph), ma solo un token ottenuto con l'autorizzazione https://outlook.office.com/SMTP.Send consente di inviare un'e-mail tramite un server SMTP. Vedi Authenticate an IMAP, POP or SMTP connection using OAuth
    - L'autorizzazione offline_access è necessaria per ottenere un token di accesso e un token di aggiornamento.


    Utilizzo del protocollo OAuth per dispositivi con vincoli di input

    Esiste una variante del protocollo OAuth che permette ai dispositivi con vincoli di input (ad esempio una smart tv) di richiedere un token OAuth, si tratta di Device Authorization Grant. Se si verificano problemi con lo scenario OAuth predefinito, è possibile utilizzare questa variante del protocollo, funziona anche per le applicazioni su computer.

    Nell'applicazione, tenete premuti i tasti Ctrl e Maiusc (Shift) quando cliccate sul tasto per entrare nella finestra Configurazione OAuth: questo vi permette di selezionare lo scenario Device Authorization Grant. In questo scenario, l'endpoint di autorizzazione è sostituito da un endpoint del dispositivo.

    Attenzione, questo non funziona con i servizi Google perché non si può chiedere l'autorizzazione https://mail.google.com/. Vedi Ambiti consentiti

    Tuttavia, funziona con i servizi di Microsoft.
    Bisogna solo sapere che l'endpoint del dispositivo si deduce dall'endpoint di autorizzazione cambiando alla fine authorize con devicecode :
    • https://login.microsoftonline.com/common/oauth2/v2.0/authorize diventa https://login.microsoftonline.com/common/oauth2/v2.0/devicecode
    • https://login.microsoftonline.com/{xxx}/oauth2/v2.0/authorize diventa https://login.microsoftonline.com/{xxx}/oauth2/v2.0/devicecode