Tokens d’accès

Lorsqu’une personne se connecte avec une app à l’aide de Facebook Login, l’app peut obtenir un token d’accès qui fournit un accès provisoire et sécurisé aux API Facebook.

Un token d’accès est une chaîne opaque qui identifie un utilisateur, une app ou une Page, et que l’app peut utiliser pour passer des appels de l’API Graph. Plusieurs méthodes permettent d’obtenir des tokens d’accès. Nous les aborderons toutes dans ce document. Le token contient notamment sa date d’expiration et le nom de l’app qui l’a généré. La plupart des appels d’API sur Facebook doivent contenir un token d’accès, en raison des contrôles de confidentialité. Il existe différents types de tokens d’accès pour prendre en charge les divers cas d’utilisation :

Type de token d’accès Description

Token d’accès utilisateur

Le token utilisateur est le plus fréquemment utilisé. Ce type de token d’accès est nécessaire chaque fois que l’app appelle une API pour lire, modifier ou écrire les données Facebook d’une personne en son nom. Les tokens d’accès utilisateur s’obtiennent généralement par une boîte de dialogue Login demandant à l’utilisateur d’autoriser votre app à obtenir ces tokens.

Token d’accès d’app

Ce type de token d’accès est nécessaire pour modifier et lire les paramètres de l’app. Il peut aussi être utilisé pour publier des actions Open Graph. Il est généré à l’aide d’une clé secrète convenue à l’avance entre l’app et Facebook, et utilisé lors des appels qui modifient des paramètres dans toute l’app. Les tokens d’accès d’app s’obtiennent au moyen d’un appel de serveur à serveur.

Token d’accès de Page

Ces tokens d’accès sont similaires aux tokens d’accès utilisateur, sauf qu’ils donnent l’autorisation aux API pour lire, écrire ou modifier les données appartenant à une Page Facebook. Pour obtenir un token d’accès de Page, vous devez d’abord obtenir un token d’accès utilisateur et demander l’autorisation manage_pages. Une fois que vous avez obtenu le token d’accès utilisateur, vous pouvez obtenir le token d’accès de Page au moyen de l’API Graph.

Token client

Le token client est un identifiant que vous pouvez intégrer aux fichiers binaires mobiles natifs ou aux apps pour ordinateur de bureau afin d’identifier votre app. Le token client n’est pas un identifiant secret. En effet, il est intégré aux apps. Il sert à accéder aux API au niveau de l’app, mais seulement à un sous-ensemble très limité. Le token client se trouve dans votre Espace App. Puisque le token client n’est que rarement utilisé, nous ne l’aborderons pas en détail dans ce document. En revanche, le token client est abordé dans toute documentation associée aux API qui l’utilisent.

Générer des tokens d’accès

- Tokens d’accès utilisateur

- Tokens d’accès d’app

- Tokens d’accès de Page


Tokens d’accès utilisateur

Bien que chaque plate-forme génère des tokens d’accès au moyen de différentes API, toutes les plates-formes suivent la même stratégie de base pour obtenir des tokens utilisateur :

Les diverses plates-formes utilisent différentes méthodes pour démarrer ce processus et incluent une fonctionnalité pour gérer les tokens d’accès au nom du développeur et de la personne qui accorde les autorisations :

JavaScript

Le SDK Facebook pour JavaScript obtient et conserve automatiquement les tokens d’accès utilisateur dans les cookies du navigateur. Vous pouvez récupérer le token d’accès utilisateur en passant un appel FB.getAuthResponse, dont la réponse inclut une propriété accessToken.

Android

Les SDK Facebook pour Android gèrent automatiquement les tokens d’accès utilisateur par l’intermédiaire de la classe com.facebook.AccessToken. Vous pouvez en apprendre davantage sur l’obtention d’un token d’accès utilisateur en implémentant Facebook Login pour Android. Vous pouvez récupérer le token d’accès utilisateur en inspectant Session.getCurrentAccessToken.

iOS

Les SDK Facebook pour iOS gèrent automatiquement les tokens d’accès utilisateur par l’intermédiaire de la classe FBSDKAccessToken. Vous pouvez en apprendre davantage sur l’obtention d’un token d’accès utilisateur en implémentant Facebook Login pour iOS. Vous pouvez récupérer le token d’accès en inspectant FBSDKAccessToken.currentAccessToken.

Web (sans JavaScript)

Lorsque vous créez une app sur le Web sans le SDK Facebook pour JavaScript, vous devez générer un token d’accès suivant les étapes décrites dans ce document.

Exemples de code

Android

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    FacebookSdk.sdkInitialize(this.getApplicationContext());
    accessToken = AccessToken.getCurrentAccessToken();
}

iOS

- (void)viewDidLoad
{
  [super viewDidLoad];
  NSString *accessToken = [FBSDKAccessToken currentAccessToken];
}

JavaScript (Web)

FB.getLoginStatus(function(response) {
  if (response.status === 'connected') {
    var accessToken = response.authResponse.accessToken;
  } 
} );

Tokens à court terme et tokens à long terme

Les tokens d’accès utilisateur se présentent sous deux formes : les tokens de courte durée et ceux de longue durée. Généralement, les tokens de courte durée sont valides pendant une heure ou deux, tandis que les tokens de longue durée sont valides pendant environ 60 jours. Ne prenez pas ces durées comme acquises, car les tokens peuvent expirer plus tôt et ces durées peuvent varier sans préavis. Apprenez-en davantage dans la rubrique Gestion des erreurs.

Les tokens d’accès générés par une connexion web sont de courte durée, mais vous pouvez les convertir en tokens de longue durée en passant un appel d’API côté serveur avec votre clé secrète.

