Version de pierres précieuses
État de la construction
Code climat
État de la couverture

Il s’agit de la documentation de la branche d’OmniAuth en cours de développement. Vous pouvez consulter la documentation de notre dernière version v2.0.4 Ici.

Une introduction

OmniAuth est une bibliothèque qui standardise l’authentification multi-fournisseur pour les applications Web. Il a été créé pour être puissant et flexible et pour faire le moins possible. Tout développeur peut créer Stratégies pour OmniAuth, qui peut authentifier les utilisateurs sur différents systèmes. Les stratégies OmniAuth sont conçues pour tout, de Facebook à LDAP.

Pour utiliser OmniAuth dans vos applications, vous devez utiliser une ou plusieurs stratégies. Ces stratégies sont généralement publiées individuellement en tant que RubyGems, et vous pouvez voir un Liste tenue à jour par la communauté
dans le wiki de ce projet.

Une stratégie appelée Developer, est inclus avec OmniAuth et offre une stratégie de non-production totalement non sécurisée qui demande directement à un utilisateur des informations d’authentification, puis les transmet directement. Vous pouvez l’utiliser comme espace réservé lorsque vous commencez à développer et échanger facilement d’autres stratégies plus tard.

A débuté

Chaque stratégie OmniAuth est un middleware de rack. Cela signifie que vous pouvez l’utiliser comme n’importe quel autre middleware de rack. Par exemple, pour utiliser la stratégie de développement intégrée dans une application Sinatra, procédez comme suit:

require 'sinatra'
require 'omniauth'

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

Parce que c’est pour cela qu’OmniAuth est conçu Multi-fournisseur En ce qui concerne l’authentification, vous voudrez peut-être laisser de la place pour exécuter plusieurs stratégies. C’est ce que le intégré
OmniAuth::Builder La classe vous offre un moyen simple de spécifier plusieurs stratégies. Notez qu’il y a aucune différence entre le code suivant et l’utilisation de chaque stratégie individuellement comme middleware. Voici un exemple que vous pouvez insérer dans un initialiseur Rails à
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

Vous devez consulter la documentation de chaque fournisseur que vous utilisez pour connaître les exigences d’initialisation spécifiques.

Intégration d’OmniAuth dans votre application

OmniAuth est une bibliothèque extrêmement sans contact. Il s’agit d’une boîte noire vers laquelle vous pouvez envoyer les utilisateurs de votre application lorsqu’ils ont besoin d’une authentification, puis récupérer des informations. OmniAuth a été conçu intentionnellement pour ne pas mapper automatiquement un modèle d’utilisateur ou émettre des hypothèses sur le nombre de méthodes d’authentification que vous pourriez vouloir utiliser ou ce que vous voulez faire avec les données une fois qu’un utilisateur s’est authentifié. Cela rend OmniAuth incroyablement flexible. Pour utiliser OmniAuth, il vous suffit de rediriger les utilisateurs /auth/:provider, Où :provider
est le nom de la stratégie (par ex. developer ou alors twitter). À partir de là, OmniAuth prend le relais et guide l’utilisateur à travers les étapes nécessaires pour s’authentifier à l’aide de la stratégie choisie.

Que faites-vous ensuite une fois l’utilisateur authentifié? OmniAuth définit simplement un hachage spécial appelé hachage d’authentification dans l’environnement de rack d’une demande pour /auth/:provider/callback. Ce hachage contient autant d’informations sur l’utilisateur qu’OmniAuth pourrait en déduire de la stratégie utilisée. Vous devez configurer un point de terminaison dans votre application qui correspond à l’URL de rappel, puis suivre les étapes requises par votre application. Par exemple, dans une application Rails, vous ajouteriez une ligne à votre application routes.rb Fichier comme suit:

post '/auth/:provider/callback', to: 'sessions#create'

Et puis tu pourrais en avoir un SessionsController avec un code qui ressemble à ceci:

class SessionsController < ApplicationController
  # If you're using a strategy that POSTs during callback, you'll need to skip the authenticity token check for the callback action only. 
  skip_before_action :verify_authenticity_token, only: :create

  def create
    @user = User.find_or_create_from_auth_hash(auth_hash)
    self.current_user = @user
    redirect_to '/'
  end

  protected

  def auth_hash
    request.env['omniauth.auth']
  end
