omniauth

Omniauth: การรับรองความถูกต้องแบบหลายผู้ให้บริการมาตรฐาน

นี่คือเอกสารประกอบสำหรับสาขาการพัฒนาของ Omniauth คุณสามารถค้นหาเอกสารสำหรับการเปิดตัวที่มีเสถียรภาพล่าสุดได้ที่นี่

บทนำ

Omniauth เป็นไลบรารีที่สร้างมาตรฐานการรับรองความถูกต้องแบบหลายผู้ให้บริการสำหรับเว็บแอปพลิเคชัน มันถูกสร้างขึ้นให้มีประสิทธิภาพยืดหยุ่นและทำให้น้อยที่สุด นักพัฒนาทุกคนสามารถสร้าง กลยุทธ์ สำหรับ omniauth ที่สามารถตรวจสอบสิทธิ์ผู้ใช้ผ่านระบบที่แตกต่างกัน กลยุทธ์ Omniauth ถูกสร้างขึ้นสำหรับทุกสิ่งตั้งแต่ Facebook ไปจนถึง LDAP

ในการใช้ Omniauth ในแอปพลิเคชันของคุณคุณจะต้องใช้ประโยชน์จากกลยุทธ์อย่างน้อยหนึ่งอย่าง กลยุทธ์เหล่านี้โดยทั่วไปจะถูกปล่อยออกมาเป็นรายบุคคลเป็น Rubygems และคุณสามารถดูรายการชุมชนที่ได้รับการดูแลในวิกิสำหรับโครงการนี้

กลยุทธ์หนึ่งที่เรียกว่า Developer นั้นรวมอยู่ใน Omniauth และให้กลยุทธ์ที่ไม่ปลอดภัยและไม่สามารถใช้งานได้อย่างสมบูรณ์ซึ่งจะแจ้งให้ผู้ใช้ทราบข้อมูลการตรวจสอบสิทธิ์โดยตรงจากนั้นส่งผ่านโดยตรง คุณสามารถใช้เป็นตัวยึดตำแหน่งเมื่อคุณเริ่มพัฒนาและสลับในกลยุทธ์อื่น ๆ ได้อย่างง่ายดายในภายหลัง

เริ่มต้น

กลยุทธ์ Omniauth แต่ละตัวเป็นมิดเดิลแวร์ชั้นวาง นั่นหมายความว่าคุณสามารถใช้มันในลักษณะเดียวกับที่คุณใช้มิดเดิลแวร์ชั้นวางอื่น ๆ ตัวอย่างเช่นในการใช้กลยุทธ์นักพัฒนาในตัวในแอปพลิเคชัน Sinatra คุณอาจทำสิ่งนี้:

 require 'sinatra'
require 'omniauth'

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

เนื่องจาก Omniauth ถูกสร้างขึ้นสำหรับการตรวจสอบความถูกต้อง แบบหลายผู้ให้บริการ คุณอาจต้องการออกจากห้องเพื่อใช้กลยุทธ์หลายอย่าง สำหรับสิ่งนี้คลาส OmniAuth::Builder ในตัวให้วิธีง่ายๆในการระบุกลยุทธ์หลายอย่าง โปรดทราบว่า ไม่มีความแตกต่าง ระหว่างรหัสต่อไปนี้และการใช้แต่ละกลยุทธ์เป็นรายบุคคลเป็นมิดเดิลแวร์ นี่เป็นตัวอย่างที่คุณอาจใส่ลงใน Rails Initializer ที่ 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

คุณควรดูเอกสารสำหรับผู้ให้บริการแต่ละรายที่คุณใช้สำหรับข้อกำหนดการเริ่มต้นเฉพาะ

การรวม Omniauth เข้ากับแอปพลิเคชันของคุณ

Omniauth เป็นห้องสมุดสัมผัสต่ำมาก มันถูกออกแบบมาให้เป็นกล่องดำที่คุณสามารถส่งผู้ใช้แอปพลิเคชันของคุณไปยังเมื่อคุณต้องการการรับรองความถูกต้องแล้วรับข้อมูลกลับมา Omniauth ถูกสร้างขึ้นโดยเจตนาไม่เชื่อมโยงกับโมเดลผู้ใช้โดยอัตโนมัติหรือตั้งสมมติฐานเกี่ยวกับจำนวนวิธีการตรวจสอบความถูกต้องที่คุณอาจต้องการใช้หรือสิ่งที่คุณอาจต้องการทำกับข้อมูลเมื่อผู้ใช้รับรองความถูกต้อง สิ่งนี้ทำให้ Omniauth มีความยืดหยุ่นอย่างไม่น่าเชื่อ ในการใช้ Omniauth คุณต้องเปลี่ยนเส้นทางผู้ใช้ไปยัง /auth/:provider โดยที่ :provider คือชื่อของกลยุทธ์ (ตัวอย่างเช่น developer หรือ twitter ) จากตรงนั้น Omniauth จะเข้าครอบครองและนำผู้ใช้ผ่านขั้นตอนที่จำเป็นเพื่อตรวจสอบสิทธิ์ด้วยกลยุทธ์ที่เลือก

