Tokens de acesso

Quando alguém se conecta a um aplicativo usando o Login do Facebook, o aplicativo pode obter um token de acesso que fornece acesso temporário e seguro às APIs do Facebook.

Um token de acesso é uma cadeia de caracteres opaca que identifica um usuário, aplicativo ou Página. Ele pode ser usado pelo aplicativo para fazer chamadas da Graph API. Tokens de acesso são obtidos por meio de uma série de métodos, que serão abordados mais adiante neste documento. O token inclui informações sobre quando o token expirará e qual aplicativo gerou o token. Devido às verificações de privacidade, a maioria das chamadas de API no Facebook precisa incluir um token de acesso. Existem diferentes tipos de tokens de acesso para respaldar diferentes casos de uso:

Tipo de token de acesso Descrição

Token de acesso de usuário

O token de usuário é o tipo de token mais comumente usado. Esse tipo de token de acesso é necessário em todos os momentos que o aplicativo chama uma API para ler, modificar ou gravar dados do Facebook de uma pessoa específica em seu nome. Tokens de acesso de usuário são obtidos por meio de uma caixa de diálogo Login e precisam da permissão da pessoa para que seu aplicativo obtenha um.

Token de acesso de aplicativo

Esse tipo de token de acesso é necessário para modificar e ler as configurações do aplicativo. Também pode ser usado para publicar ações da Open Graph. Ele é gerado usando um segredo acordado previamente entre o aplicativo e o Facebook, e é então usado durante as chamadas que alteram as configurações de todo o aplicativo. Você obtém um token de acesso de aplicativo por meio de uma chamada de servidor para servidor.

Token de acesso de página

Esses tokens de acesso são semelhantes aos tokens de acesso de usuário, exceto pelo fato de fornecerem permissão para APIs que leem, escrevem ou modificam os dados pertencentes a uma Página do Facebook. Para obter um token de acesso de página, é necessário obter um token de acesso de usuário e pedir a permissão manage_pages. Depois que você tiver o token de acesso de usuário, poderá então obter o token de acesso de página por meio da Graph API.

Token de cliente

O token de cliente é um identificador que você pode incorporar em aplicativos de desktop e binários móveis nativos para identificar o seu aplicativo. O token de cliente não se destina a ser um identificador secreto porque é incorporado em aplicativos. O token de cliente é usado para acessar as APIs de nível de aplicativo, mas apenas um subconjunto muito limitado. O token de cliente é encontrado no painel de seu aplicativo. Como o token de cliente é usado raramente, não falaremos sobre ele neste documento. Esse assunto é abordado por qualquer documentação sobre a API que usa o token de cliente.

Como gerar tokens de acesso

Tokens de acesso de usuário

Tokens de acesso de aplicativo

Tokens de acesso de página


Tokens de acesso de usuário

Embora cada plataforma gere tokens de acesso por meio de diferentes APIs, todas as plataformas seguem a estratégia básica para obter um token de usuário:

Plataformas diferentes têm diferentes métodos para iniciar esse processo e incluem funcionalidades para gerenciar tokens de acesso em nome do desenvolvedor e permissões concedidas pelas pessoas:

Javascript

O SDK do Facebook para JavaScript obtém e mantém tokens de acesso de usuário automaticamente em cookies de navegador. Você pode recuperar o token de acesso de usuário fazendo uma chamada para FB.getAuthResponse que inclui uma propriedade accessToken dentro da resposta.

Android

Os SDKs do Facebook para Android gerenciam automaticamente tokens de acesso de usuário por meio da classe com.facebook.AccessToken. Você pode aprender mais sobre como obter um token de acesso de usuário implementando o Login do Facebook para Android. Você pode recuperar o token de acesso de usuário inspecionando Session.getCurrentAccessToken.

iOS

Os SDKs do Facebook para iOS gerenciam automaticamente tokens de acesso de usuário por meio da classe FBSDKAccessToken. Você pode aprender mais sobre como obter um token de acesso de usuário implementando o Login do Facebook para iOS. Você pode recuperar o token de acesso inspecionando FBSDKAccessToken.currentAccessToken.

Web (sem JavaScript)

Quando você criar um aplicativo na Web sem SDK do Facebook para JavaScript, será preciso gerar um token de acesso durante as etapas descritas neste documento.

Amostras de código

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 de curto prazo e tokens de longo prazo

Os tokens de acesso de usuário existem em duas formas: tokens de curta duração e tokens de longa duração. Tokens de curta duração têm normalmente uma vida útil de cerca de uma ou duas horas, enquanto tokens de longa duração têm normalmente uma vida útil de cerca de 60 dias. Você não deve contar com essas durações com algo fixo, pois elas podem mudar sem aviso prévio ou expirar mais cedo. Veja mais sob como lidar com erros.

Os tokens de acesso gerados por meio de logon da Web são tokens de curta duração, mas você pode convertê-los em tokens de longa duração fazendo uma chamada de API do lado do servidor, juntamente com seu segredo do aplicativo.

