omniauth

Omniauth: стандартизированная аутентификация с несколькими проваторами

Это документация для ветви Omniauth в разработке. Вы можете найти документацию для последнего стабильного выпуска здесь

Введение

Omniauth-это библиотека, которая стандартизирует аутентификацию с несколькими проваленными для веб-приложений. Он был создан, чтобы быть мощным, гибким и делать как можно меньше. Любой разработчик может создавать стратегии для Omniauth, которые могут аутентифицировать пользователей через разрозненные системы. Стратегии Omniauth были созданы для всего, от Facebook до LDAP.

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

Одна стратегия, называемая Developer , включена в Omniauth и предоставляет совершенно небезопасную, непроизводственную стратегию, которая напрямую подсказывает пользователя информацию о аутентификации, а затем передает ее прямо. Вы можете использовать его в качестве заполнителя, когда вы начинаете разработку, и позже легко заменять другие стратегии.

Начиная

Каждая стратегия Omniauth - это промежуточное программное обеспечение. Это означает, что вы можете использовать его так же, как вы используете любое другое промежуточное программное обеспечение. Например, чтобы использовать встроенную стратегию разработчика в приложении Sinatra, вы можете сделать это:

 require 'sinatra'
require 'omniauth'

class MyApplication < Sinatra :: Base
  use Rack :: Session :: Cookie
  use OmniAuth :: Strategies :: Developer
end

Поскольку Omniauth построен для аутентификации с несколькими проваторами , вы можете оставить место для запуска нескольких стратегий. Для этого встроенный класс OmniAuth::Builder дает вам простой способ указать несколько стратегий. Обратите внимание, что нет никакой разницы между следующим кодом и использованием каждой стратегии индивидуально в качестве промежуточного программного обеспечения. Это пример, который вы можете поместить в инициализатор рельсов на config/initializers/omniauth.rb :

 Rails . application . config . middleware . use OmniAuth :: Builder do
  provider :developer unless Rails . env . production?
  provider :twitter , ENV [ 'TWITTER_KEY' ] , ENV [ 'TWITTER_SECRET' ]
end

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

Интеграция Omniauth в ваше приложение

Omniauth-это чрезвычайно низкая библиотека. Он предназначен для того, чтобы быть черным ящиком, в который вы можете отправить пользователей вашего приложения, когда вам нужна аутентификация, а затем вернуть информацию. Omniauth был намеренно создан не для того, чтобы автоматически ассоциироваться с пользовательской моделью или делать предположения о том, сколько методов аутентификации вы можете использовать или что вы можете сделать с данными, как только пользователь будет аутентифицирован. Это делает Omniauth невероятно гибким. Чтобы использовать Omniauth, вам нужно только перенаправить пользователей на /auth/:provider где :provider - это имя стратегии (например, developer или twitter ). Оттуда Omniauth возьмет на себя и проведет пользователя через необходимые шаги для аутентификации их с помощью выбранной стратегии.

После того, как пользователь провел аутентификацию, что вы делаете дальше? Omniauth просто устанавливает специальный хэш, называемый хэш аутентификации в среде стойки запроса на /auth/:provider/callback . Этот хэш содержит столько информации об пользователе, сколько Omniauth смог получить из используемой стратегии. Вам следует настроить конечную точку в вашем приложении, которая соответствует URL -адресу обратного вызова, а затем выполняет любые шаги, необходимые для вашего приложения.

Ключ omniauth.auth в среде хэш предоставляет хэш аутентификации, которая будет содержать информацию о только что аутентифицированном пользователе, включая уникальный идентификатор, стратегию, которую они просто использовали для аутентификации, и личные данные, такие как имя и адрес электронной почты в качестве доступных. Для подробного описания того, что может содержать хэш аутентификации, см. Вики-страницу Auth Hash Hash.

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

RACK_CSRF

omniauth не совместим с OOTB с RACK_CSRF. Для этого необходимо добавить следующий код в код начальной загрузки приложения:

 OmniAuth :: AuthenticityTokenProtection . default_options ( key : "csrf.token" , authenticity_param : "_csrf" ) 

Рельсы (без разработки)

Чтобы начать, добавьте следующие драгоценные камни

Gemfile :

 gem 'omniauth'
gem "omniauth-rails_csrf_protection"

Затем вставьте Omniauth в качестве промежуточного программного обеспечения

config/initializers/omniauth.rb :

 Rails . application . config . middleware . use OmniAuth :: Builder do
  provider :developer if Rails . env . development?
end

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

config/routes.rb :

  get 'auth/:provider/callback' , to : 'sessions#create'
  get '/login' , to : 'sessions#new'

app/controllers/sessions_controller.rb :

 class SessionsController < ApplicationController
  def new
    render :new
  end

  def create
    user_info = request . env [ 'omniauth.auth' ]
    raise user_info # Your own session management should be placed here.
  end
