Créer manuellement un processus de connexion

Pour une application web ou de bureau, implémenter la connexion dans un navigateur sans passer par nos SDK, comme dans le cas d’un webview pour une application native de bureau (par exemple, sous Windows 8) ou d’un processus de connexion employant un code entièrement côté serveur, vous pouvez créer votre processus de connexion à l’aide de redirections dans le navigateur. Ce guide détaille toutes les étapes du processus de connexion et explique comment mettre en œuvre chacune d’elles sans utiliser nos SDK :

Vérifier l’état de la connexion
Inviter les utilisateur·ices à se connecter
Confirmer l’identité des utilisateur·ices
Stocker les tokens d’accès et l’état de la connexion
Déconnecter les utilisateur·ices
Détecter les désinstallations d’applications
Répondre aux demandes de suppression des données d’utilisateur·ice

Pour utiliser la fonctionnalité Facebook Login dans une application de bureau, vous devez d’abord intégrer un navigateur web (parfois appelé webview) au sein de l’application pour exécuter le processus de connexion.

Vérifier l’état de la connexion

Les applications qui utilisent nos SDK peuvent détecter si un utilisateur ou une utilisatrice s’est déjà connecté·e à l’aide de fonctions intégrées. Toutes les autres apps doivent créer leur propre méthode pour retenir l’état de la connexion d’un utilisateur ou d’une utilisatrice, et si aucun indicateur ne permet de le connaître, poursuivre en partant du principe qu’il ou elle n’est pas connecté·e. Si un utilisateur ou une utilisatrice est déconnecté·e, votre application doit le ou la rediriger vers la boîte de dialogue Login au moment opportun, par exemple lorsqu’il clique sur un bouton Login.

Si un utilisateur ou une utilisatrice n’est pas connecté·e à votre application ni à Facebook, vous pouvez utiliser la boîte de dialogue Login pour l’inviter à se connecter à la fois à l’application et à la plate-forme. S’il n’est pas connecté à Facebook, il sera invité à se connecter, puis redirigé vers le processus de connexion dans votre application. Vous n’avez rien à faire de votre côté pour activer ce comportement, car il s’exécute automatiquement.

Appeler la boîte de dialogue Login et paramétrer l’URL de redirection

Votre application doit initier une redirection vers un point de terminaison qui affichera la boîte de dialogue Login :

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

Ce point de terminaison doit présenter les paramètres suivants :

client_id : ID de votre application, accessible dans votre Espace App
redirect_uri : URL vers laquelle vous souhaitez rediriger l’utilisateur·ice qui se connecte. Cette URL capturera la réponse provenant de la boîte de dialogue Login. Si vous l’utilisez dans un webview au sein d’une application de bureau, vous devez utiliser l’adresse https://www.facebook.com/connect/login_success.html. Vous pouvez confirmer que cette URL correspond à votre application dans l’Espace App. Dans le menu de navigation de gauche de l’Espace App, sous Produits, cliquez sur Facebook Login, puis sur Paramètres. Dans la section Paramètres OAuth clients, vérifiez les URI de redirection OAuth valides.
state : valeur de chaîne créée par votre application pour stabiliser la requête et le rappel. Ce paramètre doit être utilisé pour prévenir la falsification de requête intersite et vous sera renvoyé intact dans votre URI de redirection.

Par exemple, si votre requête de connexion ressemble à :

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

alors votre URI de redirection est appelée avec :

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

Le point de terminaison peut également présenter les paramètres facultatifs suivants :

response_type : détermine si les données de réponse incluse lors de la redirection vers l’application se trouve dans les paramètres ou les fragments d’URL. Consultez la section Confirmer l’identité des utilisateur·ices pour déterminer le type de données que votre application doit utiliser. Vous pouvez choisir parmi les options suivantes :
- code : données de réponse sont incluses en tant que paramètres d’URL et contiennent un paramètre code (une chaîne chiffrée distincte pour chaque requête de connexion). Il s’agit du comportement par défaut si ce paramètre n’est pas spécifié. Il convient particulièrement si votre serveur gère le token.
- token : données de réponse sont incluses en tant que fragment d’URL et contiennent un token d’accès. Les apps de bureau doivent utiliser ce paramètre pour response_type. Il convient particulièrement si le client gère le token.
- code%20token : données de réponse sont incluses en tant que fragment d’URL et contiennent à la fois un token d’accès et le paramètre code.
- granted_scopes : renvoie une liste de toutes les autorisations accordées à l’application par l’utilisateur·ice au moment de la connexion, séparées par des virgules. Vous pouvez l’utiliser avec d’autres valeurs response_type. S’il est utilisé avec la valeur token, les données de réponse sont incluses en tant que fragment d’URL. Autrement, elles sont incluses en tant que paramètre d’URL.
scope : liste d’autorisations à demander à l’utilisateur·ice de votre application, séparées par des virgules ou des espaces.

