Login do Facebook

Criar manualmente um fluxo de login

No caso de um login baseado no navegador para um app da web ou para desktop sem usar os nossos SDKs, como em um modo de exibição da web para um app nativo para desktop (Windows 8, por exemplo) ou um fluxo de login que usa código inteiramente do lado do servidor, será possível criar um fluxo de login usando redirecionamentos de navegador. Neste guia, apresentaremos todas as etapas do fluxo de login e mostraremos como implementar cada uma sem usar nossos SDKs:

Para usar o Login do Facebook em um app para desktop, é necessário incorporar um navegador da web (também chamado de modo de exibição da web) dentro do app para realizar o processo de login.

Como verificar o status do login

Os apps que usam nossos SDKs podem verificar se alguém já fez login usando funções integradas. Todos os outros apps precisam criar a própria maneira de armazenar tokens de acesso quando um usuário entra e, quando o indicador não está presente, prosseguir supondo que a pessoa esteja desconectada. Se alguém tiver saído, o app deverá redirecionar essa pessoa ao diálogo Entrar no momento certo, por exemplo, ao clicar no botão Entrar.

Como conectar pessoas

Caso alguém não esteja conectado ao seu app ou ao Facebook, use o diálogo Entrar para solicitar que esse usuário faça login nos dois. Se o usuário não estiver conectado ao Facebook, será solicitado que ele entre na plataforma e, depois, no seu app. Isso é detectado automaticamente. Portanto, nenhuma medida complementar é necessária para habilitar esse comportamento.


Como chamar o diálogo Entrar e configurar a URL de redirecionamento

Seu app deve iniciar um redirecionamento para um ponto de extremidade que exibirá o diálogo Entrar:

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

Esse ponto de extremidade tem os seguintes parâmetros obrigatórios:

  • client_id. O ID do app, encontrado no painel do seu app.
  • redirect_uri. A URL para a qual você quer redirecionar a pessoa que faz login novamente. Essa URL capturará a resposta do diálogo Entrar. Caso você esteja usando isso em um modo de exibição da web ou em um app para desktop, defina-a como https://www.facebook.com/connect/login_success.html. Você pode confirmar se essa URL está definida no Painel de Apps. Em Produtos, no menu de navegação esquerdo do Painel de Apps, clique em Login do Facebook e em Configurações. Verifique os URIs de redirecionamento de OAuth válidos na seção Configurações de OAuth do cliente.
  • state. Um valor de string criado pelo seu app para manter o estado entre a solicitação e o retorno de chamada. Esse parâmetro deve ser usado para prevenir a falsificação de solicitação entre sites e será devolvido inalterado no URI de redirecionamento.

Por exemplo, caso sua solicitação de login seja assim:

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

o URI de redirecionamento será chamado desta forma:

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

Há também os seguintes parâmetros opcionais:

  • response_type. Determina se os dados de resposta incluídos quando ocorre o redirecionamento de volta para o app vêm em fragmentos ou parâmetros de URL. Para escolher o tipo que seu app deve usar, consulte a seção Confirmar identidade. Pode ser uma destas opções:
    • code. Os dados de resposta são incluídos como parâmetros de URL e contêm o parâmetro code (uma string criptografada exclusiva para cada solicitação de login). Esse é o comportamento padrão caso o parâmetro não seja especificado. Ele é mais útil quando o token é manipulado pelo seu servidor.
    • token. Os dados de resposta são incluídos como um fragmento de URL e contêm um token de acesso. Os apps para desktop devem usar essa configuração para response_type. É mais útil quando o token é manipulado pelo cliente.
    • code%20token. Os dados de resposta são incluídos como um fragmento de URL e contêm o token de acesso e o parâmetro code.
    • granted_scopes. Retorna uma lista separada por vírgulas de todas as permissões concedidas ao app pelo usuário na hora do login. Pode ser combinado com outros valores de response_type. Quando combinado com token, os dados de resposta são incluídos como um fragmento de URL. Caso contrário, eles serão incluídos como um parâmetro de URL.
  • scope. Uma lista separada por vírgulas ou espaços das permissões a serem solicitadas à pessoa usando seu app.
Para apps do Windows 8

Caso você esteja criando um login para um app Windows, use o identificador de segurança do pacote como o redirect_uri. Dispare o diálogo Entrar fazendo uma chamada a WebAuthenticationBroker.AuthenticateAsync e use o ponto de extremidade desse diálogo como o requestUri. Veja um exemplo no JavaScript:

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

Isso retornará o fluxo de controle para seu app com um token de acesso em caso de sucesso ou de erro em caso de falha.

