© 2014 - 2024 esia.pro

Инструкция по интеграции модуля авторизации через ЕСИА (Ruby)

1 Общее описание

Библиотека (gem) содержит набор функций реализованных на языке программирования Ruby позволяющих организовать взаимодействие с сервисами Единой системы идентификации и аутентификации (ЕСИА) по протоколу OAuth 2.0. Подробную информацию о данном протоколе и принципах взаимодействия с ЕСИА можно получить в методических рекомендациях по использованию ЕСИА Важно учесть, что библиотека авторизации поставляется в 2-х версиях базовой и расширенной. Основным отличием расширенной версии от базовой является возможность получения дополнительного набора сведений о пользователе (см. Приложение Б - Перечень запрашиваемых областей доступа). Условия поставки базовой или расширенной версии необходимо обговаривать заранее с Вашим персональным менеджером.

2 Перечень поставляемых файлов

• Gemfile - файл, содержащий перечень необходимых гемов;
• Gemfile.lock - файл, сформированный бандлером bundle install, в котором содержится полный перечень зависимостей для данного гема;
• omniauth-esia_oauth.gemspec - файл спецификации гема;
• bin/test.rb - тест для проверки функциональности гема;
• lib/omniauth-esia_oauth.rb - модуль, в котором подключаются все необходимые зависимости;
• lib/omniauth/strategies/esia_oauth.rb - модуль, реализующий взаимодействие с сервисами ЕСИА;
• lib/esia_oauth/
• access_token.rb - модуль, реализующий функции для получения маркера доступа от ЕСИА;
• cryptopro_crypt.rb - модуль, реализующий функции подписания и проверки подписи на основе ГОСТ2012 алгоритмов, используя прямые (системные) вызовы КриптоПРО CSP;
• jigner.rb - модуль, реализующий функции подписания и проверки подписи на основе ГОСТ2012 и RSA алгоритмов, используя сетевые вызовы (по http-протоколу) сервиса подписания Jigner;
• openssl_crypt.rb - модуль, реализующий функции подписания и проверки подписи на основе ГОСТ2012 алгоритмов, используя прямые (системные) вызовы OpenSSL;
• rsa_crypt.rb - модуль, реализующий функции подписания и проверки подписи на основе RSA-алгоритма, используя встроенные функции-обёртки Ruby для работы с OpenSSL;
• utils.rb - модуль, реализующий функции кодирования/декодирования base64 в соответствии с требованиями RFC4684;
• version.rb - модуль, содержащий глобальную константу, определяющую версию гема.

3 Основные функции

Основными функциями библиотеки авторизации являются: - получение авторизационного кода ЕСИА; - обмен авторизационного кода на маркер доступа; - получение данных пользователя из ЕСИА (в приложении Б перечислены скоупы, которые может получать базовая и расширенная версии библиотеки); - выход (логаут) на стороне ЕСИА; - подписание запросов к ЕСИА на основе криптографических средств, установленных на удалённом сервере (взаимодействие с сервисом подписания Jigner).

4 Интеграция библиотеки

Перед началом интеграции необходимо: - выполнить конфигурирование OpenSSL, подключив gost-engine с поддержкой алгоритмов ГОСТ Р 34.10-2012 и ГОСТ Р 34.11- 2012. Если подписание происходит на стороне сервиса Jigner, то OpenSSL настраивать не нужно; - настроить для вашей системы HTTPS (это обязательное требование, поскольку данные между вашей системой и ЕСИА передаются в открытом виде); - выполнить экспорт ключевой пары (сформированной по ГОСТ2012) из криптоконтейнера (экспорт можно сделать с помощью нашей утилитой). Если подписание будет происходить на стороне Jigner, то экспорт делать не нужно; - настроить систему на технологическом портале тестовой/промышленной ЕСИА. На технологическом портале в окне редактирования параметров системы указать URL возврата после авторизации и логаута, а также установить алгоритм подписания запросов GOST3410_2012_256.

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

