Разработка процесса входа вручную

Для мобильных приложений используйте Facebook SDK для iOS и Android, следуя руководствам для соответствующей платформы.

Если же вам нужно реализовать в мобильном или ПК-приложении вход через браузер, не применяя наши SDK, — скажем, в веб-просмотре для нативного приложения для ПК (например, Windows 8), или процесс входа с помощью одного только серверного кода — вы можете сделать это самостоятельно. Для этого нужно использовать функцию перенаправления в браузерах. В этом руководстве описаны все этапы процесса входа и показано, как реализовать их без помощи наших SDK.

Чтобы использовать вход через Facebook в приложении для ПК, нужно встроить в приложение веб-браузер (иногда его называют веб-просмотром), который и будет реализовывать процесс входа.

Проверка статуса входа

Приложения, использующие наши SDK, могут отслеживать вход в приложение с помощью встроенных функций. Во всех других приложениях должен быть собственный механизм, позволяющий запомнить, когда был выполнен вход. Если этот индикатор отсутствует, в приложении будут доступны только функции, не требующие входа. Если человек выполнил выход, приложение в подходящий момент (например, при нажатии кнопки "Вход") должно перенаправить его в диалог входа.

Вход в приложение

Даже если человек не выполнил вход в приложение или на Facebook, с помощью диалога «Вход» вы можете предложить оба варианта входа. Если человек не вошел на Facebook, ему будет предложено сделать это, после чего он перейдет к процедуре входа в приложение. Такие ситуации отслеживаются автоматически, поэтому вам не понадобится ничего настраивать, чтобы реализовать подобный алгоритм.


Вызов диалога входа и настройка URL для перенаправления

Ваше приложение должно инициировать перенаправление к конечной точке, которая вызывает диалог входа:

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

Эта конечная точка имеет следующие обязательные параметры:

  • client_id. ID вашего приложения, указанный в панели приложений.
  • redirect_uri. URL, на который необходимо перенаправить человека после входа. Этот URL будет регистрировать ответ от диалога входа. Если он используется как часть веб-просмотра в приложении для ПК, ему необходимо присвоить значение https://www.facebook.com/connect/login_success.html. Подтвердить, что этот URL задан для вашего приложения, можно в панели приложений. В разделе Продукты в меню навигации слева в панели приложений нажмите Вход через Facebook, а затем выберите Настройки. Проверьте Действительные URI для перенаправления OAuth в разделе Клиентские настройки OAuth.
  • state. Строковое значение, созданное приложением для поддержки состояния между запросом и обратным вызовом. Этот параметр должен использоваться для предотвращения подделки межсайтовых запросов. Он будет возвращен вам в неизменном виде в вашем URI перенаправления.

Например, если ваш запрос входа выглядит так:

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

URI перенаправления будет вызываться так:

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

Кроме того, имеются следующие необязательные параметры:

  • response_type. Указывает, будут ли включены данные ответа в параметры или фрагменты URL при перенаправлении обратно в приложение. О том, какой тип выбрать для своего приложения, читайте в разделе Подтверждение личности. Это может быть:
    • code. Данные ответа включаются в виде параметров URL и содержат параметр code (зашифрованную строку, уникальную для каждого запроса входа). Если этот параметр не указан, по умолчанию используется этот вариант. Он будет особенно полезным, если маркер будет обрабатываться сервером.
    • token. Данные ответа включаются в виде фрагмента URL и содержат маркер доступа. Эту настройку response_type должны использовать приложения для ПК. Она будет особенно полезной, если маркер будет обрабатываться клиентом.
    • code%20token. Данные ответа указываются в виде фрагмента URL и содержат маркер доступа и параметр code.
    • granted_scopes. Возвращает список разделенных запятыми разрешений, предоставленных приложению пользователем во время входа. Может использоваться в сочетании с другими значениями response_type. Если используется со значением token, данные ответа указываются в виде фрагмента URL, в противном случае — в виде параметра URL.
  • scope. Список разделенных запятыми или пробелами разрешений, запрашиваемых у пользователя приложения.
Для приложений Windows 8

Создавая вход для приложения Windows, вы можете использовать в качестве redirect_uriидентификатор безопасности пакета. Вызовите WebAuthenticationBroker.AuthenticateAsync, чтобы открыть диалог входа, и используйте его конечную точку как URI запроса (requestUri). Ниже приведен пример на JavaScript.

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

В этом примере управление возвращается приложению вместе с маркером доступа в случае успешного входа или с ошибкой в случае сбоя.

