15.10 Applicazioni esterne

Questa funzione di vtenext, che si trova in Impostazioni > Applicazioni esterne, permette a servizi esterni di accedere ai dati del crm usando OAuth2 come protocollo di autorizzazione.

Schermata di configurazione per le Applicazioni esterne

Quindi come funziona esattamente? I servizi esterni, che in questo ambito chiamiamo applicazioni esterne, per collegarsi a vtenext tramite REST API, hanno prima bisogno di ottenere un access_token, che viene fornito tramite uno dei flussi messi a disposizione dal protocollo OAuth2. Vediamo una immagine esplicativa:

Questo flusso raffigurato, è denominato Client Credentials. Ci sono tre parti coinvolte:

Applicazione (per esempio un Gestionale)
Il Server di Autorizzazione (nel caso di vtenext, è lo stesso del punto 3)
Il Server che contiene di Dati (nel nostro caso vtenext)

In pratica, l'Applicazione (che potrebbe essere un Gestionale che deve leggere le Fatture su vtenext), chiede al Server di Autorizzazione un Access Token inviando la coppia di accesso (Client ID e Secret Key) per autenticarsi. Se le credenziali (Client ID e Secret Key) sono corrette, viene rilasciato un Access Token (stringa casuale) con il quale l'Applicazione può chiedere a vtenext le informazioni necessarie (es: Fatture) via REST API.

Il vantaggio è che l'access Token ha una durata limitata, è revocabile lato server e quindi è possibile consentire l'accesso alle app in maniera controllata e, soprattutto, non vengono divulgate o condivise password di sistema. Naturalmente allo scadere del Token, sarà necessario ottenerne uno di nuovo ripetendo la procedura sopra menzionata.

Questo tipo di flusso è indicato per la comunicazione diretta tra 2 server, senza bisogno di intervento umano dopo aver configurato entrambe le parti.

Il secondo tipo di flusso, è denominato Authorization Code. Questo flusso coinvolge un elemento in più, che identificheremo come Utente.

Nell'esempio, diremo che l'Applicazione che si vuole connettere a vtenext questa volta, è Facebook che necessita di leggere i Lead presenti in vtenext. Chi richiede i dati non è però Facebook direttamente, ma l'Utente che lo usa, che deve fornire a Facebook i Leads che l'Utente possiede all'interno del crm. L'obiettivo è quindi che l'utente dia il permesso a Facebook di leggere i Lead su vtenext, quindi sarà fatta un'autenticazione da parte dell'utente su vte, il quale risponderà a Facebook con un Authorization Code. Facebook userà quell'Auth Code per richiedere all'Authorization Server l'Access Token (che può essere temporaneo, da usare una tantum, oppure può essere rinnovato in autonomia) e leggere finalmente i dati nel Server.