Шаг 0. Установить необходимые зависимости, описанные в разделе 5.

Шаг 1. Распаковать архив с библиотекой в рабочей директории, в которую она должна быть установлена. Подключить гем в Gemfile

gem 'omniauth-esia_oauth', path: '/<working_directory_path>/omniauth-esia'

Шаг 2. Если для подписания запросов к ЕСИА используется Jigner, то ключевую пару вашей системы необходимо загрузить в криптохранилище сервиса (см. инструкцию по эксплуатации Jigner), в ином случае создайте директорию для хранения сертификатов (в Rails-приложении это может быть config/keys/) и загрузите в неё сертификат и ключ в PEM-формате (для извлечения ключа и сертификата из криптоконтейнера можно воспользоваться нашей утилитой). Удостоверьтесь, что тот же сертификат загружен на технологическом портале тестовой/промышленной ЕСИА.

Шаг 3. В ту же директорию со 2-го шага необходимо положить файл сертификата ЕСИА в PEM формате с именем esia-test.crt или esia-prod.crt в зависимости от окружения (тестовое/промышленное), в котором запускается код.

Шаг 4. ВАЖНО Настроить доступ к директориям для размещения файлов сертификата и ключа таким образом, чтобы их файлы нельзя было получить извне.

Шаг 5. В файле config/initializers/devise.rb задать конфигурационные параметры для библиотеки.

Devise.setup do |config|
  config.omniauth :esia_oauth,
    # redirect_uri: 'http://wifi.rnds.pro/prophet/accounts/auth/esia_oauth/callback',
    # logout_redirect_uri: 'http://wifi.rnds.pro/',
    # client_id: 'PRDT01611',
    scope: 'openid fullname id_doc', # набор скоупов доступный для всех систем, подключаемых к ЕСИА
    #В 2.13 уже нет коротких
    # scope: [
      # 'openid',
      # 'birth_cert_doc', 'birthdate', 'birthplace', 'contacts', 'drivers_licence_doc',
      # 'email', 'foreign_passport_doc', 'fullname', 'gender', 'id_doc', 'inn',
      # 'medical_doc', 'military_doc', 'mobile', 'residence_doc', 'snils',
      # 'temporary_residence_doc', 'vehicles', 'kid_fullname', 'kid_birthdate',
      # 'kid_gender', 'kid_snils', 'kid_inn', 'kid_birth_cert_doc', 'kid_medical_doc',
    # ].join(" "),

    # при crypto_provider = :cryptopro не заполняется
    cert_path: "#{Rails.root}/config/keys/oauth_cert.crt",

    # при crypto_provider = :cryptopro не заполняется
    pkey_path: "#{Rails.root}/config/keys/oauth_secret.key",

    # при crypto_provider = :cryptopro не заполняется
    esia_cert_path: "#{Rails.root}/config/keys/oauth_esia_cert.crt",

    debug: false,
    test: false,
    contacts_info: true,
    addresses_info: true,
    docs_info: true,
    orgs_info: true,
    kids_info: false,
    vehicle_info: true,
    crypto_provider: :rsa #одно из значений :rsa(по умолчанию), :cryptopro, :openssl
    cryptopro_opts: { # заполняется только при crypto_provider = :cryptopro
                      kps: 'CN=test',
                      pin: '123456789',
                      path: nil
    }
    end

Более подробно параметры библиотеки описаны в приложении А.

Шаг 6. В модели пользователя включить модуль :omniauthable для devise

class User < ActiveRecord::Base

  devise :omniauthable

end

Шаг 7. В маршрутах приложения настроить обработчики

devise_for :users, :controllers => {
  omniauth_callbacks: 'users/omniauth_callbacks'
}

devise_scope :user do
  get '/users/logout/:provider', to: 'users/omniauth_callbacks#logout', as: 'omniauth_logout', provider: /esia/
end

