Быстрая установка

Добавление системы авторизации Persona на ваш сайт займет всего 5 шагов:

Подключите ЯваСкрипт-библиотеку на ваши страницы.
Добавьте кнопки «Вход» и «Выход».
Отслеживайте события входа и выхода.
Проверьте учетные данные пользователя.
Ознакомьтесь с лучшими примерами.

Установка и настройка займёт у вас всего один вечер, но если вы собираетесь использовать Persona на вашем сайте, пожалуйста, прежде всего уделите минутку и подпишитесь на рассылку Заметки о Persona. Там крайне мало сообщений, она используется только для анонсов изменений или проблем с безопасностью, которые могут неблагоприятно сказаться на работе вашего сайта.

Шаг 1: Подключение библиотеки

Persona разработана так, чтобы быть независимой от обозревателя и хорошо работает во всех основных настольных и мобильных обозревателях. Это возможно благодаря межплатформенной библиотеке Persona, написанной на ЯваСкрипте. После того, как библиотека загружена на вашей странице, вам потребуются следующие функции Persona: (watch(), request(), и logout()), которые будут доступны в глобальном объекте navigator.id.

Чтобы подключить ЯваСкрип-библиотеку Persona, поместите следующий код в головной ярлык head:

<script src="https://login.persona.org/include.js"></script>

Вы должны подключить эту библиотеку, так как она создает функции navigator.id. Потому, что Persona еще находится в разработке, вы не должны самостоятельно изменять файл include.js.

Шаг 2: Добавление кнопок входа и выхода

Потому, что Persona создана как DOM API, Вы должны вызывать функции, когда пользователь нажимает на кнопки входа и выхода на Вашем сайте. Чтобы открыть окно входа через Persona, вызовите функцию navigator.id.request(). Для выхода вызовите navigator.id.logout().

Например:

var signinLink = document.getElementById('signin');
if (signinLink) {
  signinLink.onclick = function() { navigator.id.request(); };
};

var signoutLink = document.getElementById('signout');
if (signoutLink) {
  signoutLink.onclick = function() { navigator.id.logout(); };
};

Как выглядят эти кнопки? Посмотрите эту страницу, там найдете CSS и изображения!

Шаг 3: Отслеживание событий входа и выхода

Для работы Persona вы должны сообщить ей, что делать, когда пользователь осуществляет вход и выход. Для этого нужно вызвать функцию navigator.id.watch(), предоставив ей три параметра:

loggedInEmail – почта текущего пользователя на сайте или null, если его нет. Это значение должно формироваться динамически во время создания страницы.
Функцию, которую следует вызвать при входе пользователя – действие onlogin. Это функция должна принимать один параметр – "заявленный идентификатор", который должен быть проверен.
Функцию, которую следует вызвать при выходе пользователя – действие onlogout. Эта функция работает без каких-либо параметров.

Замечание: Необходимо всегда указывать обе функции (для входа и выхода) – onlogin и onlogout при вызове navigator.id.watch().

Например, если вы думаете что Иван выполнил вход на ваш сайт, вы должны сделать следующее:

var currentUser = '[email protected]';

navigator.id.watch({
  loggedInEmail: currentUser,
  onlogin: function(assertion) {
    // Пользователь выполнил вход! В этом случае нужно:
    // 1. Отправить заявленный идентификатор в бекэнд вашего сайта (серверная часть, прим. переводчика) для проверки и создания сессии.
    // 2. Обновить интерфейс пользователя.
    $.ajax({
      type: 'POST',
      url: '/auth/login', // это URL путь на вашем сайте.
      data: {assertion: assertion},
      success: function(res, status, xhr) { window.location.reload(); },
      error: function(res, status, xhr) { alert("login failure" + res); }
    });
  },
  onlogout: function() {
    // Пользователь выполнил выход! В этом случае нужно:
    // Удалить сессию пользователя с помощью перенаправления или отправки запроса на бекэнд.
    $.ajax({
      type: 'POST',
      url: '/auth/logout', // это URL путь на вашем сайте.
      success: function(res, status, xhr) { window.location.reload(); },
      error: function(res, status, xhr) { alert("logout failure" + res); }
    });
  }
});