Обработка ответа диалога «Вход»

К этому моменту человек увидит диалог входа и сможет решить, отменить его или предоставить приложению доступ к своим данным.

Если человек выбирает «OK» в диалоге «Вход», он предоставляет доступ к своему публичному профилю, списку друзей и всем дополнительным Разрешениям, которые запрашивает приложение.

В любом случае браузер возвращает управление приложению и указывает в данных ответа, подключился человек к приложению или отказался от входа. Если ваше приложение использует описанный выше метод перенаправления, к redirect_uri, который возвращается приложением, будут добавлены параметры или фрагменты URL, которые нужно зарегистрировать (согласно выбранному response_type).

В этом руководстве не приводятся конкретные примеры, так как в веб-приложениях могут использоваться самые разные комбинации языков программирования. Однако большинство современных языков могут анализировать URL следующим образом:

JavaScript на стороне клиента может регистрировать фрагменты URL-адреса (например, jQuery BBQ), тогда как параметры URL могут регистрироваться как клиентским, так и серверным кодом (например, $_GET в PHP, jQuery.deparam в jQuery BBQ, querystring.parse в Node.js или urlparse в Python). Microsoft предлагает руководство и пример кода для приложений Windows 8, который позволяет подключиться к сетевому поставщику, в данном случае — к Facebook.

При входе в приложение для ПК Facebook перенаправляет людей с помощью указанного выше redirect_uri и помещает маркер доступа вместе с прочими метаданными (в том числе сроком действия маркера) во фрагмент URI:

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

Ваше приложение должно обнаружить это перенаправление и считать маркер доступа из URI с помощью механизмов используемой операционной системы и среды разработки. После этого можно перейти непосредственно к проверке маркеров доступа.


Отмена входа

Если человек не захотел войти в приложение и нажал кнопку отмены, будет выполнено следующее перенаправление:

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

Подробнее о том, как приложение должно реагировать на отказ от входа, см. в разделе Обработка недостающих разрешений.

Подтверждение личности

Так как в процессе перенаправления из диалога «Вход» к URL, указанным в вашем приложении, используются браузеры, человек может получить прямой доступ к этому URL с помощью поддельных фрагментов или параметров. Если ваше приложение примет эти параметры как действительные, поддельные данные можно будет использовать в приложении с потенциально злонамеренными целями. Таким образом, прежде чем генерировать маркер доступа, следует убедиться, что пользователь приложения и человек, для которого предназначаются данные ответа, — одно и то же лицо. Подтвердить личность можно разными способами в зависимости от полученных ранее данных response_type:

  • Если получен code, его необходимо обменять на маркер доступа с помощью конечной точки. Вызов необходимо передавать с сервера на сервер, так как в нем используется секрет приложения. (Секрет приложения ни в коем случае не должен попасть в клиентский код.)
  • Если получен token, его нужно подтвердить. Отправьте вызов API к проверяемой конечной точке, которая покажет, для кого сгенерирован маркер и каким приложением. Так как для этого вызова API необходимо использовать маркер доступа приложения, никогда не отправляйте этот вызов из клиента. Этот вызов необходимо выполнять с сервера, на котором можно безопасно хранить секрет приложения.
  • Если получены code и token, нужно выполнить обе процедуры.

Помните, что вы также можете сгенерировать собственный параметр state и использовать его с запросами входа, чтобы обеспечить защиту CSRF.

Обмен кода на маркер доступа

Чтобы получить маркер доступа, отправьте запрос HTTP GET к следующей конечной точке OAuth:

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

Эта конечная точка имеет следующие обязательные параметры:

  • client_id. ID вашего приложения
  • redirect_uri. Этот аргумент обязателен и должен совпадать с исходным request_uri, который использовался для запуска процесса входа OAuth.
  • client_secret. Ваш уникальный секрет приложения, который указан в панели приложений. Секрет приложения ни при каких условиях не должен попасть в клиентский код или в двоичные файлы, которые можно декомпилировать. Чрезвычайно важно, чтобы секрет приложения оставался секретом, поскольку это основной элемент, обеспечивающий безопасность вашего приложения и всех его пользователей.
  • code. Параметр, полученный при описанном выше перенаправлении из диалога входа.

Примечание. Начиная с версии 2.3 этот эндпойнт будет возвращать правильный ответ JSON. Если в вашем вызове не указана версия, по умолчанию будет использоваться самая старая из доступных версий.

Ответ

В случае успеха вы получите от конечной точки следующий ответ в формате JSON:

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

В случае неудачи будет получено сообщение с описанием ошибки.

