omniauth
v1.9.2
Dies ist die Dokumentation für den Entwicklungszweig von Omniauth. Die Dokumentation finden Sie hier für die neueste stabile Version hier
Omniauth ist eine Bibliothek, die die Authentifizierung der Multi-Anbieter-Authentifizierung für Webanwendungen standardisiert. Es wurde geschaffen, um mächtig, flexibel zu sein und so wenig wie möglich zu tun. Jeder Entwickler kann Strategien für Omniauth erstellen, die Benutzer über unterschiedliche Systeme authentifizieren können. Omniauth -Strategien wurden für alles von Facebook bis LDAP erstellt.
Um Omniauth in Ihren Anwendungen zu verwenden, müssen Sie eine oder mehrere Strategien nutzen. Diese Strategien werden im Allgemeinen einzeln als Rubygemems veröffentlicht, und Sie können eine Community -Liste auf dem Wiki für dieses Projekt sehen.
Eine Strategie namens Developer ist in Omniauth enthalten und bietet eine völlig unsichere Strategie, die einen Benutzer für Authentifizierungsinformationen direkt auffordert und dann direkt durchgeht. Sie können es als Platzhalter verwenden, wenn Sie mit der Entwicklung beginnen und später andere Strategien problemlos eintauschen.
Jede Omniauth -Strategie ist ein Rack Middleware. Das bedeutet, dass Sie es genauso verwenden können, wie Sie andere Rack Middleware verwenden. Um beispielsweise die integrierte Entwicklerstrategie in einer Sinatra-Anwendung zu verwenden, können Sie dies tun:
require 'sinatra'
require 'omniauth'
class MyApplication < Sinatra :: Base
use Rack :: Session :: Cookie
use OmniAuth :: Strategies :: Developer
end Da Omniauth für die Authentifizierung von Multi-Anbietern gebaut wurde, möchten Sie möglicherweise Raum für mehrere Strategien verlassen. Dafür bietet Ihnen die integrierte OmniAuth::Builder Klasse eine einfache Möglichkeit, mehrere Strategien anzugeben. Beachten Sie, dass es keinen Unterschied zwischen dem folgenden Code und der Verwendung jeder Strategie einzeln als Middleware gibt. Dies ist ein Beispiel, das Sie bei config/initializers/omniauth.rb in einen Rails -Initialisierer einfügen könnten:
Rails . application . config . middleware . use OmniAuth :: Builder do
provider :developer unless Rails . env . production?
provider :twitter , ENV [ 'TWITTER_KEY' ] , ENV [ 'TWITTER_SECRET' ]
endSie sollten die Dokumentation für jeden Anbieter betrachten, den Sie für bestimmte Initialisierungsanforderungen verwenden.
Omniauth ist eine extrem niedrige Bibliothek. Es ist eine schwarze Box ausgelegt, in die Sie die Benutzer Ihrer Anwendung senden können, wenn Sie Authentifizierung benötigen, und dann Informationen zurückholen. Omniauth wurde absichtlich erstellt, um nicht automatisch mit einem Benutzermodell zu assoziieren oder Annahmen darüber zu treffen, wie viele Authentifizierungsmethoden Sie möglicherweise verwenden möchten oder was Sie mit den Daten tun möchten, sobald ein Benutzer authentifiziert ist. Dies macht Omniauth unglaublich flexibel. Um Omniauth zu verwenden, müssen Sie Benutzer nur zu /auth/:provider umleiten, wobei :provider der Name der Strategie ist (z. B. developer oder twitter ). Von dort aus übernimmt Omniauth den Benutzer die erforderlichen Schritte, um sie mit der gewählten Strategie zu authentifizieren.
Was tun Sie als nächstes, sobald der Benutzer authentifiziert hat? Omniauth legt lediglich einen speziellen Hash namens Authentication Hash in der Rack -Umgebung einer Anfrage an /auth/:provider/callback fest. Dieser Hash enthält so viele Informationen über den Benutzer, wie Omniauth aus der verwendeten Strategie entlasten konnte. Sie sollten einen Endpunkt in Ihrer Anwendung einrichten, der mit der Callback -URL übereinstimmt, und dann alle für Ihre Bewerbung erforderlichen Schritte ausführen.
Der Schlüssel in der Umgebung von omniauth.auth in der Umgebung bietet einen Authentifizierungs -Hash, der Informationen über den gerechten Benutzer enthält, einschließlich einer eindeutigen ID, der Strategie, die sie gerade zur Authentifizierung verwendet haben, sowie persönliche Daten wie Name und E -Mail -Adresse wie verfügbar. Eine eingehende Beschreibung dessen, was der Authentifizierungs-Hash enthalten könnte, finden Sie auf der Auth-Hash-Schema-Wiki-Seite.
Beachten Sie, dass Omniauth keine Aktionen ausführt, die über einige Umgebungsinformationen auf der Rückrufanforderung festgelegt werden. Es liegt ganz bei Ihnen, wie Sie die Einzelheiten des Authentifizierungsflusss Ihrer Anwendung implementieren möchten.
omniauth ist nicht mit Rack_CSrf-kompatibel. Zu diesem Zweck muss der folgende Code dem Anwendungs -Bootstrapping -Code hinzugefügt werden:
OmniAuth :: AuthenticityTokenProtection . default_options ( key : "csrf.token" , authenticity_param : "_csrf" ) Fügen Sie zu Beginn die folgenden Edelsteine hinzu
GemFile :
gem 'omniauth'
gem "omniauth-rails_csrf_protection"Fügen Sie dann Omniauth als Middleware ein
config/initializer/omniauth.rb :
Rails . application . config . middleware . use OmniAuth :: Builder do
provider :developer if Rails . env . development?
endZusätzliche Anbieter können hier in Zukunft hinzugefügt werden. Als nächstes verdrahten wir alles mit Routen, einem Controller und einer Anmeldeansicht.
config/Routes.rb :
get 'auth/:provider/callback' , to : 'sessions#create'
get '/login' , to : 'sessions#new'App/Controller/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 %> Wenn Sie nun besuchen /login und auf die Schaltfläche Anmeldung klicken, sollten Sie den Anmeldebildschirm Omniauth Developer sehen. Nachdem Sie es eingereicht haben, werden Sie an Ihre Bewerbung bei Sessions#create zurückgegeben. Die Erhöhung sollte jetzt alle Omniauth -Details anzeigen, die Sie zur Verfügung haben, um sie in Ihre eigene Benutzerverwaltung zu integrieren.
Wenn Sie das Box -Benutzermanagement wünschen, sollten Sie Omniauth durch Devise verwenden. Bitte besuchen Sie die Devise Github -Seite, um weitere Informationen zu erhalten.
Die folgenden Middleware sind (standardmäßig) für die Sitzungsverwaltung in Rails -Anwendungen enthalten. Wenn Sie Omniauth mit einer Rails -API verwenden, müssen Sie eine dieser erforderlichen Middleware zurück in:
ActionDispatch::Session::CacheStoreActionDispatch::Session::CookieStoreActionDispatch::Session::MemCacheStore Der Trick beim Hinzufügen dieser zurück in ist, dass sie standardmäßig beim Hinzufügen von session_options bestanden werden (einschließlich der Sitzungsschlüssel), sodass Sie nicht einfach einen session_store.rb -Initializer hinzufügen können, use ActionDispatch::Session::CookieStore und haben Sitzungen wie normal funktionieren.
Um klar zu sein: Die Sitzungen können funktionieren, aber Ihre Sitzungsoptionen werden ignoriert (dh der Sitzungsschlüssel wird standardmäßig _session_id standardmäßig). Anstelle des Initialisierers müssen Sie die entsprechenden Optionen irgendwo festlegen, bevor Ihre Middleware erstellt wird (wie bei application.rb ) und an Ihre bevorzugte Middleware wie folgt weitergeben:
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(Danke @mltsy)
Omniauth unterstützt einen konfigurierbaren Logger. Standardmäßig wird sich Omniauth bei STDOUT anmelden, aber Sie können dies mit OmniAuth.config.logger konfigurieren:
# Rails application example
OmniAuth . config . logger = Rails . logger Der origin -URL -Parameter wird normalerweise verwendet, um darüber zu informieren, woher ein Benutzer stammt und woher Sie ihn verwenden möchten, zu dem sie zurückkehren möchten. Omniauth unterstützt die folgenden Einstellungen, die auf Anbieterebene konfiguriert werden können:
Standard :
provider :twitter , ENV [ 'KEY' ] , ENV [ 'SECRET' ]
POST /auth/twitter /?o rigin = [ URL ]
# If the `origin` parameter is blank, `omniauth.origin` is set to HTTP_REFERERVerwenden eines unterschiedlich benannten Ursprungsparameters :
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_REFERERDeaktiviert :
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. Das Omniauth Wiki hat aktiv eine eingehende Dokumentation für Omniauth beibehalten. Es sollte Ihr erster Zwischenstopp sein, wenn Sie sich über einen detaillierteren Blick auf Omniauth, wie es funktioniert und wie man es benutzt, wundert.
Erhältlich als Teil des Tidelift -Abonnements.
Die Betreuer von Omniauth und Tausenden anderer Pakete arbeiten mit TIDELIFT zusammen, um kommerzielle Unterstützung und Wartung für die Open Source -Pakete zu bieten, mit denen Sie Ihre Anwendungen erstellen. Sparen Sie Zeit, reduzieren Sie das Risiko und verbessern Sie die Code -Gesundheit, während Sie die Wartenden der genauen Pakete bezahlen, die Sie verwenden. Erfahren Sie mehr.
Omniauth wird unter 2,5, 2,6, 2,7, 3,0, 3,1, 3,2, Truffleruby und Jruby getestet.
Diese Bibliothek zielt darauf ab, sich an semantische Versionen 2.0.0 zu halten. Verstöße gegen dieses Schema sollten als Fehler gemeldet werden. Wenn eine Minor- oder Patch -Version veröffentlicht wird, die die Kompatibilität nach hinten ausbricht, sollte diese Version sofort geschleudert werden und/oder eine neue Version sofort veröffentlicht werden, die die Kompatibilität wiederherstellt. Durch die Veränderung der öffentlichen API wird nur mit neuen Hauptversionen eingeführt. Als Ergebnis dieser Richtlinie können (und sollten) Sie eine Abhängigkeit von diesem Juwel angeben, indem Sie die pessimistische Versionsbeschränkung mit zwei Ziffern der Präzision verwenden. Zum Beispiel:
spec.add_dependency 'omniauth', '~> 1.0'
Copyright (C) 2010-2017 Michael Beigh und Intridea, Inc. Siehe Lizenz für Details.
