Autenticazione e autorizzazione
Quasi tutti gli endpoint richiedono un token OAuth 2.0 Bearer
valido, da inviare nell'header Authorization di ogni richiesta:
Il token ha una durata limitata; alla scadenza ne va richiesto uno nuovo. Questa pagina spiega come ottenerlo.
Prima di tutto: registra la tua app
Per ottenere le credenziali OAuth (client_id e client_secret) devi prima
registrare la tua applicazione sull'App Store di Amica. In fase
di registrazione scegli gli scope richiesti e il flusso di autenticazione.
L'identity provider di Amica è basato su OpenID Connect. L'authority è
https://auth.amica20.it, con gli endpoint standard:
- Autorizzazione:
https://auth.amica20.it/connect/authorize - Token:
https://auth.amica20.it/connect/token - Discovery:
https://auth.amica20.it/.well-known/openid-configuration
Flussi disponibili
La scelta dipende da come la tua applicazione si autentica:
- c'è un utente che può accedere via browser (web app, SPA, app mobile)? Usa Authorization Code con PKCE;
- è un servizio headless (backend, batch, integrazione server-to-server) di una singola azienda, senza un utente che effettua il login? Usa Client Credentials.
Authorization Code con PKCE (consigliato)
Il flusso Authorization Code (definito in OAuth 2.0 RFC 6749, sez. 4.1) prevede lo scambio di un codice di autorizzazione con un access token. È il flusso consigliato per le applicazioni che operano per conto di un utente Amica, ed è l'unico disponibile alle app pubbliche (pubblicate sul marketplace), perché garantisce che le credenziali dell'utente non vengano mai condivise con l'app: il login avviene sull'infrastruttura Amica e l'utente concede esplicitamente i permessi.
In sintesi: l'utente viene reindirizzato a una pagina dell'Authorization Server, dove
effettua il login e approva (o nega) i permessi richiesti dall'app. Viene quindi
emesso un codice, che l'app scambia con un access token chiamando connect/token. Da
quel momento l'app usa il token per accedere alle risorse dell'API.
Una sola registrazione serve un numero qualsiasi di aziende: ogni utente, di qualsiasi azienda, autorizza l'app per la propria, e il token ne riceve automaticamente il contesto. È quindi il flusso adatto anche alle applicazioni distribuite a più clienti.
Client Credentials
Il flusso Client Credentials è pensato per le integrazioni server-to-server,
senza utente interattivo: l'app richiede direttamente un access token usando
client_id e client_secret.
Un'app Client Credentials è legata a una singola azienda — quella dell'utente che la registra — e il token ne riceve automaticamente il contesto. Per servire un'azienda diversa serve una registrazione separata; se devi distribuire la stessa app a più aziende usa invece Authorization Code.
POST https://auth.amica20.it/connect/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>&scope=read write documenti
Solo app private
Il flusso Client Credentials è disponibile solo per le app private, non per
quelle pubblicate sul marketplace. Custodisci il client_secret con la massima
cura.
Niente openid in questo flusso
Non includere lo scope openid (né profile/email) nella richiesta Client
Credentials. openid attiva OpenID Connect — il login di un utente e l'emissione
di un ID token — che in un flusso puramente server-to-server non ha senso:
l'identity provider rifiuta la richiesta con l'errore Client cannot request
OpenID scopes in client credentials flow. Indica solo gli scope di risorsa
(comune, magazzino, documenti, contabilita, ed eventualmente read/write).
Tipi di token
| Token | Descrizione | Durata |
|---|---|---|
| Authorization Code | Si scambia con un access token. È valido una sola volta e ha vita molto breve. Usato solo nel flusso Authorization Code. | 5 minuti |
| Access Token | Si usa per chiamare gli endpoint dell'API. | 24 ore |
| Refresh Token | Si usa per ottenere un nuovo access token alla scadenza, senza richiedere una nuova autorizzazione esplicita all'utente. | 1 anno |
Scope
Gli scope sono il meccanismo con cui si limita l'accesso di un'applicazione ai
dati di un'azienda: ogni scope corrisponde al permesso di operare su un determinato
insieme di risorse. L'access token è limitato agli scope concessi; una richiesta
verso una risorsa non coperta riceve una risposta 403 Forbidden.
Gli scope richiesti si indicano in fase di registrazione dell'app e, nel flusso Authorization Code, vengono confermati dall'utente dopo il login.
Tip
Prevedi sempre la gestione degli errori 403 Forbidden: l'utente potrebbe non
concedere uno degli scope richiesti.
Scope disponibili
| Scope | Descrizione |
|---|---|
read |
Accesso in lettura alle risorse |
write |
Accesso in scrittura alle risorse |
comune |
Anagrafiche e tabelle di base comuni |
magazzino |
Articoli, listini, giacenze e movimenti di magazzino |
documenti |
Documenti commerciali (ordini, DDT, preventivi, fatture, note di credito, ...) e fatturazione elettronica |
contabilita |
Scadenze (altre risorse contabili in arrivo) |
Principio del privilegio minimo
Nello scegliere gli scope, segui il principio del privilegio minimo: richiedi solo gli scope che ti servono e preferisci, quando possibile, i permessi di sola lettura. Così, in caso di furto di un access token, l'attaccante può compiere un insieme limitato di azioni; inoltre richiedere troppi permessi può scoraggiare l'utente in fase di autorizzazione.