Autenticazione OAuth2

Questo testo è stato tradotto utilizzando l’IA. Se desideri visualizzare il testo originale in inglese, fai clic qui.

OAuth2 consente alle applicazioni di accedere in modo sicuro ai siti WordPress.com e Jetpack senza bisogno delle password degli utenti. Fornisce un controllo granulare su ciò a cui ogni app può accedere.

OAuth2 consente alle app di richiedere solo le autorizzazioni specifiche di cui hanno bisogno tramite gli “scope”. Quando gli utenti autorizzano un’app, possono vedere e controllare esattamente quale accesso stanno concedendo.

Gli utenti accedono con il proprio account WordPress.com e possono approvare o negare le autorizzazioni richieste, mantenendo il controllo sui propri dati mentre collegano le app in sicurezza.

Prerequisiti

Prima di sviluppare la tua applicazione OAuth2, è necessario avere un’applicazione WordPress.com registrata con i seguenti dati:

1. Client ID: identifica la tua applicazione
2. Client Secret: autentica la tua applicazione (da mantenere al sicuro)
3. URI di reindirizzamento: dove gli utenti vengono reindirizzati dopo l’autorizzazione

Puoi ottenere queste credenziali tramite il Gestore delle applicazioni di WordPress.com.

Utilizza questo modulo per registrare una nuova applicazione WordPress.com

Endpoint OAuth2

Se non hai familiarità con OAuth2, puoi saperne di più su https://oauth.net/. Per l’integrazione con WordPress.com, è necessario comprendere gli endpoint principali di OAuth2 disponibili nel namespace https://public-api.wordpress.com/oauth2/. Questi endpoint funzionano in modo coerente sia per i siti WordPress.com che per i siti connessi tramite Jetpack.

Endpoint di autorizzazione

Endpoint: https://public-api.wordpress.com/oauth2/authorize

Metodo: GET (tramite reindirizzamento dell’utente)

Qui inizia il flusso OAuth2. Viene presentata un’interfaccia di autorizzazione in cui l’utente può esaminare e approvare i permessi richiesti dalla tua applicazione. L’endpoint convalida le credenziali dell’applicazione, l’URI di reindirizzamento e genera codici di autorizzazione sicuri per lo scambio di token.

Parametri obbligatori:

• client_id: il client ID della tua applicazione
• redirect_uri: deve corrispondere all’URI di reindirizzamento registrato
• response_type: “code” per il flusso Authorization Code o “token” per il flusso Implicit

Parametri opzionali:

• scope: permessi separati da spazi (per impostazione predefinita, accesso a un singolo blog)
• state: consigliato per la protezione CSRF
• blog: URL o ID di un blog specifico per l’accesso a un singolo sito

Esempio di URL di autorizzazione (flusso Authorization Code):

https://public-api.wordpress.com/oauth2/authorize?client_id=12345&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=code&scope=posts%20media&state=abc123xyz

Esempio di URL di autorizzazione (flusso Implicit):

https://public-api.wordpress.com/oauth2/authorize?client_id=12345&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=token&scope=posts%20media&state=abc123xyz

Esempio di URL di autorizzazione (blog specifico):

https://public-api.wordpress.com/oauth2/authorize?client_id=12345&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=code&blog=yourblog.wordpress.com&scope=posts%20media&state=abc123xyz

Risposta/Azione: dopo l’approvazione da parte dell’utente, reindirizza al tuo redirect_uri con:

• Flusso Authorization Code: ?code=AUTHORIZATION_CODE&state=YOUR_STATE
• Flusso Implicit: #access_token=TOKEN&expires_in=64800&token_type=bearer&site_id=BLOG_ID
• Rifiuto dell’utente: ?error=access_denied

Nota importante: il parametro redirect_uri deve corrispondere esattamente all’URI di reindirizzamento registrato durante la creazione dell’applicazione. Anche differenze minime (come la mancanza di una barra finale) causeranno il fallimento dell’autorizzazione. Si tratta di una misura di sicurezza per prevenire reindirizzamenti malevoli.