В этом примере обе функции onlogin и onlogout отправляют асинхронные POST запросы к бекэнду вашего сайта. Бекэнд в свою очередь осуществляет процедуру входа и выхода пользователя, записывая или удаляя информацию в куки сессии. Далее, если пройдены все проверки, страница перезагружается, отображая новое состояние авторизации.

Вы, конечно, можете использовать AJAX, чтобы реализовать всё без перезагрузки страницы или перенаправлений, однако это не входит в рамки данного учебника.

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

Шаг 4: Проверка пользовательских данных

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

Крайне важно осуществлять такую проверку на стороне сервера, но не с помощью ЯваСкрипт-кода, работающего в обозревателе пользователя, иначе её легко можно подделать. В следующем примере заявка передаётся на сервер методом POST на адрес /api/login с помощью вспомогательной функции jQuery $.ajax().

Как следует делать проверку на сервере при получении заявки? Самый простой способ – использовать службу, предоставляемую Mozilla. Просто отправьте POST запрос с заявкой на адрес https://verifier.login.persona.org/verify указав два параметра:

assertion: заявка-идентификатор, полученный от пользователя.
audience: Адрес хоста и порт вашего сайта. Это информация должна быть записана в вашем бекэнде, ни в коем случае не получайте эти данные из того, что было отправлено пользователем.

Предположим, example.com – это адрес вашего сайта, вы сможете проверить заявку, используя командную строку:

$ curl -d "assertion=<ASSERTION>&audience=https://example.com:443" "https://verifier.login.persona.org/verify"

Если она настоящая, в ответ вы получите примерно такой ответ в формате JSON:

{
  "status": "okay",
  "email": "[email protected]",
  "audience": "https://example.com:443",
  "expires": 1308859352261,
  "issuer": "eyedee.me"
}

Вы можете более подробно ознакомиться со службой проверки, прочитав статью API Проверочной Службы. Примерная реализация /api/login, с использованием Питона, веб-фреймворка Flask, и HTTP-библиотеки Requests, может выглядеть так:

@app.route('/api/login', methods=['POST'])
def login():
    # Запрос должен содержать заявку, которую нам нужно проверить
    if 'assertion' not in request.form:
        abort(400)

    # Отправляем заявку в службу проверки Mozilla.
    data = {'assertion': request.form['assertion'], 'audience': 'https://example.com:443'}
    resp = requests.post('https://verifier.login.persona.org/verify', data=data)

    # Получен ли от службы ответ?
    if resp.ok:
        # Разбираем ответ
        verification_data = json.loads(resp.content)

        # Проверяем, верна ли заявка?
        if verification_data['status'] == 'okay':
            # Осуществляем вход пользователя, устанавливая защищённую куки сессии
            session.update({'email': verification_data['email']})
            return resp.content

    # Что-то пошло не так! Отмена.
    abort(500)

Управление сессиями, вероятно, очень похоже на систему авторизации, которую вы уже используете. Первое основное отличие при проверке идентификатора пользователя в том, что вместо проверки пароля происходит проверка заявки. Второе большое отличие – проверка того, что адрес электронной почты пользователя корректный, путём передачи его в качестве параметра loggedInEmail функции navigator.id.watch().

Выход из системы прост: всё, что нужно – удалить куки сессии пользователя.

Шаг 5: Обзор лучших примеров

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

Возможно, вы захотите написать интеграционные тесты, которые симулируют вход и выход пользователя используя BrowserID, если вы делает сайт, готовый к запуску. Чтобы облегчить этот процесс c Selenium, обратите внимание на библиотеку bidpom. Так же может оказаться полезным сайт personatestuser.org.

Ну и напоследок, не забудьте подписаться на рассылку Заметки о Persona, так вы всегда будете в курсе любых проблем безопасности, а также об обратно несовместимых изменениях в API Persona. Рассылка не будет обременять вас – она используется исключительно для объявлений изменений, которые могут неблагоприятно сказаться на вашем сайте.