Applications sous Windows 8

Si vous développez Login pour une application Windows, vous pouvez utiliser l’Identificateur de sécurité du package comme redirect_uri. Appelez WebAuthenticationBroker.AuthenticateAsync pour faire apparaître la boîte de dialogue Login et utilisez le point de terminaison « boîte de dialogue Login » en tant que requestUri. Voici un exemple dans JavaScript :

var requestUri = new Windows.Foundation.Uri(
  "https://www.facebook.com/v21.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
  }
);

Cette opération permet de renvoyer le flux de contrôle vers votre application avec un token d’accès en cas de réussite, ou avec une erreur en cas d’échec.

Gérer la réponse de la boîte de dialogue Login

À cette étape du processus de connexion, l’utilisateur·ice voit la boîte de dialogue Login et peut choisir d’annuler l’opération ou d’autoriser l’application à accéder à ses données.

Si l’utilisateur·ice de l’application clique sur OK dans la boîte de dialogue Login, il ou elle donne à votre application l’autorisation d’accéder à son profil public et à sa liste d’amis, ainsi que toute autre autorisation supplémentaire demandée par votre application.

Dans tous les cas, le navigateur revient à l’application et les données indiquant si l’utilisateur ou l’utilisatrice s’est connecté·e ou a annulé l’opération sont incluses à la réponse. Lorsque votre application utilise la méthode de redirection ci-dessus, le redirect_uri auquel elle renvoie inclut les paramètres ou fragments d’URL (en fonction du response_type choisi) qui doivent être capturés.

Puisque différentes combinaisons de langages de code peuvent être utilisées dans les apps web, notre guide ne contient aucun exemple particulier. Néanmoins, la plupart des langages modernes peuvent analyser les URL :

Le langage JavaScript côté client peut capturer des fragments d’URL (par exemple, jQuery BBQ), tandis que les paramètres d’URL peuvent être capturés à la fois par un code côté client et côté serveur (par exemple, $_GET dans le langage PHP, jQuery.deparam dans jQuery BBQ, querystring.parse dans Node.js ou urlparse dans le langage Python). Microsoft propose un guide accompagné d’un exemple de code pour les applications sous Windows 8 qui se connectent à un « fournisseur en ligne ». Dans notre cas, il s’agit de Facebook.

Lorsqu’un utilisateur ou une utilisatrice se connecte à partir d’une application de bureau, Facebook le ou la redirige vers le redirect_uri mentionné ci-dessus et place un token d’accès avec d’autres métadonnées (par exemple, l’heure d’expiration du token) dans le fragment d’URI :

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

Votre application doit détecter cette redirection, puis lire le token d’accès dans l’URI à l’aide de mécanismes fournis par l’OS et la structure de développement que vous utilisez. Vous pouvez alors directement passer à l’étape Inspecter les tokens d’accès.

Connexion annulée

Si l’utilisateur·ice de votre application ne souhaite pas utiliser la boîte de dialogue Login et clique sur Annuler, il sera redirigé vers :

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

Consultez la rubrique Gérer les autorisations manquantes pour en apprendre davantage sur ce que les applications doivent faire lorsqu’un utilisateur ou une utilisatrice refuse de se connecter.

Confirmer l’identité des utilisateur·ices

Étant donné que ce flux de redirection passe par une redirection des navigateurs vers des URL dans votre application à partir de la boîte de dialogue Login, le trafic peut théoriquement accéder directement à ces URL avec des fragments ou des paramètres fabriqués. Si votre application a reconnu ces paramètres comme valides, ces données fabriquées pourraient être utilisées par votre application à des fins potentiellement malveillantes. Par conséquent, votre application doit confirmer que l’utilisateur·ice de l’application correspond à la personne pour laquelle vous avez des données de réponse avant de générer un token d’accès pour cet utilisateur ou cette utilisatrice. Il existe plusieurs façons de confirmer l’identité d’un utilisateur ou une utilisatrice, selon le response_type reçu ci-dessus :