Aplicativos móveis que usam SDKs do Facebook para iOS e Android adquirem tokens de longa duração por padrão.

Aplicativos com Acesso padrão à API de Marketing do Facebook, ao usar tokens de longa duração, receberão tokens de longa duração que não têm tempo de expiração. Esses tokens ainda estão sujeitos à invalidação por outras razões, mas não expirarão exclusivamente com base no tempo. Isso também é verdade sobre os tokens de acesso para Usuários do Sistema no Gerenciador de Negócios.

Tokens são portáteis

Um aspecto importante para entender sobre tokens de acesso é que eles são portáteis. Uma vez que você tem um token de acesso, é possível usá-lo para fazer chamadas de um cliente móvel, um navegador da Web ou de seu servidor para servidores do Facebook. Se um token é obtido em um cliente, você pode enviar esse token para o seu servidor e usá-lo em chamadas de servidor para servidor. Se um token é obtido por meio de uma chamada de servidor, também é possível enviar o token para um cliente e, em seguida, fazer as chamadas a partir do cliente.

Mover tokens entre o seu cliente e o servidor deve ser feito de forma segura, via HTTPS, para garantir a segurança das contas das pessoas. Leia mais sobre as implicações de mover tokens entre seus clientes e seu servidor.

Tokens de acesso de aplicativo

Tokens de acesso de aplicativos são usados​para fazer solicitações para APIs do Facebook em nome de um aplicativo, em vez de um usuário. Pode ser usado para modificar os parâmetros de seu aplicativo, criar e gerenciar usuários de teste ou ler informações de seus aplicativos.

Limitações

Alguns dados de usuário que normalmente seriam visíveis para um aplicativo que está fazendo a solicitação com um token de acesso de usuário nem sempre são visíveis com um token de acesso de aplicativo. Se você está lendo os dados do usuário e utilizando-os em seu aplicativo, é preciso usar um token de acesso de usuário em vez de um token de acesso de aplicativo.

Tokens de acesso de aplicativo são considerados inseguros se o seu aplicativo está definido para Native/Desktop nas Configurações Avançadas de seu Painel do Aplicativo e, portanto, não funcionarão com chamadas de API. Isso ocorre porque supomos que os aplicativos nativos ou de desktop terão o segredo do aplicativo embutido em algum lugar (e, portanto, o token de acesso de aplicativo gerado usando esse segredo não é seguro).

Como gerar um token de acesso de aplicativo

Para gerar um token de acesso de aplicativo, você precisa fazer uma chamada para a Graph API:

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

Essa chamada retornará um token de acesso de aplicativo que pode ser usado no lugar de um token de acesso de usuário para fazer chamadas de API como mencionado acima. Mais uma vez, para a segurança, o token de acesso de aplicativo nunca deve ser codificado em código do lado do cliente. Isso concederia a todas as pessoas que carregassem sua página da Web ou descompilassem seu aplicativo acesso total ao seu segredo do aplicativo e, portanto, a capacidade de modificar seu aplicativo. Isso implica que, na maior parte do tempo, você estará usando tokens de acesso de aplicativo apenas em chamadas de servidor para servidor.

Observe que, por esse pedido usar seu segredo do aplicativo, ele nunca deve ser feito no código do lado do cliente ou em um binário do aplicativo que possa ser descompilado. É importante que o seu segredo do aplicativo nunca seja compartilhado com ninguém. Portanto, esta chamada de API só deve ser feita usando o código do lado do servidor.

Há um outro método para fazer chamadas para a Graph API que não requer o uso de um token de acesso de aplicativo gerado. Basta passar a seu número de identificação do aplicativo e o segredo como o parâmetro access_token quando você fizer uma chamada:

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

A escolha de usar um token de acesso gerado versus esse método depende de onde você escondeu o seu segredo do aplicativo.

Tokens de acesso de página

Tokens de acesso de página são usados em chamadas da Graph API para gerenciar Páginas do Facebook. Para gerar um token de acesso de página, um administrador da página deve conceder uma permissão estendida chamada manage_pages. Quando essa permissão for concedida, você poderá recuperar o token de acesso de página usando um token de acesso do usuário com as permissões necessárias e a seguinte solicitação da Graph API:

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

Essa ação retorna uma lista de páginas que a pessoa administra, junto com outras informações, como a categoria da Página, as permissões que o administrador tem para essa Página e o token de acesso da página:

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

Com um token de acesso de página, você pode realizar chamadas de API em nome de uma Página. Por exemplo, você pode postar uma atualização de status para uma Página (em vez de postar na Linha do Tempo do usuário) ou ler os dados de Informações da Página.

Tokens de acesso de página são únicos para cada Página, administrador e aplicativo.

Administradores da Página desempenham funções diferentes, que são indicadas pela matriz perms retornada, conforme o exemplo acima. A funcionalidade disponível para eles é decidida com base nos valores de perms, que são descritos em Tokens e funções.