Guida all'uso delle API OAuth2 per SocialAnime.it - Beta

Pagine disponibili

• authorize.php: login dell’utente e autorizzazione del client. Restituisce l’authorization code tramite redirect al callback. L’authorization code è monouso e ha una scadenza temporale.
• callback.php: pagina del client che riceve l’authorization code e lo scambia con access token e refresh token.
• token.php: endpoint per scambiare l’authorization code con access token valido. Restituisce messaggi chiari se il code è scaduto o già usato.
• refresh_token.php: endpoint per ottenere un nuovo access token usando un refresh token. Se un access token valido esiste già, lo restituisce senza generarne uno nuovo, con il tempo residuo aggiornato.
• resource.php: esempio di API protetta, che accetta solo access token validi.
• test_authorize.php: pagina di test per simulare la richiesta di autorizzazione dal client.
• test_resource.php: pagina di test per chiamare le API protette usando l’access token ottenuto.

Flusso di utilizzo per un client

1. Aprire test_authorize.php nel browser o via URL con ?client_id=ID_CLIENT.
2. Eseguire il login nella pagina authorize.php e cliccare "Login & Autorizza".
3. Il server reindirizza automaticamente a callback.php con l’authorization code.
4. callback.php scambia il code con access token e refresh token tramite token.php.
5. Usare l’access token per chiamare le API protette tramite resource.php o test_resource.php.
6. Quando l’access token scade, usare refresh_token.php per ottenere un nuovo token. Se esiste già un token valido, verrà restituito quello esistente con il tempo residuo aggiornato.

Esempio chiamata API

GET /resource.php
Authorization: Bearer ACCESS_TOKEN

L’API risponderà con i dati dell’utente se il token è valido e ha i permessi corretti.

Esempi di chiamate cURL con risposta

1. Richiesta di autorizzazione (authorize)

curl -X GET "http://localhost/api-sa/public/authorize.php?client_id=ID_CLIENT"

Risposta tipica (redirect al callback con authorization code):

HTTP/1.1 302 Found
Location: http://localhost/api-sa/public/callback.php?code=AUTH_CODE

2. Scambio authorization code con access token e refresh token (token)

curl -X POST "http://localhost/api-sa/public/token.php" \
-d "grant_type=authorization_code" \
-d "code=AUTH_CODE" \
-d "client_id=ID_CLIENT" \
-d "client_secret=CLIENT_SECRET"

Risposta JSON:

{
    "access_token": {
        "value": "ACCESS_TOKEN",
        "token_type": "Bearer",
        "expires_in": 3600
    },
    "refresh_token": {
        "value": "REFRESH_TOKEN",
        "token_type": "Bearer",
        "expires_in": 2592000
    }
}

3. Uso dell’access token per chiamare API protette (resource)

curl -X GET "http://localhost/api-sa/public/resource.php" \
-H "Authorization: Bearer ACCESS_TOKEN"

Risposta JSON:

{
    "message": "Accesso riuscito!",
    "user_id": 123
}

4. Refresh dell’access token usando il refresh token

curl -X POST "http://localhost/api-sa/public/refresh_token.php" \
-d "client_id=ID_CLIENT" \
-d "refresh_token=REFRESH_TOKEN"

Risposta JSON:

{
    "access_token": {
        "value": "NEW_ACCESS_TOKEN",
        "token_type": "Bearer",
        "expires_in": 3600
    }
}

Messaggi e errori

• invalid_grant: l’authorization code non esiste.
• expired_code: l’authorization code è scaduto.
• used_code: l’authorization code è già stato usato.
• invalid_refresh_token: il refresh token fornito non è valido.
• Tutti gli errori restituiscono un messaggio chiaro e il relativo error nel JSON.

Note pratiche

• L’utente può solo accettare o rifiutare la richiesta di autorizzazione.
• Tutti gli scope dei token sono definiti a livello di client, nessuna scelta dell’utente.
• Se servono scope differenti, creare un client separato.
• Le pagine test_authorize.php e test_resource.php servono per verificare velocemente il flusso completo.
• Refresh token gestisce automaticamente il ritorno del token esistente se ancora valido, con il tempo residuo aggiornato.
• Tutti i messaggi JSON contengono informazioni utili per debug e gestione corretta del flusso OAuth2.