Lorsque le code est reçu, il doit être échangé contre un token d’accès à l’aide d’un point de terminaison. L’appel doit être effectué de serveur à serveur étant donné qu’il nécessite l’utilisation de votre clé secrète. (Votre clé secrète ne doit jamais se retrouver dans le code client.)
Lorsque le token est reçu, il doit faire l’objet d’une vérification. Vous devez passer un appel d’API vers un point de terminaison d’inspection qui indiquera l’utilisateur ou l’utilisatrice pour lequel ou laquelle le token a été généré ainsi que l’application l’ayant généré. Étant donné que cet appel d’API nécessite l’utilisation du token d’accès d’une application, ne passez jamais cet appel depuis un client. Passez-le depuis un serveur sur lequel vous pouvez stocker votre clé secrète en toute sécurité.
Lorsque le code et le token sont tous les deux reçus, vous devez effectuer les deux opérations ci-dessus.

Notez que vous pouvez également générer votre propre paramètre state et l’utiliser avec votre requête de connexion pour vous protéger contre toute falsification de requête intersites (CSRF).

Échanger le code contre un token d’accès

Pour obtenir un token d’accès, passez un appel HTTP GET au point de terminaison OAuth suivant :

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

Ce point de terminaison doit présenter les paramètres suivants :

client_id : ID de votre application
redirect_uri : argument requis, qui doit être identique au request_uri initial que vous avez utilisé lorsque vous avez commencé le processus de connexion OAuth.
client_secret : clé secrète unique, accessible dans l’Espace App. Cette clé secrète ne doit jamais être intégrée au code côté client ni à des fichiers binaires pouvant être décompilés. Elle doit absolument rester secrète étant donné qu’elle joue un rôle prépondérant dans la protection de votre application et de toutes les personnes qui l’utilisent.
code : paramètre reçu issu de la redirection de la boîte de dialogue Login mentionnée plus haut.

Remarque : à partir de la version 2.3, ce point de terminaison renverra une réponse JSON correcte. Si votre appel n’indique aucune version spécifique, la version la plus ancienne sera choisie par défaut.

Réponse

La réponse que vous recevez de ce point de terminaison est renvoyée au format JSON. Si le renvoi s’est bien déroulé, il s’agit de :

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

Si ce n’est pas le cas, vous recevez un message d’erreur expliquant la raison de l’échec.

Inspecter les tokens d’accès

Que votre application utilise ou non le code ou le token en tant que response_type de la boîte de dialogue Login, elle reçoit un token d’accès. Vous pouvez effectuer des vérifications automatisées de ces tokens avec un point de terminaison de l’API Graph :

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

Ce point de terminaison doit présenter les paramètres suivants :

input_token : token à inspecter.
access_token : token d’accès d’une application ou token d’accès pour un développeur de l’application.

La réponse de l’appel d’API prend la forme d’un tableau JSON contenant des données sur le token inspecté. Par exemple :

{
    "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"
    }
}

Les champs app_id et user_id aident votre application à vérifier que le token d’accès est valide pour l’utilisateur·ice et votre application. Pour plus de détails sur les autres champs, consultez le guide expliquant comment obtenir des infos sur les tokens d’accès.

Vérifier les autorisations

Vous pouvez appeler l’arête /me/permissions pour récupérer une liste des autorisations ayant été accordées ou refusées par un utilisateur ou une utilisatrice en particulier. Votre application peut exploiter cette liste pour vérifier les autorisations demandées qu’elle ne peut pas utiliser pour un utilisateur ou une utilisatrice en particulier.

Redemander une autorisation refusée

Facebook Login permet aux utilisateur·ices de refuser de partager certaines autorisations avec votre application. La boîte de dialogue Login contient une fenêtre ressemblant à ceci :

L’autorisation public_profile est toujours requise et apparaît en gris, car elle ne peut pas être désactivée.

Toutefois, si un utilisateur ou une utilisatrice venait à décocher user_likes (mentions J’aime) dans cet exemple, vous obtiendriez le résultat ci-après en appelant /me/permissions pour vérifier les autorisations accordées :

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

Notez que l’autorisation user_likes n’a pas été accordée, mais bien refusée.