Como lidar com a resposta ao diálogo Entrar

Nesse ponto do fluxo de login, a pessoa verá o diálogo Entrar e terá a opção de cancelar ou permitir que o app acesse os dados dela.

Caso a pessoa escolha OK no diálogo Entrar, ela concederá acesso ao próprio perfil público, à lista de amigos e quaisquer permissões adicionais que o app solicitar.

Em todos os casos, o navegador retornará ao app e serão incluídos dados de resposta indicando se a pessoa optou por conectar ou cancelar. Quando seu app usa o método de redirecionamento dessa forma, o redirect_uri para o qual seu app retornará será anexado com parâmetros de URL ou fragmentos (de acordo com o response_type escolhido), que devem ser capturados.

Por causa das várias combinações de linguagens de código que podem ser usadas em apps da web, nosso guia não mostra exemplos específicos. Contudo, a maioria das linguagens modernas é capaz de analisar URLs, da seguinte maneira:

O JavaScript do lado do cliente pode capturar fragmentos de URL (por exemplo, jQuery BBQ). Já os parâmetros de URL podem ser capturados por código do lado do cliente e do lado do servidor (por exemplo, $_GET em PHP, jQuery.deparam em jQuery BBQ, querystring.parse em Node.js ou urlparse em Python). A Microsoft fornece um guia e um código de amostra para apps do Windows 8 que se conectam a um "provedor online", nesse caso, o Facebook.

Ao usar um app para desktop e fazer login, o Facebook redireciona as pessoas para o redirect_uri mencionado acima e coloca um token de acesso junto a outros metadados (como o tempo de expiração do token) no fragmento de URI:

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

Seu app precisa detectar esse redirecionamento e ler o token de acesso fora do URI usando os mecanismos fornecidos pelo sistema operacional e pela estrutura de desenvolvimento usada. Você pode pular diretamente para a etapa de Como inspecionar tokens de acesso.


Cancelamento de login

Se as pessoas que usam seu app não aceitarem o diálogo Entrar e clicarem em Cancelar, elas serão redirecionadas para o seguinte:

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

Para saber mais sobre o que os apps devem fazer quando as pessoas se recusam a fazer o login, consulte Como manusear permissões ausentes.

Como confirmar a identidade

Esse fluxo envolve o redirecionamento de navegadores para URLs no seu app a partir do diálogo Entrar. Logo, o tráfego pode acessar essa URL diretamente com fragmentos ou parâmetros inventados. Caso o app presuma que esses são parâmetros válidos, os dados inventados poderão ser usados para fins potencialmente maliciosos. Portanto, confirme que a pessoa usando o app é a mesma para quem você tem dados de resposta antes de gerar um token de acesso para ela. Você pode confirmar a identidade de diferentes formas, dependendo do response_type recebido acima:

  • Quando um code é recebido, ele deve ser trocado por um token de acesso usando um ponto de extremidade. Nesse caso, a chamada deverá ser feita de servidor para servidor, pois envolve a chave secreta do app. (A chave secreta do app nunca deve estar no código do lado do cliente.)
  • É necessário verificar o token quando ele for recebido. Faça uma chamada de API para um ponto de extremidade de inspeção que indicará para quem o token foi gerado e por qual app. Não faça essa chamada de um cliente, pois essa API requer o uso de um token de acesso. Faça essa chamada do servidor, onde é possível armazenar a chave secreta do app com segurança.
  • Quando o code e o token são recebidos, as duas etapas devem ser desempenhadas.

Observe que é possível gerar seu próprio parâmetro de state e usá-lo com a solicitação de login para fornecer proteção CSRF.

Como trocar um código por um token de acesso

Para obter um token de acesso, faça uma solicitação HTTP GET para o seguinte ponto de extremidade do OAuth:

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

Esse ponto de extremidade tem alguns parâmetros obrigatórios:

  • client_id. Os IDs do seu app.
  • redirect_uri. Este argumento é obrigatório e deve ser igual ao request_uri original usado ao iniciar o processo de login do OAuth.
  • client_secret. A única chave secreta do app, exibida no Painel de Apps. Não inclua a chave secreta do app no código do lado do cliente ou em binários que possam ser descompilados. É de extrema importância que ela permaneça completamente secreta, pois é o centro da segurança do seu app e de todas as pessoas que o utilizam.
  • code. O parâmetro recebido do redirecionamento do diálogo Entrar acima.

Observação: a partir da versão 2.3, esse ponto de extremidade retornará uma resposta JSON adequada. Caso sua chamada não especifique uma versão, por padrão, será considerada a versão mais antiga disponível.

