🔒 Autenticazione

La maggior parte dei punti di accesso dell'API richiede l'autenticazione per funzionare. Ci affidiamo a un'istanza self-hosted di Keycloak come IdP (Identity Provider) dell'intera piattaforma. Gli utenti sono registrati sia su Keycloak che sul nostro database, mantenendoli sincronizzati.

Supportiamo tutti i metodi di autenticazione forniti direttamente da Keycloak. Si prega di fare riferimento a questa pagina per una guida molto dettagliata di tutti i possibili flussi di autorizzazione.

🔑🧑🏻 Autenticazione con password

Questo metodo dovrebbe essere utilizzato ESCLUSIVAMENTE per interazioni macchina-macchina. Poiché coinvolge la password di un account, non è possibile utilizzarlo su un client, ma solo su un server fidato (altrimenti la password sarebbe esposta a tutti!). Si prega di ricordarsi di non registrare mai la password in nessun luogo e di mantenerla al sicuro (possibilmente in variabili d'ambiente criptate).

Questo metodo consente a un server di ottenere un token di un account specifico e di chiamare le API autenticato come tale account. Il token scade dopo un determinato periodo di tempo. Per ulteriori dettagli, fare riferimento a questa pagina.

Di seguito è riportato un esempio di chiamata API per autenticarsi con le credenziali del client:

curl --location --request POST 'https://iam.staging.gayadeed.it/auth/realms/gaya/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>' \
--data-urlencode 'username=<EMAIL>' \
--data-urlencode 'password=<PASSWORD>' \
--data-urlencode 'scope=openid profile email' \
--data-urlencode 'grant_type=password'

I campi CLIENT_ID e CLIENT_SECRET verranno comunicati separatamente.

I campi EMAIL e PASSWORD sono le credenziali dell'utente per il quale si desidera ottenere un token.

La risposta avrà il seguente aspetto:

{
    "access_token": "ey...",
    "expires_in": 900,
    "refresh_expires_in": 1800,
    "refresh_token": "ey...",
    "token_type": "Bearer",
    "id_token": "ey...",
    "not-before-policy": 0,
    "session_state": "<uuid>",
    "scope": "openid email profile"
}

Memorizzare l'access_token e passarlo nell'intestazione Authorization di ogni chiamata autenticata nel formato: Bearer <access_token>