Vous pouvez demander une nouvelle fois à une personne d’accorder à votre application des autorisations qu’elle a refusées. Avant de refaire une demande, nous vous conseillons tout de même d’ajouter une fenêtre expliquant les raisons pour lesquelles l’utilisateur·ice devrait vous accorder ces autorisations. Cependant, si vous appelez la boîte de dialogue Login en suivant la méthode précédente, les autorisations ne seront pas demandées.

En effet, à partir du moment où un utilisateur ou une utilisatrice refuse une autorisation, la boîte de dialogue Login ne la redemande plus, à moins que vous ne lui indiquiez de manière explicite que vous souhaitez à nouveau la demander.

Pour ce faire, ajoutez le paramètre auth_type=rerequest à l’URL de votre boîte de dialogue Login :

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

La boîte de dialogue Login fera alors une nouvelle demande pour l’autorisation refusée.

Stocker les tokens d’accès et l’état de la connexion

À ce stade du processus, un utilisateur ou une utilisatrice s’est authentifié·e et connecté·e. Votre application est prête à passer des appels d’API en son nom. Néanmoins, il faut d’abord stocker le token d’accès et l’état de la connexion de la personne qui utilise l’application.

Stocker les tokens d’accès

Une fois que votre application a reçu le token d’accès de l’étape précédente, ce dernier doit être stocké afin de le rendre disponible pour toutes les parties de l’application lors des appels d’API. Aucun processus particulier n’existe pour stocker le token. Si vous développez une application web, nous vous conseillons cependant d’ajouter le token en tant que variable de session afin d’associer cette session de navigateur à un utilisateur ou une utilisatrice en particulier. Si vous développez une application native de bureau ou mobile, nous vous conseillons d’utiliser le magasin de données auquel votre application peut accéder. Aussi, l’application doit stocker le token dans une base de données avec le user_id afin d’identifier l’utilisateur·ice.

Veuillez lire notre remarque à propos de la taille des tokens d’accès dans le document sur les tokens d’accès.

Suivre l’état de la connexion

Là aussi, votre application doit stocker l’état de connexion d’un utilisateur ou d’une utilisatrice, afin de ne pas avoir à passer des appels supplémentaires vers la boîte de dialogue Login. Quelle que soit la procédure que vous avez choisie, modifiez votre méthode de vérification de l’état de la connexion pour qu’il soit pris en compte.

Déconnecter les utilisateur·ices

Vous pouvez déconnecter un utilisateur ou une utilisatrice de votre application en retirant tout indicateur d’état de la connexion que vous avez ajouté (par exemple, en supprimant la session indiquant qu’un utilisateur ou une utilisatrice est connecté·e). Nous vous conseillons également de retirer le token d’accès stocké.

Déconnecter un utilisateur ou une utilisatrice et révoquer des autorisations de connexion (suppression d’une authentification préalablement accordée) sont deux opérations bien différentes pouvant être exécutées séparément. Par conséquent, configurez votre application de manière à ne pas rediriger automatiquement les utilisateur·ices qui se sont déconnecté·es vers la boîte de dialogue Login.

Détecter les désinstallations d’applications

Les utilisateur·ices peuvent désinstaller une application sur Facebook.com sans avoir à interagir avec l’application en question. Pour aider les applications à détecter de telles désinstallations, nous les autorisons à fournir une URL de rappel d’annulation d’autorisation qui sera exécutée pour chaque action de désinstallation.

Vous pouvez activer un rappel d’annulation d’autorisation dans Espace App.

Répondre aux demandes de suppression des données d’utilisateur·ice

Les utilisateur·ices peuvent demander à une application de supprimer toutes les données les concernant transmises via Facebook. Pour répondre à ces demandes, consultez Rappel de demande de suppression de données.

Créer manuellement un processus de connexion

Vérifier l’état de la connexion

Inviter les utilisateur·ices à se connecter

Appeler la boîte de dialogue Login et paramétrer l’URL de redirection

Applications sous Windows 8

Gérer la réponse de la boîte de dialogue Login

Connexion annulée

Confirmer l’identité des utilisateur·ices

Échanger le code contre un token d’accès

Inspecter les tokens d’accès

Vérifier les autorisations

Redemander une autorisation refusée

Stocker les tokens d’accès et l’état de la connexion

Stocker les tokens d’accès

Suivre l’état de la connexion

Déconnecter les utilisateur·ices

Détecter les désinstallations d’applications

Répondre aux demandes de suppression des données d’utilisateur·ice