omniauth
v1.9.2
Esta es la documentación para la rama en desarrollo de Omniauth. Puede encontrar la documentación para el último lanzamiento estable aquí.
Omniauth es una biblioteca que estandariza la autenticación de múltiples proveedores para aplicaciones web. Fue creado para ser poderoso, flexible y hacer lo menos posible. Cualquier desarrollador puede crear estrategias para Omniauth que puedan autenticar a los usuarios a través de sistemas dispares. Se han creado estrategias de Omniauth para todo, desde Facebook hasta LDAP.
Para usar Omniauth en sus aplicaciones, deberá aprovechar una o más estrategias. Estas estrategias generalmente se publican individualmente como Rubygems, y puede ver una lista mantenida por la comunidad en el wiki para este proyecto.
Una estrategia, llamada Developer , se incluye con Omniauth y proporciona una estrategia completamente insegura y de uso no usable que solicita directamente a un usuario para la información de autenticación y luego la pasa directamente. Puede usarlo como marcador de posición cuando comienza al desarrollo y cambia fácilmente en otras estrategias más adelante.
Cada estrategia de Omniauth es un middleware de rack. Eso significa que puede usarlo de la misma manera que usa cualquier otro middleware de rack. Por ejemplo, para usar la estrategia de desarrollador incorporada en una aplicación Sinatra, puede hacer esto:
require 'sinatra'
require 'omniauth'
class MyApplication < Sinatra :: Base
use Rack :: Session :: Cookie
use OmniAuth :: Strategies :: Developer
end Debido a que Omniauth está construido para la autenticación de múltiples proveedores , es posible que desee dejar espacio para ejecutar múltiples estrategias. Para esto, la clase OmniAuth::Builder incorporada le brinda una manera fácil de especificar múltiples estrategias. Tenga en cuenta que no hay diferencia entre el siguiente código y el uso de cada estrategia individualmente como middleware. Este es un ejemplo que puede poner en un inicializador Rails en 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' ]
endDebe buscar la documentación para cada proveedor que use para requisitos de inicialización específicos.
Omniauth es una biblioteca extremadamente baja. Está diseñado para ser una caja negra en la que puede enviar a los usuarios de su aplicación cuando necesita autenticación y luego recuperar la información. Omniauth se construyó intencionalmente para no asociarse automáticamente con un modelo de usuario o hacer suposiciones sobre cuántos métodos de autenticación puede usar o qué puede hacer con los datos una vez que un usuario se haya autenticado. Esto hace que Omniauth sea increíblemente flexible. Para usar Omniauth, solo necesita redirigir a los usuarios a /auth/:provider , dónde :provider es el nombre de la estrategia (por ejemplo, developer o twitter ). A partir de ahí, Omniauth se hará cargo y tomará al usuario a través de los pasos necesarios para autenticarlos con la estrategia elegida.
Una vez que el usuario se ha autenticado, ¿qué haces a continuación? Omniauth simplemente establece un hash especial llamado el hash de autenticación en el entorno de rack de una solicitud a /auth/:provider/callback . Este hash contiene tanta información sobre el usuario como Omniauth pudo obtener de la estrategia utilizada. Debe configurar un punto final en su aplicación que coincida con la URL de devolución de llamada y luego realice los pasos que sean necesarios para su aplicación.
La clave omniauth.auth en el entorno hash proporciona un hash de autenticación que contendrá información sobre el usuario recién autenticado, incluida una ID única, la estrategia que acaba de usar para la autenticación y detalles personales como el nombre y la dirección de correo electrónico tal como están disponibles. Para una descripción profunda de lo que el hash de autenticación podría contener, consulte la página de Wiki de esquema de autores.
Tenga en cuenta que Omniauth no realiza ninguna acción más allá de establecer información sobre el entorno en la solicitud de devolución de llamada. Depende completamente de usted cómo desea implementar los detalles del flujo de autenticación de su aplicación.
omniauth no es compatible con OOTB con rack_csrf. Para hacerlo, se debe agregar el siguiente código al código de arranque de la aplicación:
OmniAuth :: AuthenticityTokenProtection . default_options ( key : "csrf.token" , authenticity_param : "_csrf" ) Para comenzar, agregue las siguientes gemas
Gemfile :
gem 'omniauth'
gem "omniauth-rails_csrf_protection"Luego inserte omniauth como middleware
config/inicializadores/omniauth.rb :
Rails . application . config . middleware . use OmniAuth :: Builder do
provider :developer if Rails . env . development?
endSe pueden agregar proveedores adicionales aquí en el futuro. A continuación, lo conectamos todo usando rutas, un controlador y una vista de inicio de sesión.
config/rutas.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
endapp/vistas/sesiones/new.html.erb :
<%= form_tag('/auth/developer', method: 'post', data: {turbo: false}) do %>
< button type =' submit ' > Login with Developer </ button >
<% end %> Ahora, si visita /login y hace clic en el botón de inicio de sesión, debería ver la pantalla de inicio de sesión del desarrollador Omniauth. Después de enviarlo, es devuelto a su solicitud en Sessions#create . El aumento ahora debe mostrar todos los detalles de Omniauth que tiene disponibles para integrarlo en su propia administración de usuarios.
Si desea fuera de la caja Usermanagement, debe considerar usar Omniauth a través de dispositivos. Visite la página de disposición GitHub para obtener más información.
El siguiente middleware se incluye (por defecto) para la administración de sesiones en aplicaciones Rails. Cuando use Omniauth con una API Rails, deberá agregar uno de estos middleware requerido:
ActionDispatch::Session::CacheStoreActionDispatch::Session::CookieStoreActionDispatch::Session::MemCacheStore El truco para volver a agregarlos es que, de manera predeterminada, se pasan session_options cuando se agregan (incluida la clave de sesión), por lo que no puede agregar un inicializador session_store.rb , agregue use ActionDispatch::Session::CookieStore y tener sesiones funcionando como normales.
Para ser claros: las sesiones pueden funcionar, pero las opciones de su sesión se ignorarán (es decir, la clave de sesión de la sesión predeterminará _session_id ). En lugar del inicializador, tendrá que establecer las opciones relevantes en algún lugar antes de que su middleware esté construido (como application.rb ) y pasarlas a su middleware preferido, así:
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(Gracias @mltsy)
Omniauth admite un registrador configurable. Por defecto, Omniauth registrará a STDOUT pero puede configurar esto usando OmniAuth.config.logger :
# Rails application example
OmniAuth . config . logger = Rails . logger El parámetro de URL origin generalmente se usa para informar de dónde proviene un usuario y de dónde, si elige usarlo, le gustaría volver. Omniauth admite las siguientes configuraciones que se pueden configurar a nivel de proveedor:
Por defecto :
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 un parámetro de origen con nombre 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_REFERERDesactivado :
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. El Omniauth Wiki ha mantenido activamente la documentación en profundidad para Omniauth. Debería ser su primera parada si se pregunta sobre una mirada más profunda a Omniauth, cómo funciona y cómo usarlo.
Disponible como parte de la suscripción de TidElift.
Los mantenedores de Omniauth y miles de otros paquetes están trabajando con TidElift para ofrecer soporte y mantenimiento comerciales para los paquetes de código abierto que utiliza para construir sus aplicaciones. Ahorre tiempo, reduzca el riesgo y mejore la salud del código, al tiempo que paga a los mantenedores de los paquetes exactos que usa. Aprende más.
Omniauth se prueba bajo 2.5, 2.6, 2.7, 3.0, 3.1, 3.2, Truffleruby y Jruby.
Esta biblioteca tiene como objetivo adherirse al versioning semántico 2.0.0. Las violaciones de este esquema deben informarse como errores. Específicamente, si se lanza una versión menor o de parche que rompe la compatibilidad hacia atrás, esa versión debe tirarse inmediatamente y/o una nueva versión debe lanzarse inmediatamente que restaure la compatibilidad. Los cambios en la API pública solo se introducirán con nuevas versiones importantes. Como resultado de esta política, puede (y debe) especificar una dependencia de esta gema utilizando la restricción de la versión pesimista con dos dígitos de precisión. Por ejemplo:
spec.add_dependency 'omniauth', '~> 1.0'
Copyright (c) 2010-2017 Michael Bleigh e Intridea, Inc. Consulte la licencia para obtener detalles.
