JSO – OAuth 2.0 Client with Javascript

JSO — это простая и гибкая библиотека OAuth для javascript, которую можно использовать в веб-приложении или нативном мобильном приложении.

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

Особенности

• Реализует OAuth 2.0 Implicit Flow.
• Может также использоваться с OpenID Connect.
• Совместимость с ES6 при загрузке через npm/webpack.
• Также включает версию UMD, упакованную в папку dist/
• Не требуется серверный компонент.
• Может обрабатывать несколько провайдеров одновременно.
• Использует HTML 5.0 localStorage для кэширования токенов доступа. Вам не нужно реализовывать хранилище.
• Можно предварительно получить все необходимые токены с достаточными областями действия, чтобы начать работу, а затем использовать токены для запросов позже. Таким образом, вы можете быть уверены, что вам не придётся никуда перенаправляться в вашей бизнес-логике, потому что вам нужно будет обновить просроченный токен.
• Отличная поддержка областей.
• Кэширует и восстанавливает хэш, ваше приложение не потеряет состояние при отправке пользователя на конечную точку авторизации.
• Предоставляется с простой в использовании обёрткой fetch(), которая берёт на себя всё необходимое для получения токена, а затем возвращает нужные вам данные API.
• Экспериментальная функция: OAuth 2.0 Authorization Code flow.
• Экспериментальная функция: Jquery.ajax()-обёртка, если у вас загружен jquery и вы не хотите требовать или полифилить fetch.

Как использовать

Установите с помощью npm:

npm install jso --save

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

import {JSO, Popup} from 'jso'

let config = {...}
let j = new JSO(config)

Чтобы загрузить javascript, вы можете использовать распространяемый модуль UMD:

<script type="text/javascript" src="dist/jso.js"></script>
<script type="text/javascript">
    var config = {...}
    var j = new jso.JSO(config)
</script>

Тот же пакет доступен через CDN:

<script type="text/javascript" src="https://unpkg.com/jso/dist/jso.js"></script>

Инициализация клиента

Чтобы начать использовать JSO, необходимо инициализировать новый объект JSO с конфигурацией для провайдера OAuth 2.0:

let client = new JSO({
    providerID: "google",
    client_id: "541950296471.apps.googleusercontent.com",
    redirect_uri: "http://localhost:8080/", // URL, куда вы будете перенаправлены обратно, и где вы выполняете функцию обратного вызова().
    authorization: "https://accounts.google.com/o/oauth2/auth",
    scopes: { request: ["https://www.googleapis.com/auth/userinfo.profile"]}
})

Параметры конструктора JSO:

• providerID: ДОПОЛНИТЕЛЬНО Это просто тег имени, который используется для префикса данных, хранящихся в браузере. Это может быть всё, что угодно :)

• client_id: ОБЯЗАТЕЛЬНО Идентификатор клиента, которому доверяет поставщик. Поскольку JSO использует поток предоставления неявных грантов, клиентский секрет не нужен.

• authorization: ОБЯЗАТЕЛЬНО Конечная точка URL-адреса сервера авторизации

• redirect_uri: ДОПОЛНИТЕЛЬНО (может потребоваться поставщику). URI, на который пользователь будет перенаправлен после завершения. Это должен быть тот же URL, на котором представлена страница.

• scopes.require: Контролирует, какие области требуются в запросе авторизации. Этот список используется при просмотре кэшированных токенов, чтобы узнать, хотим ли мы использовать какой-либо из существующих.

• scopes.request: Контролирует, какие области запрашиваются в запросе авторизации. Когда ни один из кэшированных токенов не будет использоваться, и будет запрошен новый, список scopes.request будет включён в запрос авторизации.

• default_lifetime : Секунды с временем жизни по умолчанию для токена доступа. Если установлено значение false, это означает постоянный. По умолчанию — 3600. Это имеет значение только в том случае, если expires_in не был отправлен с сервера, что должно происходить ВСЕГДА.

• permanent_scope: Область, указывающая на то, что срок действия токена доступа бесконечен. Хорошо протестированный)

• response_type: тип ответа по умолчанию для всех запросов авторизации. По умолчанию: token. Может быть переопределён, например, для использования OpenID Connect.

• debug: по умолчанию установлено значение false. Установите значение true, чтобы включить ведение журнала отладки на консоль.

• request: дополнительные параметры запроса, добавленные к запросу. Полезно для добавления всех доступных параметров OpenID Connect.

Обработка ответа, когда пользователь возвращается

На странице (обычно той же), куда пользователь отправляется после авторизации, обычно в конечной точке redirect_uri, вам необходимо вызвать функцию callback() в JSO, чтобы сообщить ей проверить параметры ответа:

client.callback()

Не забудьте запустить функцию callback() рано и до того, как вы используете маршрутизатор и начнёте использовать объект jso для получения данных.

Получение токена

Чтобы получить токен, используйте функцию getToken:

client.getToken(opts)
    .then((token) => {
        console.log("Я получил токен: ", token)
    })

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

Помните, что ВСЕГДА вызывайте функцию callback(), чтобы обработать ответ от сервера OAuth, перед использованием getToken(), иначе вы окажетесь в цикле перенаправления.

Параметры для getToken(opts):

• allowredir: генерирует исключение, если getToken подразумевает перенаправление пользователя. Обычно вы хотели бы использовать checkToken() вместо этого.
• response_type: переопределение для этого конкретного запроса.
• scopes.require: переопределение для этого конкретного запроса.
• scopes.request: переопределение для этого конкретного запроса.

В качестве альтернативы getToken() вы можете проверить, доступен ли токен с помощью checkToken().

let token = client.getToken(opts)
if (token !== null) {
    console.log("Я получил токен: ", token)
}

Параметры для checkToken(opts):

• scopes.require: переопределение для этого конкретного запроса.

Выход из системы

Вы можете стереть все сохранённые токены, чтобы имитировать выход из системы:

client.wipeTokens()

Извлечение данных из защищённой OAuth конечной точки

JSO предоставляет простую оболочку вокруг Javascript Fetch API.

// Инициализация
let config = {...}
let client = new JSO(config)
client.callback()

// Когда ваше приложение хочет получить доступ к защищённым данным
let f = new Fetcher(client)
let url = 'https://some-api.httpjs.net/rest/me'
f.fetch(url, {})
    .then((data) => {
        return data.json()
    })
    .then((data) => {
        console.log("Я получил защищённые данные JSON из API", data)
    })
    .catch((err) => {
        console.error("Ошибка от fetcher", err)
    })

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

// Обеспечение получения токена.
// Перенаправит пользователя для аутентификации, если токен недоступен.
client.getToken({
    scopes: {
        request: ["profile", "restdata", "longterm", "email"]
        require: ["profile", "restdata", "longterm"]
    }
})

FetcherJQuery — это альтернативный интерфейс, который использует jQuery.ajax() вместо fetch(). Рассмотрите FetcherJQuery как бета-версию.

Обратите внимание, что этот класс принимает объект jQuery в качестве второго аргумента конструктора. Аргумент опций выборки предоставляется в качестве опций для jQuery.ajax().

Функция fetch() возвращает Promise, который разрешает данные ответа.