Creazione manuale di un flusso di accesso

Per l'accesso per un'app web o per computer tramite browser senza usare gli SDK, come in una visualizzazione web in un'app nativa per computer (ad esempio, su Windows 8) o un flusso di accesso usando interamente codice lato server, puoi creare un flusso di accesso personalizzato usando i reindirizzamenti del browser. Questa guida spiega in modo dettagliato il flusso di accesso, mostrando come implementarne i passaggi senza usare i nostri SDK:

Verifica dello stato d'accesso
Accesso delle persone
Conferma dell'identità
Memorizzazione dei token d'accesso e dello stato d'accesso
Disconnessione delle persone
Rilevamento delle disinstallazioni delle app
Risposta alle richieste di eliminazione dei dati degli utenti

Per usare Facebook Login in un'app per computer, dovrai poter incorporare un browser web (a volte chiamato visualizzazione web) all'interno dell'app per eseguire il processo di accesso.

Verifica dello stato d'accesso

Le app che utilizzano i nostri SDK possono verificare se una persona ha effettuato l'accesso tramite funzioni integrate. Tutte le altre app devono creare il proprio modo di memorizzazione dell'accesso di una persona, e, in assenza di questo indicatore, ritenere che la persona si sia disconnessa. Se una persona si è disconnessa, l'app dovrà reindirizzarla alla finestra di dialogo Accedi al momento appropriato, ad esempio quando clicca sul pulsante Accedi.

Se una persona non ha effettuato l'accesso all'app o a Facebook, puoi utilizzare la finestra di dialogo Accedi per richiederle di effettuare entrambe le azioni. Se la persona non ha effettuato l'accesso a Facebook, le verrà chiesto di accedere prima a Facebook e poi alla tua app. Questa azione verrà rilevata automaticamente, pertanto non è necessario che tu esegua ulteriori operazioni per abilitare questo comportamento.

Richiamo della finestra di dialogo Accedi e impostazione dell'URL di reindirizzamento

La tua app deve eseguire un reindirizzamento a un endpoint che visualizzerà la finestra di dialogo Accedi:

https://www.facebook.com/v19.0/dialog/oauth?
  client_id={app-id}
  &redirect_uri={redirect-uri}
  &state={state-param}

Questo endpoint prevede i seguenti parametri necessari:

client_id. L'ID della tua app si trova nella dashboard dell'app.
redirect_uri. L'URL a cui desideri reindirizzare l'utente al momento dell'accesso, che acquisisce la risposta della finestra di dialogo Accedi. Se lo usi nella visualizzazione web di un'app per computer, deve essere impostato su https://www.facebook.com/connect/login_success.html. Puoi confermare che questo URL è impostato per la tua app nella Dashboard gestione app. In Prodotti nel menu di navigazione a sinistra della Dashboard gestione app, clicca su Facebook Login, quindi clicca su Impostazioni. Verifica gli URI di reindirizzamento OAuth validi nella sezione Impostazioni OAuth client.
state. Un valore di tipo stringa creato dalla tua app per mantenere il parametro state tra la richiesta e la callback. Questo parametro deve essere usato per impedire attacchi Cross-site Request Forgery e verrà passato di nuovo a te, invariato, nel tuo URI di reindirizzamento.

Ad esempio, se la tua richiesta di accesso è simile alla seguente:

https://www.facebook.com/v19.0/dialog/oauth?
  client_id={app-id}
  &redirect_uri={"https://www.domain.com/login"}
  &state={"{st=state123abc,ds=123456789}"}

il tuo URI di reindirizzamento verrà chiamato in questo modo:

https://www.domain.com/login?state="{st=state123abc,ds=123456789}"

Inoltre, prevede i seguenti parametri facoltativi:

response_type. Determina se i dati della risposta inclusi quando si verifica il reindirizzamento all'app rientra nei parametri o nei frammenti di URL. Consulta la sezione Conferma delle identità per scegliere quale tipo usare nella tua app. Può essere uno tra:
- code. I dati della risposta sono inclusi come parametri URL e contengono il parametro code (una stringa crittografata unica per ogni richiesta di accesso). Si tratta del comportamento predefinito se questo parametro non viene specificato. È più utile per la gestione del token da parte del server.
- token. I dati della risposta sono inclusi come un frammento di URL e contengono un token d'accesso. Le app per computer devono usare questa impostazione per il valore response_type. È più utile per la gestione del token da parte del client.
- code%20token. I dati della risposta sono inclusi come un frammento di URL e contengono un token d'accesso e il parametro code.
- granted_scopes. Restituisce una lista separata da virgole di tutte le autorizzazioni che l'utente ha concesso all'app al momento dell'accesso. Può essere combinato con altri valori response_type. Se combinato con token, i dati della risposta vengono inclusi come un frammento di URL; in caso contrario, vengono inclusi come un parametro URL.
scope. Una lista separata da virgole o spazi delle autorizzazioni da richiedere alla persona che usa l'app.

Per le app per Windows 8

Se stai creando Facebook Login per un'app Windows, puoi usare l'identificatore di sicurezza del pacchetto come redirect_uri. Attiva la finestra di dialogo Accedi chiamando WebAuthenticationBroker.AuthenticateAsync e usa il relativo endpoint come requestUri. Ecco un esempio in JavaScript:

var requestUri = new Windows.Foundation.Uri(
  "https://www.facebook.com/v19.0/dialog/oauth?
    client_id={app-id}
    &display=popup
    &response_type=token
    &redirect_uri=ms-app://{package-security-identifier}");

Windows.Security.Authentication.Web.WebAuthenticationBroker.authenticateAsync(
  options,
  requestUri)
  .done(function (result) {
    // Handle the response from the Login Dialog
  }
);

In questo modo, l'app riavrà il flusso di controllo e riceverà un token d'accesso se l'azione è stata eseguita correttamente o un errore in caso contrario.

Gestione delle risposte della finestra di dialogo Accedi

A questo punto del flusso di accesso, la persona visualizzerà la finestra di dialogo Accedi e potrà scegliere se concedere o meno all'app l'accesso ai dati.

Se la persona che utilizza l'app sceglie Ok nella finestra di dialogo Accedi, concederà l'accesso al profilo pubblico, alla lista degli amici e a tutte le autorizzazioni aggiuntive richieste dalla tua app.

In tutti i casi, il browser torna all'app e vengono inclusi i dati di risposta che indicano se la persona si è collegata oppure ha annullato l'operazione. Quando l'app utilizza il metodo di reindirizzamento descritto in precedenza, al parametro redirect_uri restituito dalla tua app vengono aggiunti parametri o frammenti di URL (in base al valore response_type), che devono essere acquisiti.

A causa delle diverse combinazioni di linguaggi del codice che è possibile utilizzare nelle app web, la nostra guida non mostra esempi specifici. Tuttavia, la maggior parte dei linguaggi moderni è in grado di eseguire il parsing dell'URL nel modo seguente:

Il linguaggio JavaScript lato client è in grado di acquisire i frammenti di URL (ad esempio jQuery BBQ), mentre i parametri URL possono essere acquisiti tramite codice lato client e lato server (ad esempio $_GET in PHP, jQuery.deparam in jQuery BBQ, querystring.parse in Node.js oppure urlparse in Python). Microsoft mette a disposizione una guida e un codice di esempio per le app Windows 8 che si connettono a un "fornitore online" (in questo caso, Facebook).

Quando una persona effettua l'accesso a un'app per computer, Facebook la reindirizza al parametro redirect_uri descritto in precedenza, inserendo un token d'accesso e altri metadati (ad esempio, la scadenza del token) nel frammento di URI:

https://www.facebook.com/connect/login_success.html#
    access_token=ACCESS_TOKEN...

L'app deve essere in grado di individuare il reindirizzamento e di leggere il token d'accesso dell'URI tramite i meccanismi offerti dal sistema operativo e dal framework di sviluppo usato. In seguito, passa direttamente al passaggio Esame dei token d'accesso.

Accesso annullato

Se la persona che sta usando la tua app non accetta la finestra di dialogo Accedi e clicca su Annulla, viene reindirizzata a:

YOUR_REDIRECT_URI?
 error_reason=user_denied
 &error=access_denied
 &error_description=Permissions+error.

Consulta Gestione delle autorizzazioni mancanti per maggiori informazioni su quali operazioni deve eseguire l'app quando le persone rifiutano l'accesso.

Conferma dell'identità

Poiché il flusso di reindirizzamento prevede che i browser siano reindirizzati dalla finestra di dialogo Accedi agli URL nella tua app, a cui il traffico può accedere direttamente attraverso determinati frammenti o parametri. Se l'app li accetta come parametri validi, potrebbe usare questi dati per scopi potenzialmente dannosi. Pertanto, prima di generare un token d'accesso, l'app deve confermare che la persona che la sta usando sia la stessa a cui sono destinati i dati della risposta. Esistono diversi modi per confermare l'identità di una persona, a seconda del parametro response_type ricevuto in precedenza:

Se ricevi code, devi scambiarlo con un token d'accesso utilizzando un endpoint. Dal momento che usa la chiave segreta, la chiamata deve essere tra server (non inserire la chiave segreta in un codice lato client).
Se ricevi token, devi verificarlo. Devi effettuare una chiamata API a un endpoint di ispezione che indicherà per chi è stato generato il token e da quale app. Dal momento che la chiamata all'API richiede l'uso di un token d'accesso dell'app, non effettuarla da un client. Al contrario, effettua la chiamata da un server in cui puoi memorizzare la chiave segreta in modo sicuro.
Se ricevi sia code sia token, devi eseguire entrambi i passaggi.

Puoi anche generare un parametro state personale e usarlo con la richiesta di accesso come protezione dagli attacchi CSRF (Cross-Site Request Forgery).

Scambio del codice per un token d'accesso

Per ottenere un token d'accesso, effettua una richiesta HTTP GET al seguente endpoint OAuth:

GET https://graph.facebook.com/v19.0/oauth/access_token?
   client_id={app-id}
   &redirect_uri={redirect-uri}
   &client_secret={app-secret}
   &code={code-parameter}

Questo endpoint prevede i seguenti parametri necessari:

client_id. L'ID della tua app.
redirect_uri. Questo argomento è necessario e deve corrispondere al parametro request_uri originale, usato per avviare il processo di accesso OAuth.
client_secret. La chiave segreta unica mostrata nella Dashboard gestione app. Non includerla in un codice lato client o in binari che è possibile decompilare. È estremamente importante mantenerla segreta in quanto cuore di protezione dell'app e di tutte le persone che la usano.
code. Il parametro ricevuto dal reindirizzamento della finestra di dialogo Accedi descritto in precedenza.

Nota: a partire dalla versione 2.3, questo endpoint restituisce una risposta JSON corretta. Se la chiamata non specifica una versione, il valore predefinito corrisponde alla versione meno recente disponibile.

Risposta

La risposta che riceverai da questo endpoint sarà in formato JSON e, se l'azione è stata eseguita correttamente, sarà:

{
  "access_token": {access-token}, 
  "token_type": {type},
  "expires_in":  {seconds-til-expiration}
}

In caso contrario, riceverai un messaggio di errore esplicativo.

Esame dei token d'accesso

Indipendentemente dal fatto che l'app usi o meno code o token come response_type dalla finestra di dialogo Accedi, riceverà un token d'accesso. Puoi eseguire controlli automatici sui token tramite un endpoint API Graph:

GET graph.facebook.com/debug_token?
     input_token={token-to-inspect}
     &access_token={app-token-or-admin-token}

Questo endpoint accetta i seguenti parametri:

input_token. Il token da esaminare.
access_token Un token d'accesso dell'app o un token d'accesso per uno sviluppatore dell'app.

La risposta alla chiamata all'API è un array JSON contenente dati sul token esaminato. Ad esempio:

{
    "data": {
        "app_id": 138483919580948, 
        "type": "USER",
        "application": "Social Cafe", 
        "expires_at": 1352419328, 
        "is_valid": true, 
        "issued_at": 1347235328, 
        "metadata": {
            "sso": "iphone-safari"
        }, 
        "scopes": [
            "email", 
            "publish_actions"
        ], 
        "user_id": "1207059"
    }
}

I campi app_id e user_id aiutano l'app a verificare che il token d'accesso sia valido sia per l'utente sia per l'app stessa. Per una descrizione completa degli altri campi, consulta la guida su come ottenere informazioni sui token d'accesso.

Verifica delle autorizzazioni

Puoi chiamare il segmento /me/permissions per recuperare una lista delle autorizzazioni concesse o rifiutate da un determinato utente. La tua app può usare questo metodo per controllare quali autorizzazioni richieste non può usare per un utente specifico.

Nuova richiesta delle autorizzazioni negate

Facebook Login consente alle persone di rifiutare la condivisione di alcune autorizzazioni con la tua app. La finestra di dialogo Accedi contiene una schermata simile alla seguente:

L'autorizzazione public_profile è sempre necessaria e visualizzata in grigio poiché non è possibile disabilitarla.

Tuttavia, se l'utente disabilitasse user_likes ("Mi piace") in questo esempio, verificando /me/permissions per le autorizzazioni concesse, il risultato sarebbe il seguente:

{
  "data":
    [
      {
        "permission":"public_profile",
        "status":"granted"
      },
      {
        "permission":"user_likes",
        "status":"declined"
      }
    ]
}

Tieni presente che user_likes non è stata concessa.

Puoi chiedere di nuovo alla persona di concedere le autorizzazioni rifiutate all'app. Mostra prima una schermata in cui spieghi il motivo per cui dovrebbe concedere una determinata autorizzazione. Tuttavia chiamando la finestra di dialogo Accedi come descritto in precedenza, l'autorizzazione non sarà richiesta.

Questo poiché, una volta che la persona ha rifiutato un'autorizzazione, la finestra di dialogo Accedi non la richiede a meno che non sia tu a specificarlo.

Puoi farlo aggiungendo il parametro auth_type=rerequest all'URL della finestra di dialogo Accedi:

https://www.facebook.com/v19.0/dialog/oauth?
    client_id={app-id}
    &redirect_uri={redirect-uri}
    &auth_type=rerequest
    scope=email

In questo modo, la finestra di dialogo Accedi chiederà nuovamente l'autorizzazione rifiutata.

Memorizzazione dei token d'accesso e dello stato d'accesso

A questo punto del flusso, la persona è autenticata e ha effettuato l'accesso. L'app può effettuare chiamate API per suo conto. Prima, però, è necessario memorizzare il token d'accesso e lo stato d'accesso della persona che utilizza l'app.

Memorizzazione dei token d'accesso

Quando l'app ha ricevuto il token d'accesso tramite il passaggio precedente, deve memorizzarlo e renderlo disponibile per ogni chiamata API. Non esiste un processo specifico, ma in generale, se stai creando un'app web è preferibile aggiungere il token come variabile della sessione per collegarla a una determinata persona; se invece stai creando un'app nativa per computer o mobile usa il datastore che hai a disposizione. Inoltre, l'app deve memorizzare il token e lo user_id in un database per poterlo identificare.

Consulta la nostra nota sulle dimensioni nel documento relativo ai token d'accesso.

Monitoraggio dello stato d'accesso

Di nuovo, la tua app deve memorizzare lo stato d'accesso della persona per evitare di dover effettuare ulteriori chiamate alla finestra di dialogo Accedi. Indipendentemente dalla procedura che sceglierai, adatta il controllo dello stato d'accesso.

Disconnessione delle persone

Puoi disconnettere le persone dalla tua app annullando l'indicatore dello stato d'accesso che hai aggiunto, ad esempio eliminando la sessione che indica se la persona ha effettuato l'accesso. Inoltre, devi rimuovere il token d'accesso memorizzato.

Disconnettere le persone non è come revocare un'autorizzazione di accesso (rimuovendo l'autenticazione concessa in precedenza), operazione che è possibile eseguire separatamente. Pertanto, fai in modo che l'app non reindirizzi automaticamente le persone disconnesse alla finestra di dialogo Accedi.

Rilevamento delle disinstallazioni delle app

Le persone possono disinstallare le app tramite Facebook.com senza interagire con queste ultime. Per aiutarti a rilevare quando si verifica tale situazione, ti consentiamo di fornire un URL di callback per la rimozione dell'autorizzazione, che sarà chiamato ogni volta.

Puoi abilitare una callback per la rimozione dell'autorizzazione tramite la Dashboard gestione app.

Risposta alle richieste di eliminazione dei dati degli utenti

Le persone possono richiedere a un'app di eliminare tutte le informazioni su di loro ricevute da Facebook. Per rispondere a queste richieste, consulta Callback di richiesta di eliminazione dati.