Quindi, nonostante Facebook abbia avuto accesso ai Lead di vtenext, non ha memorizzato le credenziali dell'utente, e dopo circa un'ora (durata standard dell'Access Token) scadranno e quindi l'accesso ai dati sensibili sarà bloccato fino a nuova autorizzazione.

Questo flusso è indicato quando una applicazione esterna deve accedere ai dati di un utente per successive elaborazioni.

Configurazione Service Account

Cliccare sul pulsante AGGIUNGI sulla destra

Si accede ad una schermata con un Wizard che ci aiuta a determinare il flusso che vogliamo configurare. Come prima cosa impostare il Tipo di Client e si potrà scegliere tra:

Web or Mobile application se abbiamo bisogno di un accesso tramite login con utente (flusso Authorization Code)
Service account se l'accesso avviene in background tra due server (flusso Client Credentials)

Volendo dunque configurare un flusso Client Credentials, come Tipo di Chiave = Service Account e come Tipo di Segreto = Chiave segreta. Compariranno dunque altri campi da configurare che vediamo di seguito:

A questo punto si dovrà dare un Nome a questa configurazione, che tipicamente identifica anche quello che fa (nell'esempio fa connettere ad un gestionale). Vengono già messe in evidenza il Client ID e la Chiave Segreta autogenerate. Infine si deve determinare lo Scope, ovvero come i dati verranno fruiti dal sistema (sola lettura, sola scrittura, oppure in lettura/scrittura) e l'Utente al quale questa configurazione dovrà fare riferimento (se lo Scope è in sola lettura o lettura/scrittura per esempio, sarà possibile gestire solamente i dati di quell'utente con le limitazioni che la sua profilazione prevede. E' chiaro che se si desidera pieno controllo senza limitazioni, dovrà essere selezionato un utente Admin).

Fornendo dunque gli Endpoints, il Client ID e la Chiave Segreta all'ipotetico tecnico del gestionale al quale ci si vuole connettere, sarà possibile finalizzare il collegamento.

Tornando alla configurazione iniziale, dopo aver scelto Tipo di Chiave = Service Account e come Tipo di Segreto = JWT firmato, ci sono più o meno le stesse informazioni da configurare e come unica differenza, troviamo che la Chiave Segreta verrà generata solamente dopo il salvataggio della configurazione.

Configurazione Web or Mobile Application

Cliccare sul pulsante AGGIUNGI sulla destra

Si accede dunque nuovamente al Wizard e selezioneremo Web or mobile application. Comparirà la schermata seguente:

In Tipo di applicazione, è possibile scegliere Web application se si tratta di un App che funziona tramite browser, oppure Native or Single Page App se invece si tratta di un'applicazione nativa come un'app presente su un dispositivo mobile.

Scegliendo Web application, verrà generata come per la configurazione vista in precedenza, un Client ID ed una Chiave Segreta e sarà possibile determinare il tipo di accesso, Scope, in sola lettura, sola scrittura o lettura/scrittura.

E' possibile decidere le attivare l'Accesso offline, ovvero invece di far scadere il Token come si diceva in precedenza (il Token ha una durata limitata e va rinnovato), in questo modo è possibile dare accesso a tempo indeterminato all'app verso vtenext. Quindi cosa succede? Il server chiede il "refresh token" e quindi l'app può richiedere nuovamente il token che sarà il medesimo e rimarrà valido fino a che non viene deciso di togliere la spunta da Offline.

Quindi poi si configurerà l'URL di ritorno, che permetterà di reindirizzare l'utente, dopo il Login al Server (ovvero vtenext), direttamente all'app in cui deve accedere (es. Facebook o altro). E' anche possibile decidere quali sono gli Utenti autorizzati ad utilizzare questa configurazione. Possono essere Tutti gli utenti, oppure quelli che si vogliono selezionare dalla lista Gruppi o Utenti.

E' possibile configurare la Schermata di autorizzazione, ovvero quando l'utente viene indirizzato alla richiesta di autorizzazione (es. l'applicazione Facebook richiede di accedere ai dati di vtenext, vuoi autorizzare?), comparirà una schermata che è possibile personalizzare con un Nome, una Descrizione ed un'Icona.

Tornando all'inizio di questo tipo di settaggio, in Tipo di applicazione è possibile selezionare anche Native or Single Page App, la cui configurazione è molto simile a quella appena illustrata.

Dalla schermata inziale, Impostazioni > Applicazioni esterne, è possibile vedere la lista delle Applicazioni registrate ed è possibile decidere se revocarne qualcuna. Ad esempio, non è più richiesto che Facebook possa accedere a vtenext, nonostante l'autorizzazione sia già stata configurata e concessa, è possibile disabilitarla cliccando sulla spunta verde sulla destra della lista.

In questa lista è anche possibile vedere se ci sono Token scaduti oppure di non attivi. Nel caso di Token scaduti l'utente è tenuto a rifare il login al sistema. Nella stessa lista, sulla destra, troviamo gli Strumenti:

serve per modificare la configurazione
per revocare tutti i Token
per eliminare la configurazione eseguita

Nelle Preferenze Utente, c'è una voce sulla destra, denominata Applicazioni collegate, che permette di visualizzare tutte le applicazioni che sono state create e relazionate allo specifico utente. Da quella stessa related, è possibile vedere il dettaglio della configurazione (ma non modificarla se non è un utente admin), ed è possibile anche disabilitarla o revocarne i token.