Endpoint di richiesta del token

Endpoint: https://public-api.wordpress.com/oauth2/token

Metodo: POST

Questo endpoint sicuro server-to-server gestisce due diversi tipi di concessione per ottenere i token di accesso. Scegli il tipo di concessione appropriato in base al tuo caso d’uso:

Authorization Code Grant (uso in produzione)

Utilizza questo tipo di concessione per tutte le applicazioni in produzione. Scambia i codici di autorizzazione (ricevuti dall’autorizzazione dell’utente) con token di accesso, mantenendo al sicuro il tuo client secret.

Parametri obbligatori:

• client_id: Il client ID della tua applicazione
• client_secret: Il client secret della tua applicazione
• code: Codice di autorizzazione ottenuto dal passaggio di autorizzazione
• grant_type: Deve essere “authorization_code”
• redirect_uri: Deve corrispondere all’URI di reindirizzamento dell’autorizzazione

Esempio di richiesta:

curl -X POST https://public-api.wordpress.com/oauth2/token 
  -d "client_id=12345" 
  -d "client_secret=your_client_secret" 
  -d "code=received_authorization_code" 
  -d "grant_type=authorization_code" 
  -d "redirect_uri=https://yourapp.com/callback"

Password Grant (solo sviluppo e test)

Questo tipo di concessione consente ai proprietari delle applicazioni di ottenere token direttamente utilizzando le proprie credenziali WordPress.com, bypassando il flusso di autorizzazione utente.

Usa il Password Grant per:

• Testare gli endpoint API durante lo sviluppo
• Test automatizzati in cui la simulazione dell’autorizzazione utente non è praticabile
• Sviluppo personale sui propri siti WordPress.com

Restrizioni di sicurezza:

• Funziona solo con le proprie credenziali WordPress.com (non quelle di altri utenti)
• Richiede l’esposizione delle credenziali nel codice
• Bypassa il consenso dell’utente e i vantaggi di sicurezza di OAuth2
• Non utilizzare mai in applicazioni di produzione

Parametri obbligatori:

• client_id: Il client ID della tua applicazione
• client_secret: Il client secret della tua applicazione
• grant_type: Deve essere “password”
• username: Il tuo nome utente WordPress.com
• password: La tua password WordPress.com (o Password per applicazioni se la 2FA è abilitata)

Esempio di richiesta:

curl -X POST https://public-api.wordpress.com/oauth2/token 
  -d "client_id=12345" 
  -d "client_secret=your_client_secret" 
  -d "grant_type=password" 
  -d "username=your_username" 
  -d "password=your_password_or_app_password"

Autenticazione a due fattori: se hai la 2FA abilitata, crea una Password per applicazioni nelle Impostazioni del tuo account WordPress.com e utilizzala al posto della tua password abituale.

Percorso di migrazione: Inizia con il Password Grant per comodità durante lo sviluppo, ma implementa l’Authorization Code Flow prima del lancio in produzione. Considera il Password Grant come una scorciatoia di sviluppo che deve essere sostituita con un’autorizzazione utente appropriata nelle applicazioni in produzione.

Formato della risposta del token (entrambi i tipi di Grant):

{
    "access_token": "YOUR_API_TOKEN",
    "blog_id": "blog_id_number", 
    "blog_url": "https://yourblog.wordpress.com",
    "token_type": "bearer"
}

Endpoint informazioni token

Endpoint: https://public-api.wordpress.com/oauth2/token-info

Metodo: GET

Fornisce validazione e ispezione sicura dei token. Restituisce informazioni dettagliate sui token, inclusi ID utente, ID blog e permessi di scope. Essenziale per verificare l’autenticità dei token, specialmente quando vengono trasmessi tra sistemi diversi o nelle applicazioni mobile.

Parametri obbligatori:

• client_id: il client ID della tua applicazione
• token: il token di accesso da validare

Esempio di richiesta:

