omniauth
v1.9.2
Il s'agit de la documentation de la branche en développement d'Omniauth. Vous pouvez trouver la documentation de la dernière version stable ici
OmniAuth est une bibliothèque qui standardise l'authentification multi-fournisseurs pour les applications Web. Il a été créé pour être puissant, flexible et faire le moins possible. Tout développeur peut créer des stratégies d'Omniauth qui peuvent authentifier les utilisateurs via des systèmes disparates. Des stratégies Omniauth ont été créées pour tout, de Facebook à LDAP.
Afin d'utiliser Omniauth dans vos applications, vous devrez tirer parti d'une ou plusieurs stratégies. Ces stratégies sont généralement publiées individuellement sous le nom de Rubygems, et vous pouvez voir une liste entretenue par la communauté sur le wiki pour ce projet.
Une stratégie, appelée Developer , est incluse avec OmniAuth et fournit une stratégie complètement incertaine et non utile qui invite directement à un utilisateur pour des informations d'authentification, puis la transmet directement. Vous pouvez l'utiliser comme espace réservé lorsque vous commencez le développement et échanger facilement dans d'autres stratégies plus tard.
Chaque stratégie Omniauth est un middleware de rack. Cela signifie que vous pouvez l'utiliser de la même manière que vous utilisez n'importe quel autre middleware. Par exemple, pour utiliser la stratégie de développeur intégrée dans une application Sinatra, vous pourriez le faire:
require 'sinatra'
require 'omniauth'
class MyApplication < Sinatra :: Base
use Rack :: Session :: Cookie
use OmniAuth :: Strategies :: Developer
end Étant donné que Omniauth est conçue pour l'authentification multiprovider , vous voudrez peut-être laisser de la place pour exécuter plusieurs stratégies. Pour cela, la classe OmniAuth::Builder intégrée vous donne un moyen facile de spécifier plusieurs stratégies. Notez qu'il n'y a pas de différence entre le code suivant et l'utilisation de chaque stratégie individuellement comme middleware. Ceci est un exemple que vous pourriez mettre dans un initialiseur de rails sur 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' ]
endVous devez consulter la documentation pour chaque fournisseur que vous utilisez pour des exigences d'initialisation spécifiques.
Omniauth est une bibliothèque extrêmement faible. Il est conçu pour être une boîte noire dans laquelle vous pouvez envoyer les utilisateurs de votre application lorsque vous avez besoin d'authentification, puis récupérer les informations. Omniauth a été intentionnellement construite pour ne pas s'associer automatiquement à un modèle d'utilisateur ou faire des hypothèses sur le nombre de méthodes d'authentification que vous pourriez souhaiter utiliser ou ce que vous pourriez vouloir faire avec les données une fois qu'un utilisateur s'est authentifié. Cela rend Omniututh incroyablement flexible. Pour utiliser OmniAuth, vous n'avez qu'à rediriger les utilisateurs vers /auth/:provider , où :provider est le nom de la stratégie (par exemple, developer ou twitter ). À partir de là, Omniauth prendra le relais et prendra l'utilisateur à travers les étapes nécessaires pour les authentifier avec la stratégie choisie.
Une fois que l'utilisateur s'est authentifié, que faites-vous ensuite? OmniAuth définit simplement un hachage spécial appelé le hachage d'authentification sur l'environnement du rack d'une demande à /auth/:provider/callback . Ce hachage contient autant d'informations sur l'utilisateur qu'Omniauth a pu glaner de la stratégie utilisée. Vous devez configurer un point de terminaison dans votre application qui correspond à l'URL de rappel, puis effectue les étapes nécessaires à votre application.
La clé omniauth.auth dans le hachage d'environnement fournit un hachage d'authentification qui contiendra des informations sur l'utilisateur juste authentifié, y compris un ID unique, la stratégie qu'ils viennent d'utiliser pour l'authentification et les détails personnels tels que le nom et l'adresse e-mail, le cas échéant. Pour une description approfondie de ce que le hachage d'authentification pourrait contenir, consultez la page Wiki du schéma de hachage AUTH.
Notez qu'Omniauth n'effectue aucune action au-delà de la définition de certaines informations sur l'environnement sur la demande de rappel. Il vous suffit entièrement de la façon dont vous souhaitez implémenter les détails du flux d'authentification de votre application.
omniauth n'est pas compatible OOTB avec RACK_CSRF. Pour ce faire, le code suivant doit être ajouté au code d'amorçage d'application:
OmniAuth :: AuthenticityTokenProtection . default_options ( key : "csrf.token" , authenticity_param : "_csrf" ) Pour commencer, ajoutez les joyaux suivants
Gemfile :
gem 'omniauth'
gem "omniauth-rails_csrf_protection"Puis insérez Omniauth en tant que middleware
config / initialisers / omniauth.rb :
Rails . application . config . middleware . use OmniAuth :: Builder do
provider :developer if Rails . env . development?
endDes fournisseurs supplémentaires peuvent être ajoutés ici à l'avenir. Ensuite, nous câlins tout en utilisant des itinéraires, un contrôleur et une vue de connexion.
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
endapp / vues / sessions / new.html.erb :
<%= form_tag('/auth/developer', method: 'post', data: {turbo: false}) do %>
< button type =' submit ' > Login with Developer </ button >
<% end %> Maintenant, si vous visitez /login et cliquez sur le bouton de connexion, vous devriez voir l'écran de connexion du développeur Omniauth. Après l'avoir soumis, vous êtes retourné à votre demande à Sessions#create . L'augmentation devrait désormais afficher tous les détails Omniauth dont vous disposez pour l'intégrer dans votre propre gestion des utilisateurs.
Si vous voulez sortir de l'utilisateur de la boîte, vous devriez envisager d'utiliser OmniAuth via Devise. Veuillez visiter la page Github Devise pour plus d'informations.
Les middleware suivants sont (par défaut) inclus pour la gestion de session dans les applications Rails. Lorsque vous utilisez OmniAuth avec une API Rails, vous devrez ajouter un de ces middleware requis:
ActionDispatch::Session::CacheStoreActionDispatch::Session::CookieStoreActionDispatch::Session::MemCacheStore L'astuce pour les ajouter est que, par défaut, ils sont passés session_options lorsqu'ils sont ajoutés (y compris la clé de session), vous ne pouvez donc pas simplement ajouter un initialiseur session_store.rb , ajouter use ActionDispatch::Session::CookieStore et avoir des sessions fonctionnant comme normales.
Pour être clair: les sessions peuvent fonctionner, mais vos options de session seront ignorées (c'est-à-dire que la clé de session sera par défaut à _session_id ). Au lieu de l'initialisateur, vous devrez définir les options pertinentes quelque part avant la construction de votre middleware (comme application.rb ) et les transmettre à votre middleware préféré, comme ceci:
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(Merci @mltsy)
Omniauth prend en charge un enregistreur configurable. Par défaut, OmniAuth se connectera à STDOUT mais vous pouvez configurer cela en utilisant OmniAuth.config.logger :
# Rails application example
OmniAuth . config . logger = Rails . logger Le paramètre d'URL origin est généralement utilisé pour informer d'où vient un utilisateur et d'où, si vous choisissez de l'utiliser, il voulait revenir. OmniAuth prend en charge les paramètres suivants qui peuvent être configurés au niveau du fournisseur:
Défaut :
provider :twitter , ENV [ 'KEY' ] , ENV [ 'SECRET' ]
POST /auth/twitter /?o rigin = [ URL ]
# If the `origin` parameter is blank, `omniauth.origin` is set to HTTP_REFERERUtilisation d'un paramètre d'origine nommé différemment :
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_REFERERDésactivé :
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. L'Omniauth Wiki a activement maintenu une documentation approfondie pour Omniauth. Ce devrait être votre premier arrêt si vous vous interrogez sur un aperçu plus approfondi d'Omniauth, comment cela fonctionne et comment l'utiliser.
Disponible dans le cadre de l'abonnement Tidelift.
Les responsables d'Omniauth et des milliers d'autres packages travaillent avec Tidelift pour fournir un support commercial et une maintenance pour les packages open source que vous utilisez pour créer vos applications. Économisez du temps, réduisez les risques et améliorez la santé du code, tout en payant les maintenseurs des packages exacts que vous utilisez. Apprendre encore plus.
Omniauth est testé sous 2,5, 2,6, 2,7, 3.0, 3.1, 3.2, Truffleruby et JRuby.
Cette bibliothèque vise à adhérer au versioning sémantique 2.0.0. Les violations de ce programme doivent être signalées comme des bogues. Plus précisément, si une version mineure ou patch est publiée qui rompt la compatibilité en arrière, cette version doit être immédiatement arrachée et / ou une nouvelle version devrait être immédiatement publiée qui restaure la compatibilité. La rupture de modifications de l'API publique ne sera introduite qu'avec de nouvelles versions majeures. À la suite de cette politique, vous pouvez (et devriez) spécifier une dépendance à ce joyau en utilisant la contrainte de version pessimiste avec deux chiffres de précision. Par exemple:
spec.add_dependency 'omniauth', '~> 1.0'
Copyright (C) 2010-2017 Michael Bleigh et Intedea, Inc. Voir la licence pour plus de détails.
