Наши официальные SDK для JavaScript, iOS и Android позволяют без труда реализовать "Вход через Facebook". Мы рекомендуем следовать нашим руководствам — они доступны отдельно для каждой платформы.
Но если вам нужно реализовать в приложении вход через браузер, не применяя наши SDK, — скажем, в веб-представлении для нативного приложения для ПК (например, Windows 8), или процесс входа с помощью одного только серверного кода — вы можете сделать это самостоятельно. Для этого нужно использовать функцию перенаправления в браузерах. В этом руководстве описаны все этапы процесса входа и показано, как реализовать их без помощи наших SDK:
Чтобы использовать "Вход через Facebook" в приложении для ПК, нужно встроить в приложение веб-браузер (иногда его называют веб-представлением), который и будет осуществлять процесс входа.
Приложения, использующие наши SDK, могут отслеживать вход в приложение с помощью встроенных функций. Во всех других приложениях должен быть собственный механизм, позволяющий запомнить, когда был выполнен вход. Если этот индикатор отсутствует, в приложении будут доступны только функции, не требующие входа. Если человек выполнил выход, приложение в подходящий момент должно перенаправить его в диалог "Вход", например при нажатии кнопки "Вход".
Даже если человек не выполнил вход в приложение или на Facebook, с помощью диалога "Вход" вы можете предложить оба варианта входа. Если человек не выполнил вход на Facebook, ему будет предложено войти, после чего он перейдет к процедуре входа в приложение. Такие ситуации отслеживаются автоматически, поэтому вам не понадобится ничего настраивать, чтобы обеспечить подобный алгоритм.
 |  |
Ваше приложение должно инициировать перенаправление к эндпойнту, который вызывает диалог "Вход":
https://www.facebook.com/v3.2/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/v3.2/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, вы можете использовать идентификатор безопасности пакета в качестве redirect_uri. Вызовите WebAuthenticationBroker.AuthenticateAsync, чтобы открыть диалог "Вход", и используйте его эндпойнт как URI запроса (requestUri). Ниже приведен пример в JavaScript.
var requestUri = new Windows.Foundation.Uri(
"https://www.facebook.com/v3.2/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/v3.2/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}
}В случае неудачи будет получено сообщение с объяснением ошибки.
Ваше приложение получит маркер доступа независимо от того, code или token ему передает диалог "Вход" в качестве response_type. Вы можете автоматически проверить эти маркеры в эндпойнте API Graph:
GET graph.facebook.com/debug_token?
input_token={token-to-inspect}
&access_token={app-token-or-admin-token}Этот эндпойнт принимает следующие параметры:
input_token. Маркер для проверки.access_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 было не предоставлено, а отклонено.
Если вам отказали в предоставлении разрешений вашему приложению, вы можете повторно запросить их. Подготовьте экран, поясняющий, зачем вам нужно это разрешение, и запросите его повторно. Но при вызове диалога "Вход", как описывалось ранее это разрешение не будет запрашиваться.
Дело в том, что в случае отказа предоставить разрешение диалог "Вход" не будет запрашивать его повторно, если только вы явно не настроите в нем повторный запрос отклоненного разрешения.
Для этого добавьте параметр auth_type=rerequest в URL диалога "Вход":
https://www.facebook.com/v3.2/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. О том, как отвечать на подобные запросы, см. здесь.