GET https://public-api.wordpress.com/oauth2/token-info?client_id=12345&token=your_access_token_here

Esempio di richiesta CURL:

curl "https://public-api.wordpress.com/oauth2/token-info?client_id=12345&token=your_access_token_here"

Formato della risposta (token valido):

{
    "client_id": "12345",
    "user_id": "123456789",
    "blog_id": "987654321", 
    "scope": "posts,media"
}

Risposta (token non valido): restituisce un errore se il token non è stato autorizzato per la tua applicazione o non è valido.

Endpoint di autenticazione

Endpoint: https://public-api.wordpress.com/oauth2/authenticate

Metodo: GET (tramite reindirizzamento utente)

Un endpoint specializzato per le applicazioni WordPress.com Connect che necessitano solo della verifica di base dell’identità utente. Ottimizzato per la funzionalità “Accedi con WordPress.com”, è progettato per la verifica dell’identità piuttosto che per la gestione dei contenuti.

Parametri obbligatori:

• client_id: il client ID della tua applicazione
• redirect_uri: deve corrispondere all’URI di reindirizzamento registrato
• response_type: usa “code” per uno scambio sicuro lato server

Parametri facoltativi:

• scope: tipicamente “auth” per l’accesso base al profilo
• state: consigliato per la protezione CSRF

URL di autenticazione di esempio:

https://public-api.wordpress.com/oauth2/authenticate?client_id=12345&redirect_uri=https%3A%2F%2Fyourapp.com%2Fauth-callback&response_type=code&scope=auth&state=random_secure_string

Risposta/Azione: dopo l’approvazione da parte dell’utente, viene effettuato un reindirizzamento al tuo redirect_uri con un codice di autorizzazione. Scambia questo codice presso l’endpoint del token per ricevere un token con ambito limitato, che in genere fornisce accesso solo a:

Accesso API disponibile:

• Endpoint /me/ per le informazioni base del profilo utente
• Dati di verifica dell’identità dell’utente (ID, username, email, avatar_URL, stato di verifica)

Flussi di lavoro OAuth2

WordPress.com supporta due principali flussi di lavoro OAuth2, ciascuno progettato per diversi tipi di applicazione e requisiti di sicurezza:

Authorization Code Flow (consigliato)

L’Authorization Code Flow è il flusso di lavoro OAuth2 standard per le applicazioni lato server in cui è possibile archiviare in modo sicuro i client secret. Questo flusso offre il massimo livello di sicurezza scambiando un codice di autorizzazione con un access token tramite una richiesta sicura server-to-server.

Vantaggio in termini di sicurezza: il client secret non compare mai nel codice lato client e gli access token vengono ottenuti tramite richieste server autenticate.

Implicit Flow (legacy)

L’Implicit Flow è stato progettato per le applicazioni basate su browser in cui l’access token viene restituito direttamente nel frammento dell’URL. Tuttavia, questo approccio è oggi considerato meno sicuro ed è stato in gran parte deprecato a favore di alternative più sicure come PKCE (Proof Key for Code Exchange).

Importante: si consiglia di utilizzare l’Authorization Code Flow ogni volta che è possibile per una maggiore sicurezza.

Scope e permessi OAuth2

La potenza di OAuth2 risiede nel suo sistema di permessi granulare. Quando si richiede l’autorizzazione, si specificano gli scope che definiscono esattamente a cosa può accedere la propria applicazione.

Scope disponibili

• users: Visualizzare le informazioni dell’utente
• sites: Visualizzare le informazioni generali e le opzioni del sito
• posts: Visualizzare e gestire gli articoli
• comments: Visualizzare e gestire i commenti degli articoli
• taxonomy: Visualizzare e gestire tag e categorie
• follow: Seguire e smettere di seguire i blog
• sharing: Connettere servizi di social media
• freshly-pressed: Visualizzare gli articoli Pubblicato di recente
• notifications: Visualizzare e gestire le notifiche dell’utente
• insights: Visualizzare le analitiche della propria applicazione
• read: Gestire e visualizzare le iscrizioni del Reader
• stats: Visualizzare le statistiche del sito
• media: Gestire i media del sito
• menus: Visualizzare e gestire i menu del sito
• batch: Raggruppare più richieste GET in batch
• videos: Visualizzare le informazioni sui video

