omniauth
v1.9.2
Esta é a documentação para o ramo de desenvolvimento de Omniauth. Você pode encontrar a documentação para o último lançamento estável aqui
Omniauth é uma biblioteca que padroniza a autenticação de vários fornecedores para aplicativos da Web. Foi criado para ser poderoso, flexível e fazer o mínimo possível. Qualquer desenvolvedor pode criar estratégias para omniauth que possam autenticar os usuários por meio de sistemas díspares. Estratégias omniauth foram criadas para tudo, do Facebook a LDAP.
Para usar o Omniauth em seus aplicativos, você precisará aproveitar uma ou mais estratégias. Essas estratégias geralmente são divulgadas individualmente como rubygems, e você pode ver uma lista mantida da comunidade no wiki para este projeto.
Uma estratégia, chamada Developer , é incluída no Omniauth e fornece uma estratégia completamente insegura e não produtiva que solicita diretamente a um usuário para obter informações de autenticação e depois a passa diretamente. Você pode usá -lo como um espaço reservado quando iniciar o desenvolvimento e trocar facilmente em outras estratégias posteriormente.
Cada estratégia Omniauth é um middleware do rack. Isso significa que você pode usá -lo da mesma maneira que usa qualquer outro middleware do rack. Por exemplo, para usar a estratégia de desenvolvedor integrada em um aplicativo Sinatra, você pode fazer isso:
require 'sinatra'
require 'omniauth'
class MyApplication < Sinatra :: Base
use Rack :: Session :: Cookie
use OmniAuth :: Strategies :: Developer
end Como a Omniauth é construída para autenticação de vários fornecedores , você pode deixar espaço para executar várias estratégias. Para isso, a classe OmniAuth::Builder integrada fornece uma maneira fácil de especificar várias estratégias. Observe que não há diferença entre o código a seguir e o uso de cada estratégia individualmente como middleware. Este é um exemplo que você pode colocar em um inicializador de trilhos em 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' ]
endVocê deve procurar a documentação para cada provedor que você usa para requisitos específicos de inicialização.
Omniauth é uma biblioteca extremamente baixa. Ele foi projetado para ser uma caixa preta para a qual você pode enviar os usuários do seu aplicativo quando precisar de autenticação e, em seguida, obter informações de volta. Omniauth foi intencionalmente construído para não se associar automaticamente a um modelo de usuário ou fazer suposições sobre quantos métodos de autenticação você pode querer usar ou o que você deseja fazer com os dados depois que um usuário tiver autenticado. Isso torna Omniauth incrivelmente flexível. Para usar o Omniauth, você precisa apenas redirecionar os usuários para /auth/:provider , onde :provider é o nome da estratégia (por exemplo, developer ou twitter ). A partir daí, Omniauth assumirá o controle e levará o usuário às etapas necessárias para autenticá -las com a estratégia escolhida.
Depois que o usuário tiver autenticado, o que você faz a seguir? Omniauth simplesmente define um hash especial chamado Hash de autenticação no ambiente do rack de uma solicitação para /auth/:provider/callback . Este hash contém tanta informação sobre o usuário quanto a Omniauth conseguiu recolher a estratégia utilizada. Você deve configurar um terminal em seu aplicativo que corresponda ao URL de retorno de chamada e execute as etapas necessárias para o seu aplicativo.
A chave omniauth.auth no Hash do ambiente fornece um hash de autenticação que conterá informações sobre o usuário autenticado apenas, incluindo um ID exclusivo, a estratégia que eles usavam para autenticação e detalhes pessoais, como nome e endereço de email, conforme disponível. Para uma descrição profunda do que o hash de autenticação pode conter, consulte a página Wiki do esquema de hash de hash auth.
Observe que a Omniauth não executa nenhuma ação além de definir algumas informações do ambiente na solicitação de retorno de chamada. Cabe a você como você deseja implementar os detalhes do fluxo de autenticação do seu aplicativo.
omniauth não é compatível com OOTB com rack_csrf. Para fazer isso, o código a seguir precisa ser adicionado ao código de inicialização do aplicativo:
OmniAuth :: AuthenticityTokenProtection . default_options ( key : "csrf.token" , authenticity_param : "_csrf" ) Para começar, adicione as seguintes jóias
GemFile :
gem 'omniauth'
gem "omniauth-rails_csrf_protection"Em seguida, insira omniauth como um middleware
Config/Initializers/omniauth.rb :
Rails . application . config . middleware . use OmniAuth :: Builder do
provider :developer if Rails . env . development?
endFornecedores adicionais podem ser adicionados aqui no futuro. Em seguida, conectamos tudo usando rotas, um controlador e uma visualização de login.
config/rotes.rb :
get 'auth/:provider/callback' , to : 'sessions#create'
get '/login' , to : 'sessions#new'App/controladores/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
endApp/Views/Sessions/new.html.erb :
<%= form_tag('/auth/developer', method: 'post', data: {turbo: false}) do %>
< button type =' submit ' > Login with Developer </ button >
<% end %> Agora, se você visitar /login e clicar no botão de login, verá a tela de login do Omniauth Developer. Depois de enviá -lo, você retornará à sua inscrição no Sessions#create . O aumento agora deve exibir todos os detalhes do Omniauth que você tem disponível para integrá -lo ao seu próprio gerenciamento de usuários.
Se você quiser um gerenciamento de usuário fora da caixa, considere usar o Omniauth através do Devise. Visite a página Devise Github para obter mais informações.
O seguinte middleware é (por padrão) incluído para gerenciamento de sessões em aplicativos Rails. Ao usar a Omniauth com uma API do Rails, você precisará adicionar um desses middleware necessário de volta:
ActionDispatch::Session::CacheStoreActionDispatch::Session::CookieStoreActionDispatch::Session::MemCacheStore O truque para adicioná -los de volta é que, por padrão, eles são aprovados session_options quando adicionados (incluindo a chave da sessão), para que você não possa simplesmente adicionar um Inicializador session_store.rb , adicione use ActionDispatch::Session::CookieStore e ter sessões funcionando como normal.
Para ficar claro: as sessões podem funcionar, mas suas opções de sessão serão ignoradas (ou seja, a chave da sessão será padrão para _session_id ). Em vez do inicializador, você precisará definir as opções relevantes em algum lugar antes que seu middleware seja construído (como application.rb ) e passá -las para o seu middleware preferido, assim:
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(Obrigado @mltsy)
Omniauth suporta um madeireiro configurável. Por padrão, Omniauth fará login no STDOUT , mas você pode configurar isso usando OmniAuth.config.logger :
# Rails application example
OmniAuth . config . logger = Rails . logger O parâmetro URL origin é normalmente usado para informar de onde um usuário veio e de onde, você deve optar por usá -lo, eles desejam retornar. Omniauth suporta as seguintes configurações que podem ser configuradas em um nível de provedor:
Padrão :
provider :twitter , ENV [ 'KEY' ] , ENV [ 'SECRET' ]
POST /auth/twitter /?o rigin = [ URL ]
# If the `origin` parameter is blank, `omniauth.origin` is set to HTTP_REFERERUsando um parâmetro de origem de nome diferente :
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_REFERERDesabilitado :
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. O Omniauth Wiki manteve ativamente uma documentação aprofundada para Omniauth. Deve ser sua primeira parada se você estiver se perguntando sobre uma olhada mais aprofundada para Omniauth, como funciona e como usá-lo.
Disponível como parte da assinatura do Tidelift.
Os mantenedores da Omniauth e milhares de outros pacotes estão trabalhando com o Tidelift para fornecer suporte e manutenção comerciais para os pacotes de código aberto que você usa para criar seus aplicativos. Economize tempo, reduza o risco e melhore a saúde do código, enquanto paga aos mantenedores dos pacotes exatos que você usa. Saber mais.
Omniauth é testado em 2,5, 2,6, 2,7, 3,0, 3.1, 3.2, Truffleruby e Jruby.
Esta biblioteca tem como objetivo aderir à versão semântica 2.0.0. As violações desse esquema devem ser relatadas como bugs. Especificamente, se for lançada uma versão menor ou patch que quebre a compatibilidade com versões anteriores, essa versão deve ser imediatamente arrancada e/ou uma nova versão deve ser lançada imediatamente que restaure a compatibilidade. A quebra de mudanças na API pública será introduzida apenas com novas versões principais. Como resultado dessa política, você pode (e deve) especificar uma dependência dessa gema usando a restrição de versão pessimista com dois dígitos de precisão. Por exemplo:
spec.add_dependency 'omniauth', '~> 1.0'
Copyright (c) 2010-2017 Michael Bleigh e Intridea, Inc. Consulte a licença para obter detalhes.
