Questo articolo spiega come funzionano le credenziali, gli ambiti di scrittura e i cataloghi di un'applicazione registrata, e quali condizioni devono essere soddisfatte affinché l'applicazione possa creare, modificare o eliminare campagne e creare contenuti tramite l'API di SMARTFENSE.
Che cos'è un'applicazione registrata?
Un'applicazione rappresenta un sistema esterno che si connette all'API di SMARTFENSE. Ogni applicazione dispone di credenziali proprie e può utilizzare solo gli endpoint abilitati dai suoi ambiti (scope).
Le applicazioni si gestiscono da Configurazione > Integrazioni > Applicazioni registrate.
Per la procedura completa di registrazione, consultare l'articolo Integración de APIs en SMARTFENSE.
Autenticazione
L'API di SMARTFENSE utilizza i flussi OAuth 2.0 Client Credentials e Authorization Code per autenticare le richieste.
- Client Credentials: progettato per interazioni da server a server. L'applicazione accede all'API senza che sia presente un utente.
- Authorization Code: si utilizza quando l'applicazione deve accedere a risorse per conto di un utente. Richiede l'interazione e il consenso esplicito di tale utente tramite un browser.
Affinché una richiesta venga accettata:
- Tutte le richieste devono essere autenticate.
- Tutte le richieste devono essere effettuate tramite HTTPS.
- Ogni richiesta deve includere un bearer token nell'intestazione
Authorization.
Importante: qualsiasi chiamata effettuata tramite HTTP semplice non andrà a buon fine.
Credenziali
- Client ID e Client Secret: identificano l'applicazione quando richiede un token di accesso.
- Tipo di client: indica dove vengono conservate le credenziali.
- Riservato: le credenziali vengono conservate su un server.
- Pubblico: le credenziali vengono conservate lato client.
- Tipo di concessione dell'autorizzazione: definisce il flusso OAuth 2.0 con cui l'applicazione ottiene il proprio token.
- Client Credentials: per integrazioni da server a server, senza l'intervento di un utente.
- Authorization Code: quando un utente deve autorizzare l'applicazione dal browser. In questo caso, compilare gli URI di reindirizzamento.
Importante: il Client Secret viene mostrato solo al momento della registrazione dell'applicazione. Copiarlo e conservarlo in un luogo sicuro, perché non può essere recuperato in seguito.
Ambiti
Gli ambiti sono i permessi dell'applicazione. Per sicurezza, selezionare solo quelli necessari per gli endpoint che verranno utilizzati.
Ambiti delle campagne
Creare, modificare ed eliminare campagne sono tre ambiti distinti. In questo modo è possibile, ad esempio, consentire a un'applicazione di creare campagne senza consentirle di eliminarle.
Solo un utente con il permesso di amministrare le campagne può:
- Concedere tali ambiti.
- Modificare o eliminare un'applicazione che li possiede già.
Ambito per creare contenuti
Solo un utente con il permesso di amministrare i contenuti può:
- Concedere l'ambito per creare contenuti.
- Modificare o eliminare un'applicazione che lo possiede già.
Per conto di chi agisce l'applicazione?
Anche se con Client Credentials non è presente alcun utente al momento della richiesta, gli ambiti di scrittura restano sempre collegati a una persona. L'applicazione li utilizza finché tale persona rimane attiva e conserva il permesso corrispondente:
| Tipo di concessione dell'autorizzazione | Utente per conto del quale agisce l'applicazione |
|---|---|
| Client Credentials | L'utente che ha registrato l'applicazione. |
| Authorization Code | L'utente che ha autorizzato l'applicazione dal browser. |
Avvertenza: se tale utente viene disattivato o perde il permesso di amministrare le campagne, l'applicazione non può più creare, modificare o eliminare campagne. Lo stesso vale per l'ambito per creare contenuti se l'utente perde il permesso di amministrare i contenuti.
Cataloghi
I cataloghi dell'applicazione definiscono:
- Quali contenuti può utilizzare nelle campagne che crea o modifica, allo stesso modo dei cataloghi di un utente amministratore.
- In quali cataloghi può salvare i contenuti che crea.
Quando sono obbligatori?
I cataloghi sono obbligatori quando l'applicazione dispone dell'ambito per creare o modificare campagne, oppure per creare contenuti. Per tutti gli altri ambiti non vengono presi in considerazione.
Opzioni di assegnazione
- Tutti i cataloghi: l'applicazione può utilizzare i contenuti di tutti i cataloghi dell'organizzazione.
- Cataloghi selezionati: l'applicazione può utilizzare solo i contenuti dei cataloghi selezionati.
In entrambi i casi, contano solo i cataloghi che l'organizzazione ha sottoscritto. Se un catalogo non è più sottoscritto, smette di applicarsi senza che sia necessario modificare l'applicazione.
Regole che limitano i cataloghi
- È possibile concedere solo i cataloghi assegnati all'utente che configura l'applicazione.
- L'applicazione utilizza solo i cataloghi assegnati all'utente per conto del quale agisce: con Client Credentials, chi l'ha registrata; con Authorization Code, chi l'ha autorizzata.
- Se un altro amministratore le concede un catalogo che tale utente non possiede, l'applicazione non lo utilizza, anche se risulta concesso.
- Un'applicazione non può modificare una campagna il cui contenuto appartiene a un catalogo che non ha abilitato.
Nota: se un'applicazione non riesce a utilizzare un contenuto o a modificare una campagna, verificare prima i cataloghi assegnati all'utente per conto del quale agisce l'applicazione, e poi i cataloghi concessi all'applicazione.
💡 Buone pratiche
- Conservare il Client Secret in un gestore di segreti approvato dalla propria organizzazione e non includerlo mai in codice esposto lato client.
- Utilizzare Client Credentials per processi automatici senza utente, e Authorization Code quando ogni utente deve acconsentire all'accesso.
- Concedere solo gli ambiti di scrittura necessari all'integrazione. Ad esempio, evitare di concedere l'ambito per eliminare campagne se l'integrazione si limita a crearle.
- Per le integrazioni con Client Credentials, registrare l'applicazione con un utente stabile, che non perderà il proprio permesso né verrà disattivato.
- Assegnare all'applicazione solo i cataloghi che utilizzerà, invece di Tutti i cataloghi, quando l'integrazione lavora con un programma specifico.
- Prima di modificare i permessi o i cataloghi di un amministratore, verificare se esistono applicazioni registrate che agiscono per suo conto.
- Documentare internamente quale utente ha registrato o autorizzato ciascuna applicazione e quali ambiti possiede.