Scope speciali

• global: Concede un accesso completo ai dati dell’utente su tutti i servizi WordPress.com e i siti connessi
• auth: Scope limitato che fornisce accesso solo all’endpoint /me/ per i flussi di autenticazione di base. Consultare WordPress.com Connect per ulteriori informazioni correlate.

Best practice per gli scope

Seguire sempre il principio del privilegio minimo:

// Request only necessary permissions
const scopes = 'posts,media'; // Not 'global' unless truly needed

Implementare l’autenticazione OAuth2

Passaggio 1: Richiesta di autorizzazione

Indirizza gli utenti all’endpoint di autorizzazione con i parametri richiesti:

Parametri obbligatori

• client_id: L’ID client della tua applicazione
• redirect_uri: Deve corrispondere all’URI registrato nelle impostazioni della tua applicazione
• response_type: Usa “code” per il flusso Authorization Code o “token” per il flusso Implicit

Parametri facoltativi

• blog: URL o ID di un blog specifico per l’accesso a un singolo sito
• scope: Elenco di permessi richiesti separati da spazi
• state: Parametro di sicurezza consigliato per prevenire attacchi CSRF

Esempio di URL di autorizzazione

const authUrl = `https://public-api.wordpress.com/oauth2/authorize?` +
  `client_id=${clientId}&` +
  `redirect_uri=${encodeURIComponent(redirectUri)}&` +
  `response_type=code&` +
  `scope=posts,media&` +
  `state=${secureRandomString}`;

// // Redirect user to authorization
window.location.href = authUrl;

Passaggio 2: Scambio del codice di autorizzazione

Dopo l’autorizzazione dell’utente, riceverai (all’indirizzo redirect_url) un codice di autorizzazione che deve essere scambiato con un token di accesso.

Scambio del token lato server

Effettua una richiesta POST all’endpoint del token:

$curl = curl_init( 'https://public-api.wordpress.com/oauth2/token' );

curl_setopt( $curl, CURLOPT_POST, true );
curl_setopt( $curl, CURLOPT_POSTFIELDS, array(
    'client_id' => $your_client_id,
    'redirect_uri' => $your_redirect_url,
    'client_secret' => $your_client_secret_key,
    'code' => $_GET['code'], // The authorization code
    'grant_type' => 'authorization_code'
) );

curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1);

$auth = curl_exec( $curl );
$secret = json_decode( $auth );
$access_token = $secret->access_token;

Risposta con esito positivo

{
    "access_token": "YOUR_API_TOKEN",
    "blog_id": "blog_id_number",
    "blog_url": "https://yourblog.wordpress.com",
    "token_type": "bearer"
}

Passaggio 3: effettuare chiamate API autenticate

Utilizza il token Bearer nell’header Authorization per tutte le richieste API:

$access_token = 'YOUR_API_TOKEN';
$curl = curl_init( 'https://public-api.wordpress.com/rest/v1/me/' );

curl_setopt( $curl, CURLOPT_HTTPHEADER, array( 'Authorization: Bearer ' . $access_token ) );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1 );

$response = curl_exec( $curl );

Funzionalità avanzate di OAuth2

Gestione dell’ambito dei token

Diversi ambiti dei token forniscono diversi livelli di accesso:

• Token per singolo blog: concedono l’accesso a un blog specifico
• Token globali: forniscono l’accesso a tutti i siti WordPress.com e ai siti Jetpack connessi dell’utente
• Endpoint specifici per utente: alcuni endpoint (like, follow) funzionano su tutti i blog con qualsiasi token utente

OAuth lato client (implicito)

Per le applicazioni lato client, i token possono essere restituiti nel frammento dell’URL utilizzando il flusso implicito:

