GoogleAuth — это серверная библиотека на Java, которая реализует алгоритм одноразового пароля на основе времени (TOTP), описанный в RFC 6238.

Эта реализация основана на коде Google Authenticator на C, который послужил образцом, и была создана на основе кода, опубликованного в блоге Энрико М. Крисостомо.

Для кого предназначена эта библиотека?

Для любого разработчика, который хочет добавить многофакторную аутентификацию TOTP в приложение на Java и нуждается в серверном коде для создания общих секретов TOTP, генерации и проверки паролей TOTP. Пользователи могут использовать совместимые с TOTP токены (например, те, что предоставляют банки) или программное обеспечение для токенов (например, Google Authenticator).

Требования

Минимальная версия Java, необходимая для сборки и использования этой библиотеки, — Java 7.

Установка

Добавьте зависимость в свою среду сборки.

Если вы используете Maven:

<dependency>
  <groupId>com.warrenstrange</groupId>
  <artifactId>googleauth</artifactId>
  <version>1.4.0</version>
</dependency>

Если вы используете Gradle:

 compile 'com.warrenstrange:googleauth:1.4.0'

Необходимые библиотеки будут автоматически добавлены в ваш проект:

• Apache Commons Codec.
• Apache HTTP client.

Клиентские приложения

Можно использовать как клиентские приложения Google Authenticator (доступны для iOS, Android и BlackBerry), так и его модуль PAM для генерации кодов, которые будут проверяться этой библиотекой. Однако эту библиотеку также можно использовать для создания собственных клиентских приложений, если Google Authenticator недоступен на вашей платформе или не может быть использован.

Документация библиотеки

В этой библиотеке есть полная документация JavaDoc и набор тестов JUnit, который можно использовать в качестве примера для большинства целей библиотеки. Также включены источники документации Texinfo, а руководство в формате PDF можно создать с помощью Makefile, созданного Autotools:

• Для начальной загрузки Autotools можно использовать включённый скрипт autogen.sh.

    $ ./autogen.sh

• Настройте и создайте документацию:

    $ ./configure
    $ make pdf

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

Использование

Следующий код создаёт новый набор учётных данных для пользователя. Имя пользователя не предоставляется API, и вызывающий объект должен сохранить его для последующего использования во время авторизации.

GoogleAuthenticator gAuth = new GoogleAuthenticator();
final GoogleAuthenticatorKey key = gAuth.createCredentials();

Пользователю следует предоставить значение общего секрета, возвращаемого

key.getKey()

чтобы новый аккаунт можно было настроить на его токене. Предоставляется удобный метод для простого кодирования секретного ключа и информации об аккаунте в QR-код.

Когда пользователь захочет войти в систему, он предоставит пароль TOTP, сгенерированный его устройством. По умолчанию пароль TOTP представляет собой 6-значное целое число, которое меняется каждые 30 секунд. Можно изменить как длину пароля, так и срок его действия. Однако многие токены, такие как Google Authenticator, используют значения по умолчанию, указанные стандартом TOTP, и не допускают никакой настройки.

Следующий код проверяет действительность указанного пароля по предоставленному секретному ключу в кодировке Base32:

GoogleAuthenticator gAuth = new GoogleAuthenticator();
boolean isCodeValid = gAuth.authorize(secretKey, password);

Поскольку пароли TOTP основаны на времени, важно, чтобы часы сервера и клиента были синхронизированы в пределах допуска, используемого библиотекой. Допуск по умолчанию установлен равным окну размером 3 и может быть переопределён при настройке GoogleAuthenticator. Клиент

Эта библиотека может генерировать коды TOTP для тестирования или для использования в качестве программного клиента.

GoogleAuthenticator gAuth = new GoogleAuthenticator();
int code = gAuth.getTotpPassword(secretKey);

Коды, сгенерированные таким образом, можно использовать в качестве альтернативы кодам, которые были бы сгенерированы приложением Google Authenticator (или другим клиентским устройством).

Скретч-коды

По умолчанию вместе с новым общим секретом генерируется 5 скретч-кодов. Скретч-коды предназначены для обеспечения безопасности на случай, если пользователь потеряет доступ к своему токен-устройству. Скретч-узлы не являются функциональностью, требуемой стандартом TOTP, и разработчик сам решает, следует ли их использовать в своём приложении.

Хранение учётных данных пользователя

Библиотека может помочь с получением и хранением учётных данных пользователей, и предоставляется хук для пользователей, желающих интегрировать эту функциональность. Интерфейс ICredentialRepository определяет контракт между хранилищем учётных данных и этой библиотекой.

Хранилище учётных данных можно настроить несколькими способами:

• Хранилище учётных данных может быть установлено для каждого экземпляра, используя свойство credentialRepository интерфейса IGoogleAuthenticator.

• Библиотека ищет экземпляры этого интерфейса, используя [Java ServiceLoader API][serviceLoader] (представленный в Java 6), то есть сканирует пакет META-INF/services в поисках файла с именем com.warrenstrange.googleauth.ICredentialRepository и, если он найден, загружает перечисленные там классы провайдера.

В интерфейсе ICredentialRepository необходимо реализовать два метода:

• String getSecretKey(String userName).
• void saveUserCredentials(String userName, ...).

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

Следующий код создаёт новый набор учётных данных для пользователя «Bob» и сохраняет их в настроенном экземпляре ICredentialRepository:

GoogleAuthenticator gAuth = new GoogleAuthenticator();
final GoogleAuthenticatorKey key = gAuth.createCredentials("Bob");

Следующий код проверяет действительность указанного кода по отношению к секретному ключу пользователя «Bob», возвращённому настроенным экземпляром ICredentialRepository:

GoogleAuthenticator gAuth = new GoogleAuthenticator();
boolean isCodeValid = gAuth.authorizeUser("Bob", code);

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

java.lang.UnsupportedOperationException: An instance of the
  com.warrenstrange.googleauth.ICredentialRepository service must be
  configured in order to use this feature.

Отчёты об ошибках

Пожалуйста, [прочитайте руководство][pdfdoc] перед тем, как открывать заявку. Если вы прочитали руководство и всё ещё считаете, что наблюдаемое вами поведение является ошибкой, откройте заявку на [github][githubIssues].

Copyright (c) 2013 Warren Strange

Copyright (c) 2014-2019 Enrico M. Crisostomo

Все права защищены.

Распространение и использование в исходных и двоичных формах, с изменениями или без них, разрешено при соблюдении следующих условий:

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

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

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

ЭТО ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ АВТОРАМИ И УЧАСТНИКАМИ «КАК ЕСТЬ» И БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ ГАРАНТИЯМИ ТОВАРНОЙ ПРИГОДНОСТИ И СООТВЕТСТВИЯ ОПРЕДЕЛЁННЫМ ЦЕЛЯМ. НИ В ОДНОМ СЛУЧАЕ АВТОР ИЛИ УЧАСТНИКИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ЗА ЛЮБЫЕ УЩЕРБЫ, ВОЗНИКШИЕ В РЕЗУЛЬТАТЕ ИСПОЛЬЗОВАНИЯ ЭТОГО ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ.