Créer manuellement un processus de connexion

La manière la plus simple et la plus rapide d’implémenter la fonctionnalité Facebook Login consiste à utiliser nos SDK officiels pour JavaScript, iOS et Android. Nous vous conseillons de consulter nos guides dédiés à chaque plate-forme.

Toutefois, si vous devez, pour une app, implémenter la connexion dans un navigateur sans passer par nos SDK, comme dans le cas d’un webview pour une app 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 :

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

Vérifier l’état de la connexion

Les apps qui utilisent nos SDK peuvent détecter si un utilisateur s’est déjà connecté à 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, et si aucun indicateur ne permet de le connaître, poursuivre en partant du principe qu’il n’est pas connecté. Si un utilisateur est déconnecté, votre app doit le rediriger vers la boîte de dialogue Login au moment opportun, par exemple lorsqu’il clique sur un bouton Login.

Inviter les utilisateurs à se connecter

Si un utilisateur n’est pas connecté à votre app ni à Facebook, vous pouvez utiliser la boîte de dialogue Login pour l’inviter à se connecter à la fois à l’app 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 app. 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 app doit initier une redirection vers un point de terminaison qui affichera la boîte de dialogue Login :

https://www.facebook.com/v2.11/dialog/oauth?
  client_id={app-id}
  &redirect_uri={redirect-uri}

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

  • client_id. L’ID de votre app, accessible dans votre Espace App.
  • redirect_uri. L’URL vers laquelle vous souhaitez rediriger l’utilisateur 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 app de bureau, vous devez utiliser l’adresse https://www.facebook.com/connect/login_success.html. Vous pouvez confirmer que cette URL correspond à votre app dans l’espace app. Sous Produits dans le menu de navigation de gauche de l’espace app, cliquez sur Facebook Login, puis sur Paramètres. Vérifiez les URI de redirection OAuth valides dans la section Paramètres OAuth clients.
  • state. Une chaîne arbitraire unique créée par votre app pour vous protéger contre le Cross-Site Request Forgery.

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

  • response_type. Ce paramètre détermine si les données de la réponse incluses au moment de la redirection vers l’app se trouvent dans les paramètres ou les fragments d’URL. Consultez la section Confirmer l’identité des utilisateurs pour déterminer le type de données que votre app doit utiliser. Vous pouvez choisir parmi les options suivantes :
    • code. Les 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 demande 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. Les 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. Les 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. Ce type de réponse renvoie une liste de toutes les autorisations accordées à l’app par l’utilisateur 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. Une liste d’autorisations à demander à l’utilisateur de votre app, séparées par des virgules.
Pour les apps sous Windows 8

Si vous développez Login pour une app 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/v2.11/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 app 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 voit la boîte de dialogue Login et peut choisir d’annuler l’opération ou d’autoriser l’app à accéder à ses données.

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

Dans tous les cas, le navigateur revient à l’app et les données indiquant si l’utilisateur s’est connecté ou s’il a annulé l’opération sont incluses à la réponse. Lorsque votre app 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 apps sous Windows 8 qui se connectent à un « fournisseur en ligne ». Dans notre cas, il s’agit de Facebook.

Lorsqu’un utilisateur utilise une app de bureau et se connecte, Facebook le 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 app 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 de votre app 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=The+user+denied+your+request.

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

Confirmer l’identité des utilisateurs

Étant donné que ce flux de redirection passe par une redirection des navigateurs vers des URL dans votre app à 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 app a reconnu ces paramètres comme valides, ces données fabriquées pourraient être utilisées par votre app à des fins potentiellement malveillantes. Par conséquent, votre app doit confirmer que l’utilisateur de l’app 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. Il existe plusieurs façons de confirmer l’identité d’un utilisateur, 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 pour lequel le token a été généré ainsi que l’app l’ayant généré. Étant donné que cet appel d’API nécessite l’utilisation du token d’accès d’une app, 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 demande de connexion pour vous protéger contre tout Cross-Site Request Forgery.

É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/v2.11/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. Vos ID d’app.
  • redirect_uri. Cet argument est requis et doit être identique au request_uri initial que vous avez utilisé lorsque vous avez commencé le processus de connexion OAuth.
  • client_secret. Votre 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 app et de toutes les personnes qui l’utilisent.
  • code. Le paramètre reçu issu de la redirection de la boîte de dialogue Login mentionnée plus haut.

Remarque : à partir de la version v2.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 app 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 :

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, 
        "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 app à vérifier que le token d’accès est valide pour l’utilisateur et votre app. Pour plus de détails sur les autres champs, consultez le guide 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 en particulier. Votre app peut exploiter cette liste pour vérifier les autorisations demandées qu’elle ne peut pas utiliser pour un utilisateur en particulier.

Refaire une demande d’autorisation en cas de refus

Facebook Login permet aux utilisateurs de refuser le partage de certaines autorisations avec votre app. 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 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 redemander une fois à un utilisateur d’accorder à votre app des autorisations qu’il 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 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 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/v2.11/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 s’est authentifié et connecté. Votre app 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’app.

Stocker les tokens d’accès

Une fois que votre app 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’app lors des appels d’API. Aucun processus particulier n’existe pour stocker le token. Si vous développez une app web, nous vous conseillons cependant d’ajouter le token en tant que variable de session afin d’associer cette session de navigateur à un utilisateur en particulier. Si vous développez une app native pour ordinateur de bureau ou mobile, nous vous conseillons d’utiliser le magasin de données auquel votre app peut accéder. Aussi, l’app doit stocker le token dans une base de données avec le user_id afin de l’identifier.

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 app doit stocker l’état de connexion d’un utilisateur, 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 utilisateurs

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

Déconnecter un utilisateur 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 app de manière à ne pas rediriger automatiquement les utilisateurs qui se sont déconnectés vers la boîte de dialogue Login.

Détecter les désinstallations d’apps

Les utilisateurs peuvent désinstaller une app sur Facebook.com sans avoir à interagir avec l’app en question. Pour aider les apps à détecter de telles désinstallations, vous pouvez ajouter une URL de rappel qui sera exécutée pour chaque action de désinstallation.

Vous pouvez activer un rappel de désinstallation depuis l’Espace App. Pour ce faire, depuis votre app, choisissez Produits, Facebook Login, puis Paramètres. Vous y trouverez un champ de texte où vous pouvez ajouter l’URL de rappel de désinstallation.

Chaque fois qu’un utilisateur de votre app la désinstalle, cette URL reçoit un HTTP POST contenant une demande signée. Consultez notre guide sur l’analyse de la demande signée pour savoir comment la décoder et trouver l’identifiant d’utilisateur qui a déclenché le rappel.