Les apps mobiles qui utilisent les SDK Facebook pour iOS et Android obtiennent des tokens de longue durée par défaut.

Les apps disposant d’un accès standard à l’API Marketing de Facebook reçoivent des tokens d’accès de longue durée qui n’ont pas de date d’expiration. Ces tokens peuvent toutefois faire l’objet d’une invalidation pour d’autres raisons, mais ils n’expireront pas pour des raisons de durée uniquement. Cela est aussi valable pour les tokens d’accès des utilisateurs système dans Business Manager.

Les tokens sont portables

La portabilité est une caractéristique essentielle des tokens d’accès. Une fois que vous avez obtenu un token d’accès, vous pouvez l’utiliser pour passer des appels depuis un client mobile, un navigateur web ou votre serveur vers les serveurs de Facebook. Si vous obtenez un token par l’intermédiaire d’un client, vous pouvez le transférer vers votre serveur et l’utiliser dans les appels de serveur à serveur. Si vous obtenez un token par un appel de serveur, vous pouvez aussi le transférer vers un client et passer les appels depuis ce client.

Déplacez les tokens entre votre client et votre serveur en toute sécurité par un protocole HTTPS afin de protéger les comptes des utilisateurs. Apprenez-en davantage sur les conséquences du déplacement de tokens entre vos clients et votre serveur.

Tokens d’accès d’app

Les tokens d’accès d’app servent à envoyer des requêtes aux API Facebook au nom d’une app plutôt que d’un utilisateur. Ces tokens peuvent servir à modifier les paramètres de votre app, à créer et à gérer des utilisateurs tests ou à lire les statistiques concernant votre app.

Restrictions

Certaines données d’utilisateur qui sont visibles pour une app envoyant une requête avec un token d’accès utilisateur ne le sont pas toujours avec un token d’accès d’app. Si vous lisez et utilisez les données de l’utilisateur dans votre app, utilisez un token d’accès utilisateur plutôt qu’un token d’accès d’app.

Les tokens d’accès d’app sont considérés comme non sécurisés si votre app est définie sur Native/Desktop dans les paramètres avancés de votre Espace App, et ils ne fonctionneront donc pas avec les appels d’API. En effet, nous supposons que la clé secrète est intégrée aux apps natives ou pour ordinateur de bureau (par conséquent, le token d’accès de l’app généré à l’aide de cette clé n’est pas sécurisé).

Générer un token d’accès d’app

Pour générer un token d’accès d’app, vous devez passer un appel de l’API Graph :

GET /oauth/access_token
    ?client_id={app-id}
    &client_secret={app-secret}
    &grant_type=client_credentials

Cet appel renvoie un token d’accès d’app qui peut être utilisé à la place du token d’accès utilisateur pour passer des appels d’API, comme mentionné précédemment. Une fois de plus, pour des raisons de sécurité, un token d’accès d’app ne doit jamais être codé en dur dans le code côté client. Un tel codage permettrait à n’importe quelle personne ayant chargé votre page web ou décompilé votre app d’avoir un accès complet à votre clé secrète, et donc de modifier votre app. Cela signifie que vous devez, la plupart du temps, utiliser les tokens d’accès d’app uniquement dans les appels de serveur à serveur.

Remarque : étant donné que cette requête utilise votre clé secrète, elle ne doit jamais être envoyée dans un code côté client ou dans un fichier binaire d’app qui pourrait être décompilé. Il est essentiel de ne jamais communiquer votre clé secrète à qui que ce soit. Par conséquent, cet appel d’API doit être passé uniquement avec un code côté serveur.

Il existe une autre méthode pour passer des appels vers l’API Graph et qui ne nécessite aucun token d’accès généré. Vous pouvez simplement faire passer votre ID d’app et votre clé secrète en tant que paramètre access_token lorsque vous passez l’appel :

https://graph.facebook.com/endpoint?key=value&access_token=app_id|app_secret

Vous devez décider d’utiliser un token d’accès généré ou de suivre cette méthode en fonction de l’endroit où vous cachez votre clé secrète.

Tokens d’accès de Page

Les tokens d’accès de Page sont utilisés dans les appels de l’API Graph pour gérer les Pages Facebook. Pour générer un token d’accès de Page, un administrateur de la Page doit accorder une autorisation étendue appelée manage_pages. Une fois cette autorisation accordée, vous pouvez récupérer le token d’accès de la Page à l’aide d’un token d’accès utilisateur avec les autorisations requises et de la requête d’API Graph suivante :

GET /me/accounts HTTP/1.1
Host: graph.facebook.com

Cette action renvoie une liste de Pages que cette personne gère, ainsi que d’autres informations sur la Page comme la catégorie de la Page, les autorisations de l’administrateur sur cette Page et le token d’accès de la Page :

{
  "data": [
    {
      "category": "Product/service",
      "name": "Sample Page",
      "access_token": "{access-token}",
      "id": "1234567890",
      "perms": [
        "ADMINISTER",
        "EDIT_PROFILE",
        "CREATE_CONTENT",
        "MODERATE_CONTENT",
        "CREATE_ADS",
        "BASIC_ADMIN"
      ]
    }, 
}

Avec un token d’accès de Page, vous pouvez émettre des appels API au nom d’une Page. Par exemple, vous pouvez publier une mise à jour de statut sur une Page (plutôt que sur le journal de l’utilisateur) ou lire les données des Statistiques de la Page.

Les tokens d’accès de Page sont propres à chaque Page, chaque administrateur et chaque app.

Les administrateurs de Page jouent différents rôles, indiqués par le lot perms renvoyé, comme dans l’exemple ci-dessus. Les fonctionnalités disponibles pour ces administrateurs sont déterminées par les valeurs perms, qui sont décrites dans la section Tokens et rôles.