เมื่อผู้ใช้รับรองความถูกต้องแล้วคุณจะทำอะไรต่อไป? Omniauth เพียงแค่ตั้งแฮชพิเศษที่เรียกว่าแฮชการตรวจสอบความถูกต้องบนสภาพแวดล้อมชั้นวางของคำขอ /auth/:provider/callback แฮชนี้มีข้อมูลมากเกี่ยวกับผู้ใช้เช่นเดียวกับ Omniauth สามารถรวบรวมได้จากกลยุทธ์ที่ใช้ คุณควรตั้งค่าจุดสิ้นสุดในแอปพลิเคชันของคุณที่ตรงกับ URL การโทรกลับจากนั้นทำตามขั้นตอนใด ๆ ที่จำเป็นสำหรับแอปพลิเคชันของคุณ

คีย์ omniauth.auth ในสภาพแวดล้อมแฮชจัดเตรียมแฮชการตรวจสอบความถูกต้องซึ่งจะมีข้อมูลเกี่ยวกับผู้ใช้ที่ได้รับการรับรองความถูกต้องรวมถึงรหัสที่ไม่ซ้ำกันกลยุทธ์ที่พวกเขาใช้สำหรับการตรวจสอบและรายละเอียดส่วนบุคคลเช่นชื่อและที่อยู่อีเมลตามที่มีอยู่ สำหรับคำอธิบายเชิงลึกเกี่ยวกับสิ่งที่แฮชการตรวจสอบความถูกต้องอาจมีให้ดูที่หน้า Auth Hash Schema Wiki

โปรดทราบว่า Omniauth ไม่ได้ดำเนินการใด ๆ นอกเหนือจากการตั้งค่าข้อมูลสภาพแวดล้อมบางอย่างในคำขอโทรกลับ มันขึ้นอยู่กับคุณว่าคุณต้องการใช้รายละเอียดของโฟลว์การตรวจสอบสิทธิ์ของแอปพลิเคชันของคุณอย่างไร

Rack_csrf

omniauth ไม่เข้ากันได้กับ ootb กับ Rack_csrf ในการทำเช่นนั้นจำเป็นต้องเพิ่มรหัสต่อไปนี้ในรหัส Bootstrapping แอปพลิเคชัน:

 OmniAuth :: AuthenticityTokenProtection . default_options ( key : "csrf.token" , authenticity_param : "_csrf" ) 

ราง (โดยไม่ต้องคิดค้น)

ในการเริ่มต้นใช้งานเพิ่มอัญมณีต่อไปนี้

Gemfile :

 gem 'omniauth'
gem "omniauth-rails_csrf_protection"

จากนั้นแทรก omniauth เป็นมิดเดิลแวร์

config/initializers/omniauth.rb :

 Rails . application . config . middleware . use OmniAuth :: Builder do
  provider :developer if Rails . env . development?
end

ผู้ให้บริการเพิ่มเติมสามารถเพิ่มได้ที่นี่ในอนาคต ต่อไปเราจะส่งสายทั้งหมดโดยใช้เส้นทางคอนโทรลเลอร์และมุมมองเข้าสู่ระบบ

config/route.rb :

  get 'auth/:provider/callback' , to : 'sessions#create'
  get '/login' , to : 'sessions#new'

แอพ/คอนโทรลเลอร์/เซสชัน _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
end

แอพ/มุมมอง/เซสชัน/new.html.erb :

 <%= form_tag('/auth/developer', method: 'post', data: {turbo: false}) do %>
  < button type =' submit ' > Login with Developer </ button >
<% end %>

ตอนนี้ถ้าคุณเยี่ยมชม /login และคลิกปุ่มเข้าสู่ระบบคุณควรเห็นหน้าจอเข้าสู่ระบบของนักพัฒนา Omniauth Developer หลังจากส่งแล้วคุณจะถูกส่งกลับไปยังแอปพลิเคชันของคุณที่ Sessions#create ตอนนี้การเพิ่มควรแสดงรายละเอียด omniauth ทั้งหมดที่คุณมีให้รวมเข้ากับการจัดการผู้ใช้ของคุณเอง

หากคุณต้องการการจัดการผู้ใช้งานนอกกรอบคุณควรพิจารณาใช้ omniauth ผ่านการออกแบบ กรุณาเยี่ยมชมหน้า Disise GitHub สำหรับข้อมูลเพิ่มเติม

Rails API

มิดเดิลแวร์ต่อไปนี้คือ (โดยค่าเริ่มต้น) รวมไว้สำหรับการจัดการเซสชันในแอปพลิเคชัน Rails เมื่อใช้ Omniauth กับ Rails API คุณจะต้องเพิ่มหนึ่งในมิดเดิลแวร์ที่จำเป็นเหล่านี้กลับมา:

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