https://yourapp.com/callback#access_token=TOKEN&expires_in=64800&token_type=bearer&site_id=BLOG_ID

Considerazioni importanti:

• Attualmente i token scadono dopo due settimane
• Utilizzare il valore expires_in per gestire il rinnovo del token
• Adatto solo per client pubblici in cui i segreti non possono essere archiviati in modo sicuro

Validazione e gestione dei token

Gestire correttamente i token OAuth2 è fondamentale per un’applicazione robusta. Ciò include la validazione dei token, la gestione delle risposte API e la gestione appropriata della scadenza dei token o dei permessi insufficienti.

Endpoint informazioni token

Verifica l’autenticità del token utilizzando l’endpoint di informazioni sul token:

GET https://public-api.wordpress.com/oauth2/token-info?client_id=your_client_id&token=your_token

Risposta valida:

{
    "client_id": "your_client_id",
    "user_id": "user_id_number",
    "blog_id": "blog_id_number",
    "scope": "posts,media"
}

Sviluppo e test

Test con Password Grant (solo proprietari del client)

I proprietari dell’applicazione possono utilizzare il password grant per ottenere il token di autenticazione:

$curl = curl_init( 'https://public-api.wordpress.com/oauth2/token' );

curl_setopt( $curl, CURLOPT_POST, true );

curl_setopt( $curl, CURLOPT_POSTFIELDS, array(
    'client_id' => $your_client_id,
    'client_secret' => $your_client_secret_key,
    'grant_type' => 'password',
    'username' => $your_wpcom_username,
    'password' => $your_wpcom_password, // Use Application Password if 2FA enabled
) );

curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1);
$auth = curl_exec( $curl );
$auth = json_decode( $auth );
$access_token = $auth->access_token;

Importante: Questo metodo richiede una Password per applicazioni se l’autenticazione a due fattori è abilitata.

Best practice di sicurezza e gestione degli errori

Linee guida per l’implementazione

1. Validazione del parametro state: Validare sempre il parametro state per prevenire attacchi CSRF
2. Archiviazione sicura dei token: Archiviare i token di accesso in modo sicuro utilizzando una crittografia appropriata
3. Richiesta di permessi minimi: Richiedere solo i permessi effettivamente necessari per la propria applicazione
4. Comunicazione chiara con l’utente: Spiegare perché sono richiesti permessi specifici
5. Gestione corretta degli errori: Gestire in modo appropriato i fallimenti di autorizzazione, la scadenza dei token e le modifiche degli scope

Requisiti HTTPS

Tutte le comunicazioni OAuth2 devono utilizzare HTTPS per proteggere i token e i codici di autorizzazione durante la trasmissione.

Gestione dei token

• Archiviare i token di accesso in modo sicuro lato server
• Implementare meccanismi appropriati di aggiornamento dei token
• Fornire una documentazione chiara sul ciclo di vita dei token
• Gestire in modo appropriato la scadenza dei token nella propria applicazione

Gestione degli errori

Errori OAuth2 comuni e relativi significati:

• access_denied: L’utente ha rifiutato l’autorizzazione
• invalid_client: Credenziali client non valide
• invalid_grant: Codice di autorizzazione non valido o scaduto
• invalid_scope: L’ambito richiesto non è valido o non è disponibile

Implementa sempre una gestione completa degli errori per fornire un feedback chiaro quando si verificano problemi di autorizzazione.

Conclusione

OAuth2 offre un metodo di autenticazione sicuro e intuitivo per le integrazioni con WordPress.com. Implementando una corretta gestione degli ambiti, pratiche di sicurezza adeguate e una gestione degli errori efficace, puoi creare applicazioni che rispettano la privacy degli utenti offrendo al contempo funzionalità avanzate. Il sistema granulare dei permessi garantisce che gli utenti mantengano il controllo sui propri dati, consentendo alla tua applicazione di offrire funzionalità di valore.

Per la documentazione completa degli endpoint API e ulteriori esempi, visita il Riferimento REST API di WordPress.com.