Securing Graph API Requests

    Securing Graph API Requests

    Almost every Graph API call requires an access_token. Malicious developers can steal access tokens and use them to send spam from your app. Facebook has automated systems to detect this, but you can help us secure your app by adding extra parameters to API requests. This document explains how.

    This document covers some of the ways you can improve security in your app using a couple of methods that Facebook offers.

    In this document:

    Verifying Graph API Calls with appsecret_proof

    Graph API calls can be made from clients or from your server on behalf of clients. Calls from a server can be better secured by adding a parameter called appsecret_proof.

    Access tokens are portable. It's possible to take an access token generated on a client by Facebook's SDK, send it to a server and then make calls from that server on behalf of the person. An access token can also be stolen by malicious software on a person's computer or a man in the middle attack. Then that access token can be used from an entirely different system that's not the client and not your server, generating spam or stealing data.

    You can prevent this by adding the appsecret_proof parameter to every API call from a server and enabling the setting to require proof on all calls. This prevents bad guys from making API calls with your access tokens from their servers. If you're using the official PHP SDK, the appsecret_proof parameter is automatically added.

    Generating the proof

    The app secret proof is a sha256 hash of your access token, using the app secret as the key. Here's what the call looks like in PHP:

    $appsecret_proof= hash_hmac('sha256', $access_token, $app_secret);

    Add the parameter

    You add the result as an appsecret_proof parameter to each call you make:

    curl \
  -F 'access_token=<access_token>' \
  -F 'appsecret_proof=<app secret proof>' \
  -F 'batch=[{"method":"GET", "relative_url":"me"},{"method":"GET", "relative_url":"me/friends?limit=50"}]' \
  https://graph.facebook.com

    Require proof on all calls

    In the Advanced section of your app's settings, you can require use of appsecret_proof. When this is enabled, we will only allow API calls that either include appsecret_proof or are made from the same device the token was issued to.

    Once you've changed that setting, an attacker will not be able to use stolen access tokens without access to your app secret.

    Login Security

    There are a large number of other settings you can change to improve the security if your app. Please see our Login Security documentation for a checklist of things you can do.

    It's also worth looking at our access token documentation which covers various architectures and the security trade-offs that you should consider.