Проверка маркеров доступа

Ваше приложение получит маркер доступа независимо от того, что ему передает диалог входа в качестве response_type: code или token. Вы можете автоматически проверить эти маркеры с помощью конечной точки API Graph:

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

Эта конечная точка принимает следующие параметры:

Ответом на вызов API будет массив JSON с данными о проверенном маркере. Пример:

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

С помощью полей app_id и user_id приложение подтверждает, что маркер доступа для человека и для самого приложения действителен. Полное описание других полей можно найти в этом руководстве.

Проверка разрешений

Чтобы получить список разрешений, которые предоставил или отклонил конкретный человек, вызовите границу контекста /me/permissions. Так ваше приложение может определить, какие из запрошенных разрешений нельзя использовать для конкретного пользователя.

Повторный запрос отклоненных разрешений

«Вход через Facebook» позволяет людям отказаться от предоставления определенных разрешений. Диалог входа включает экран, который выглядит примерно так:

Разрешение public_profile требуется всегда. Оно показано серым цветом, потому что его нельзя удалить.

Но если бы человек в этом примере снял флажок user_likes (отметки "Нравится"), результат проверки /me/permissions на предмет того, какие разрешения предоставлены, выглядел бы так:

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

Обратите внимание, что разрешение user_likes было не предоставлено, а отклонено.

Если вашему приложению отказали в предоставлении разрешений, вы можете запросить их повторно. Подготовьте экран, поясняющий, зачем вам нужно это разрешение, и запросите его повторно. Однако при вызове диалога входа описанным ранее способом это разрешение запрашиваться не будет.

Дело в том, что в случае отказа предоставить разрешение диалог входа не будет запрашивать его повторно, если только вы явным образом не настроите в нем повторный запрос отклоненного разрешения.

Для этого добавьте в URL диалога входа параметр auth_type=rerequest:

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

Этот параметр позволяет заново запросить отклоненное разрешение в диалоге входа.

Сохранение маркеров доступа и статуса входа

К этому моменту человек уже прошел аутентификацию и вошел в приложение. Приложение готово отправлять вызовы API от его лица. Но сначала для этого человека нужно сохранить маркер доступа и состояние входа.

Сохранение маркеров доступа

Приложение должно сохранить маркер доступа, полученный на предыдущем этапе, чтобы к нему можно было обратиться из любой части приложения при отправке вызовов API. Мы рекомендуем при разработке веб-приложения добавить маркер как переменную сеанса, чтобы сопоставлять сеанс браузера с конкретным человеком. При разработке нативного приложения для ПК или мобильного приложения нужно использовать доступное хранилище данных. Кроме того, приложение должно сохранить маркер в базе данных вместе с user_id, чтобы идентифицировать его.

Подробнее о размере маркеров доступа см. здесь.

Отслеживание статуса входа

Приложение должно всегда хранить связанный с человеком статус входа. Это поможет избежать дополнительных вызовов к диалогу входа. Какую бы процедуру вы ни выбрали, обеспечьте надлежащую проверку состояния входа.

Выход из приложения

Чтобы обеспечить выход из приложения, восстановите первичное состояние добавленного индикатора состояния входа. Например, вы можете удалить сеанс, указывающий на выполнение входа. Кроме того, если был сохранен маркер доступа, его необходимо удалить.

Выход из приложения — это не то же самое, что отмена разрешения для входа (удаление ранее предоставленной авторизации), которая может быть выполнена отдельно. Поэтому ваше приложение не должно автоматически возвращать людей, выполнивших выход, к диалогу входа.

Отслеживание удаления приложений

Человек может удалить приложение через Facebook.com, не взаимодействуя с самим приложением. Чтобы отслеживать это, мы разрешаем использовать URL обратного вызова деавторизации, связь с которым будет проверяться при удалении приложения.

Вы можете активировать обратный вызов деавторизации в панели приложений. Просто перейдите в свое приложение, затем выберите Продукты, затем Вход через Facebook и, наконец, Настройки. Для URL обратного вызова деавторизации предусмотрено текстовое поле.

В случае деавторизации на этот URL отправляется подписанный запросHTTP POST. Чтобы узнать, как декодировать запрос и определить ID пользователя, инициировавшего обратный вызов, обратитесь к нашему руководству по анализу подписанных запросов.

Как отвечать на запросы на удаление данных пользователей

Пользователи имеют право запросить удаление из вашего приложения всей информации о них, полученной от Facebook. Информацию о том, как отвечать на такие запросы, см. в этой статье.