end

le omniauth.auth La clé de hachage d’environnement fournit un hachage d’authentification qui contient des informations sur l’utilisateur qui vient d’être authentifié, y compris un identifiant unique, la stratégie qu’il vient d’utiliser pour s’authentifier et des informations personnelles telles que son nom et son adresse e-mail, le cas échéant. Pour une description complète de ce que le hachage d’authentification peut contenir, consultez le Page Wiki Auth Hash Schema.

Notez qu’OmniAuth n’effectuera aucune action autre que la définition de certaines informations environnementales pour la demande de rappel. La manière dont vous souhaitez implémenter les détails du flux d’authentification de votre application dépend entièrement de vous.

Veuillez noter: Il existe actuellement une vulnérabilité CSRF affectant OmniAuth (désigné) CVE-2015-9284) qui nécessitent une atténuation au niveau de l’application. Plus de détails peuvent être trouvés sur le Wiki.

Configurer le origin Param

le origin Le paramètre url est généralement utilisé pour indiquer d’où vient un utilisateur et où il doit retourner au cas où vous souhaiteriez l’utiliser.

Il existe trois options possibles:

Débit standard:

# /auth/twitter/?origin=[URL]
# No change
# If blank, `omniauth.origin` is set to HTTP_REFERER

Renommer le paramètre d’origine:

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

Désactivation du paramètre d’origine:

# /auth/twitter
# Origin handled externally, if need be. `omniauth.origin` is not set
provider :twitter, ENV['KEY'], ENV['SECRET'], origin_param: false

Intégration d’OmniAuth dans votre API Rails

Le middleware suivant est inclus (par défaut) pour la gestion de session dans les applications Rails. Si vous utilisez OmniAuth avec une API Rails, vous devrez ajouter l’un de ces middleware requis dans:

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

L’astuce pour les ajouter en retour est qu’ils sont transmis par défaut
session_options Une fois ajouté (y compris la clé de session), vous ne pouvez pas simplement en ajouter une session_store.rb Ajouter un initialiseur use ActionDispatch::Session::CookieStore
et ayez des sessions qui fonctionnent comme d’habitude.

Pour être clair, les sessions peuvent fonctionner, mais vos options de session seront ignorées (c’est-à-dire que la clé de session est utilisée par défaut _session_id). Au lieu de l’initialiseur, vous devez définir les options appropriées quelque part avant que votre middleware ne soit construit (ex. application.rb) et transmettez-le à votre middleware préféré comme suit:

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)

Enregistrement

OmniAuth prend en charge un enregistreur configurable. Par défaut, OmniAuth se connecte à STDOUT Cependant, vous pouvez le configurer avec OmniAuth.config.logger::

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

Ressources

le Wiki OmniAuth a activement maintenu une documentation complète pour OmniAuth. Ce devrait être votre premier arrêt si vous vous demandez une plongée plus approfondie dans OmniAuth, comment cela fonctionne et utilise.

OmniAuth pour les entreprises

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. Gagnez du temps, réduisez les risques et améliorez la WordPress Divi du code tout en payant les responsables pour les packages exacts que vous utilisez. Apprendre encore plus.

Versions de Ruby prises en charge

OmniAuth est testé sous 2.5, 2.6, 2.7, Truffleruby et JRuby.

Gestion des versions

Cette bibliothèque doit être respectée Versionnage sémantique 2.0.0. Les violations de ce schéma doivent être signalées comme des erreurs. En particulier, si une version mineure ou un correctif est publiée qui affecte la compatibilité descendante, cette version doit être supprimée immédiatement et / ou une nouvelle version publiée immédiatement qui rétablit la compatibilité. Les modifications apportées à l’API publique ne seront introduites qu’avec les nouvelles versions majeures. À la suite de cette directive, vous pouvez (et devriez) spécifier une dépendance sur ce joyau en utilisant Limitation de version pessimiste avec deux chiffres de précision. Par example:

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

Licence

Copyright (c) 2010-2017 Michael Bleigh et Intridea, Inc. Voir LICENCE pour plus de détails.



Source link

Recent Posts