เคล็ดลับในการเพิ่มสิ่งเหล่านี้กลับมาคือโดยค่าเริ่มต้นพวกเขาจะผ่าน session_options เมื่อเพิ่ม (รวมถึงคีย์เซสชัน) ดังนั้นคุณไม่สามารถเพิ่ม session_store.rb initializer เพิ่ม use ActionDispatch::Session::CookieStore และมีการทำงานตามปกติ

เพื่อให้ชัดเจน: เซสชันอาจใช้งานได้ แต่ตัวเลือกเซสชันของคุณจะถูกละเว้น (เช่นคีย์เซสชันจะเริ่มต้นเป็น _session_id ) แทนที่จะเป็นผู้เริ่มต้นคุณจะต้องตั้งค่าตัวเลือกที่เกี่ยวข้องที่ไหนสักแห่งก่อนที่มิดเดิลแวร์ของคุณจะถูกสร้างขึ้น (เช่น application.rb ) และส่งผ่านไปยังมิดเดิลแวร์ที่คุณต้องการเช่นนี้:

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

(ขอบคุณ @mltsy)

การตัดไม้

Omniauth รองรับตัวบันทึกที่กำหนดค่าได้ โดยค่าเริ่มต้น Omniauth จะเข้าสู่ STDOUT แต่คุณสามารถกำหนดค่านี้ได้โดยใช้ OmniAuth.config.logger :

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

พารามิเตอร์แหล่งกำเนิด

โดยทั่วไปแล้วพารามิเตอร์ origin URL จะใช้เพื่อแจ้งว่าผู้ใช้มาจากไหนและคุณควรเลือกที่จะใช้มันพวกเขาต้องการกลับไป Omniauth รองรับการตั้งค่าต่อไปนี้ซึ่งสามารถกำหนดค่าในระดับผู้ให้บริการ:

ค่าเริ่มต้น :

 provider :twitter , ENV [ 'KEY' ] , ENV [ 'SECRET' ]
POST /auth/twitter /?o rigin = [ URL ]
# If the `origin` parameter is blank, `omniauth.origin` is set to HTTP_REFERER

การใช้พารามิเตอร์ต้นกำเนิดที่มีชื่อแตกต่างกัน :

 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_REFERER

พิการ :

 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. 

ทรัพยากร

Omniauth Wiki ได้จัดทำเอกสารเชิงลึกอย่างแข็งขันสำหรับ Omniauth มันควรจะเป็นจุดแรกของคุณถ้าคุณสงสัยเกี่ยวกับการดูเชิงลึกมากขึ้นที่ omniauth วิธีการทำงานและวิธีการใช้งาน

omniauth สำหรับองค์กร

มีให้เป็นส่วนหนึ่งของการสมัครสมาชิก TideLift

ผู้ดูแลระบบของ Omniauth และแพ็คเกจอื่น ๆ อีกหลายพันรายการกำลังทำงานร่วมกับ TideLift เพื่อให้การสนับสนุนเชิงพาณิชย์และการบำรุงรักษาสำหรับแพ็คเกจโอเพนซอร์สที่คุณใช้เพื่อสร้างแอปพลิเคชันของคุณ ประหยัดเวลาลดความเสี่ยงและปรับปรุงสุขภาพรหัสในขณะที่จ่ายค่ารักษาแพ็คเกจที่แน่นอนที่คุณใช้ เรียนรู้เพิ่มเติม

รุ่นทับทิมที่รองรับ

Omniauth ได้รับการทดสอบภายใต้ 2.5, 2.6, 2.7, 3.0, 3.1, 3.2, Truffleruby และ Jruby

การกำหนดเวอร์ชัน

ห้องสมุดนี้มีจุดมุ่งหมายที่จะปฏิบัติตามเวอร์ชันความหมาย 2.0.0 การละเมิดโครงการนี้ควรรายงานว่าเป็นข้อบกพร่อง โดยเฉพาะอย่างยิ่งหากมีการปล่อยรุ่นรองหรือแพตช์ที่จะแบ่งความเข้ากันได้ย้อนหลังเวอร์ชันนั้นควรจะดึงทันทีและ/หรือเวอร์ชันใหม่ควรได้รับการปล่อยตัวทันทีที่เรียกคืนความเข้ากันได้ การเปลี่ยนแปลงการเปลี่ยนแปลงของ API สาธารณะจะได้รับการแนะนำด้วยเวอร์ชันหลักใหม่เท่านั้น อันเป็นผลมาจากนโยบายนี้คุณสามารถ (และควร) ระบุการพึ่งพาอัญมณีนี้โดยใช้ข้อ จำกัด ในแง่ร้ายของรุ่นที่มีความแม่นยำสองหลัก ตัวอย่างเช่น:

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

ใบอนุญาต

ลิขสิทธิ์ (c) 2010-2017 Michael Bleigh และ Intridea, Inc. ดูรายละเอียดใบอนุญาต