Шаг 8. Добавить контроллер для обработки аутентификации и выхода через ЕСИА

class Users::OmniauthCallbacksController < Devise::OmniauthCallbacksController
  
  #хеш с данными полученными от ЕСИА
  def get_auth
    @auth ||= request.env["omniauth.auth"]
    @auth[:info][:snils] =@auth[:info][:snils].to_s.gsub(/[^\d]*/, '').strip if @auth[:info][:snils]
    @auth
  end
  
  #сюда попадаем при любом ответе от ЕСИА
  def esia_oauth

    if get_auth[:info].has_key?(:logout)
      #Выход из ЕСИА прошел успешно
      if get_auth[:info][:logout]
        redirect_to destroy_user_session_path
        return 
      else
        flash[:notice] = "Ошибка выхода из ЕСИА"
        return
      end

      user = User.find_by_name_id(get_auth[:info][:esia_name_id])
      Rails.logger.info "***** Logout User: #{user.inspect}"
      return
    end
    if signed_in?
      #обновляем информацию о пользователе 
      current_user.esia = get_auth
      #сохраняем идентификатор сессии пользователя в базу для дальнейшего LogoutRequest от самой ЕСИА
      current_user.name_id = get_auth[:info][:esia_name_id]
      current_user.save

      #сохраняем идентификатор сессии ЕСИА для дальнейшего запроса LogoutRequest от нас
      session[:esia_session_index] = get_auth[:extra][:esia_session_index]
      redirect_to :back and return
    end
        
    #ищем или создаем пользователя в нашей ИС
    user = User.where(identifier: get_auth.info.userid).first_or_create
    user.esia = get_auth
    user.name_id = get_auth[:info][:esia_name_id]      
    session[:esia_session_index] = get_auth[:extra][:esia_session_index]
    user.save

    flash[:notice] = I18n.t "devise.omniauth_callbacks.success", :kind => "ЕСИА"
    sign_in_and_redirect user, :event => :authentication

    #обрабатываем ошибки если есть
    flash[:notice] = "devise.omniauth_callbacks.error"
    redirect_to root_path
  end

  #сюда попадаем при запросе на выход из ЕСИА от нашей ИС
  def logout
    redirect_to user_omniauth_authorize_path(:esia, logout: true,
      esia_name_id: current_user.name_id,
      esia_session_index: session[:esia_session_index] || "") and return
  end
 
end

5 Зависимости

Библиотека авторизации предъявляет следующие языковые требования

Ruby 2.3

В окружении библиотеки авторизации должна присутствовать утилита

OpenSSL v.1.1.x

которую можно вызвать посредством системного вызова. OpenSSL должна поддерживать алгоритмы ГОСТ2012. Для этого необходимо установить расширение

Gost-engine

В случае использования сервиса подписания запросов Signer (Jigner) его необходимо развернуть и настроить к нему доступ со стороны системы, в которую интегрируется библиотека. Для работы библиотеки авторизации необходимо:

* ruby 2.3.0
* devise 3.5.2
* omniauth 1.9.1
* omniauth-oauth2 1.6.0
* awesome_print 1.8.0
* rsa 0.1.4
* uuid 2.3.9

ПРИЛОЖЕНИЕ А
Описание конфигурационных параметров

Библиотека авторизации принимает на вход набор параметров, описанных в таблице А.1.

Таблица А.1 - Описание параметров

ПРИЛОЖЕНИЕ Б
Перечень запрашиваемых областей доступа

Библиотека авторизации в базовой и расширенной версии запрашивает доступ к разным наборам областей данных (scope) и как следствие получает разные наборы сведений о пользователе. Перечень областей данных (scope) для базовой версии библиотеки приведён в таблице Б.1, а для расширенной версии в таблице Б.2.

Таблица Б.1 - Перечень запрашиваемых областей доступа в базовой версии библиотеки

Таблица Б.2 - Перечень запрашиваемых областей доступа в расширенной версии библиотеки