end

app/views/sessions/new.html.erb :

 <%= form_tag('/auth/developer', method: 'post', data: {turbo: false}) do %>
  < button type =' submit ' > Login with Developer </ button >
<% end %>

Теперь, если вы посетите /login и нажмите кнопку «Вход», вы должны увидеть экран входа в систему разработчиков Omniauth. После его отправки вы возвращаетесь в свою заявку по адресу Sessions#create . Повышение должно теперь отображать все подробности Omniauth, которые у вас есть, для интеграции его в ваше собственное управление пользователями.

Если вы хотите выйти из управления полевым управлением, вам следует рассмотреть возможность использования Omniauth через разработку. Пожалуйста, посетите страницу Depise Github для получения дополнительной информации.

Rails API

Следующее промежуточное программное обеспечение (по умолчанию) включено для управления сеансом в приложениях Rails. При использовании Omniauth с API Rails вам нужно добавить одно из этих необходимого промежуточного программного обеспечения:

• ActionDispatch::Session::CacheStore
• ActionDispatch::Session::CookieStore
• ActionDispatch::Session::MemCacheStore

Уловка в том, чтобы добавить их обратно, заключается в том, что по умолчанию они передаются session_options при добавлении (включая клавишу сеанса), поэтому вы не можете просто добавить инициализатор session_store.rb , добавьте use ActionDispatch::Session::CookieStore и выполнять функционирование сеансов как обычно.

Чтобы быть ясным: сессии могут работать, но ваши параметры сеанса будут проигнорированы (то есть ключ сеанса по умолчанию будет по умолчанию в _session_id ). Вместо инициализатора вам придется установить соответствующие параметры где -то перед тем, как ваше промежуточное программное обеспечение будет построено (например, application.rb ), и передать их предпочтительному промежуточному программному обеспечению, например:

Application.rb:

 config . session_store :cookie_store , key : '_interslice_session'
config . middleware . use ActionDispatch :: Cookies # Required for all session management
config . middleware . use ActionDispatch :: Session :: CookieStore , config . session_options

(Спасибо @mltsy)

Регистрация

Omniauth поддерживает настраиваемый регистратор. По умолчанию Omniauth войдет в STDOUT , но вы можете настроить это, используя OmniAuth.config.logger :

 # Rails application example
OmniAuth . config . logger = Rails . logger 

Происхождение Парам

Параметр URL -адреса origin обычно используется для информирования, откуда пришел пользователь и откуда, если вы решите его использовать, они хотели бы вернуться. Omniauth поддерживает следующие настройки, которые можно настроить на уровне поставщика:

По умолчанию :

 provider :twitter , ENV [ 'KEY' ] , ENV [ 'SECRET' ]
POST /auth/twitter /?o rigin = [ URL ]
# If the `origin` parameter is blank, `omniauth.origin` is set to HTTP_REFERER

Использование параметра Origin с различным названием :

 provider :twitter , ENV [ 'KEY' ] , ENV [ 'SECRET' ] , origin_param : 'return_to'
POST /auth/twitter /?r eturn_to = [ URL ]
# If the `return_to` parameter is blank, `omniauth.origin` is set to HTTP_REFERER

Неполноценный :

 provider :twitter , ENV [ 'KEY' ] , ENV [ 'SECRET' ] , origin_param : false
POST /auth/twitter
# This means the origin should be handled by your own application. 
# Note that `omniauth.origin` will always be blank. 

Ресурсы

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

Omniauth для предприятия

Доступно как часть подписки Tidelift.

Содействия Omniauth и тысячи других пакетов работают с Tidelift для обеспечения коммерческой поддержки и технического обслуживания для пакетов с открытым исходным кодом, которые вы используете для создания ваших приложений. Сэкономьте время, снижайте риск и улучшайте здоровье кода, одновременно выплачивая актуальных пакетов, которые вы используете. Узнать больше.

Поддерживаемые версии Ruby

Omniauth проверяется под 2,5, 2,6, 2,7, 3,0, 3,1, 3,2, Truffleruby и Jruby.

Версии

Эта библиотека направлена ​​на то, чтобы придерживаться семантических версий 2.0.0. Нарушения этой схемы следует сообщать как ошибки. В частности, если выпускается небольшая версия или патч, которая ломается назад, эта версия должна немедленно вырвать, и/или новая версия должна быть немедленно выпущена, которая восстанавливает совместимость. Разрыв изменения в публичном API будет введена только с новыми крупными версиями. В результате этой политики вы можете (и должны) указать зависимость от этого драгоценного камня, используя ограничение пессимистической версии с двумя цифрами точности. Например:

 spec.add_dependency 'omniauth', '~> 1.0'

Лицензия

Copyright (C) 2010-2017 Michael Bleigh and Intridea, Inc. См. Лицензию для деталей.