Resposta

A resposta que você receberá desse ponto de extremidade será retornada no formato JSON e, no caso de sucesso, será:

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

Caso contrário, você receberá uma mensagem de erro explicativa.

Como inspecionar tokens de acesso

Seu app receberá um token de acesso, independentemente de usar code ou token como response_type do diálogo Entrar. Use o ponto de extremidade da Graph API para realizar verificações automatizadas nesses tokens:

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

Esse ponto de extremidade utiliza os seguintes parâmetros:

  • input_token. O token necessário para inspecionar.
  • access_token Um token de acesso do app ou um token de acesso para um desenvolvedor do app.

A resposta da chamada de API é uma matriz JSON contendo dados sobre o token inspecionado. Por exemplo:

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

Os campos app_id e user_id ajudam seu app a verificar se o token de acesso é válido para a pessoa e para seu app. Para uma descrição completa dos outros campos, consulte o guia Como obter informações sobre os tokens de acesso.

Como verificar permissões

A borda /me/permissions pode ser chamada para recuperar uma lista de permissões concedidas ou recusadas por um determinado usuário. O app pode usá-la para verificar qual das permissões solicitadas não pode ser usada para ele.

Como solicitar novamente permissões recusadas

O Login do Facebook permite que as pessoas recusem o compartilhamento de algumas permissões com seu app. O diálogo Entrar contém uma tela semelhante a esta:

A permissão public_profile é sempre exigida e fica esmaecida porque não pode ser desabilitada.

No entanto, se alguém desmarcar user_likes (curtidas) neste exemplo, marcar /me/permissions para as permissões que foram concedidas resultará em:

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

Observe que user_likes foi recusada, e não concedida.

Não é um problema solicitar de novo que alguém conceda ao app permissões que foram recusadas anteriormente. Mostre uma tela de instrução na qual a pessoa possa conceder a permissão para você e, depois, peça-a novamente. Contudo, se você chamar o diálogo Entrar como antes, essa permissão não será solicitada.

Isso ocorre porque, quando alguém recusa a permissão, o diálogo Entrar não volta a pedir a essa pessoa a menos que você informe de maneira explícita que está solicitando novamente uma permissão que foi recusada.

Você pode fazer isso adicionando o parâmetro auth_type=rerequest à URL do diálogo Entrar:

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

Com isso, o diálogo Entrar solicitará novamente a permissão recusada.

Como armazenar tokens de acesso e status de login

Nesse ponto do fluxo, o usuário está autenticado e conectado. O app está pronto para fazer chamadas à API em nome dessa pessoa. Antes de fazer isso, ele deve armazenar o token de acesso e o status de login da pessoa usando o app.

Como armazenar tokens de acesso

Depois que o app recebe o token de acesso da etapa anterior, o token deve ser armazenado para estar disponível a todas as partes do app durante as chamadas à API. Não há um processo específico, contudo, se você estiver criando um app da web, adicione o token como uma variável de sessão para identificar a sessão do navegador com uma pessoa específica. Se você estiver criando um app nativo para desktop ou um app para celular, use o armazenamento de dados disponível para seu app. Além disso, o app deve armazenar o token em um banco de dados juntamente com o user_id para identificá-lo.

Veja nossa observação sobre o tamanho dos tokens de acesso no documento do token de acesso.

Como verificar o status do login

O app deve armazenar o status de login das pessoas, o que ajuda a evitar chamadas adicionais ao diálogo Entrar. Independentemente do procedimento escolhido, altere sua verificação de status de login para incluir essa configuração.

Como desconectar pessoas

Desconecte pessoas do app desfazendo o status de login que você adicionou, excluindo a sessão que indica que a pessoa está conectada, por exemplo. Remova o token de acesso armazenado também.

Desconectar alguém não é o mesmo que revogar a permissão de login (remover permissão concedida anteriormente), e pode ser feito em separado. Por isso, desenvolva o app de modo a não forçar (de maneira automática) as pessoas que se desconectaram a voltarem para o diálogo Entrar.

Como detectar quando as pessoas desinstalam apps

Não é possível desinstalar um app via Facebook.com sem interagir com ele. Para ajudar os apps a detectarem essa ação, permitimos que eles forneçam uma URL de retorno de chamada de desautorização que será informada sempre que isso acontecer.

É possível habilitar um retorno de chamada de desautorização por meio do Painel de Apps.

Como responder a solicitações para excluir dados de usuário

As pessoas podem solicitar que um app exclua todas as informações deles recebidas pelo Facebook. Para responder a essas solicitações consulte Retorno de chamada de solicitação de exclusão de dados.