إضافة مصادقة GitHub OAuth إلى تطبيق Phoenix
يتطور Phoenix بوتيرة سريعة. سيساعدك هذا الدليل حول دمج OAuth في تطبيق Phoenix على مواكبته.
حلّ العام الجديد، وأصبحت القرارات التي اتخذناها له ذكرى بعيدة، وأخيرًا توفرت لحظة للاستثمار في نمونا كمبرمجين :) . في رأيي المتواضع، لا شيء يوسّع آفاقك أكثر – خاصة في عالم البرمجة الوظيفية – من استكشاف لغات وأطر عمل جديدة، ومعرفة كيف تتعامل مع المشكلات، وربما استلهام أفكار منها أو إضافة أدوات جديدة إلى صندوق أدواتك.
وبما أن Phoenix وElixir يزدادان شعبية (بحسب استطلاع Stack Overflow للمطورين لعام 2022 على الأقل)، قررت تجربتهما.
Elixir لغة وظيفية، لكنها ديناميكية الأنواع، وهو أمر يبدو غريبًا لمن كتب Scala لسنوات طويلة. ومع ذلك فهي ممتعة – على الأقل في المشاريع القليلة التي بنيتها بها حتى الآن. وكل من كتب شيئًا يومًا ما بـ Ruby On Rails (كما فعلت قبل بضعة عقود ;) ) سيلاحظ سريعًا أن الفكرة هي نفسها تقريبًا، لكن بلغة برمجة وظيفية تعمل في الخلفية، وهذا شعور جيد حقًا.
يمكن أن يكون إطار عمل Phoenix أداة مفيدة – بالتأكيد للخدمات المصغّرة البسيطة التي توفر ميزات CRUD، من النوع الذي اعتدنا بناءه بإطار عمل Play، لكن ربما لما هو أكثر بكثير، وصولًا إلى تطبيق إنتاجي كامل، خاصة بفضل ميزة LiveView التي لا يغطيها هذا الدليل.
أول عقبة ستواجهها على الأرجح أثناء استكشاف الإطار والتجريب هي أن Phoenix يتغير كثيرًا، لذا لا تعمل أشياء كثيرة كما هو موصوف عند اتباع الدروس أو الدورات على الإنترنت التي مضى عليها أكثر من عام تقريبًا. واجهت ذلك تمامًا عند محاولة استخدام مكتبة OAuth مع مزوّد خارجي، ولهذا قررت إضافة تدوينة أخرى عن OAuth مع Phoenix. ستجد أدناه كل خطوة لازمة لدمج OAuth في تطبيق Phoenix الخاص بك. استمتع!
الخطوات الأولى
1 أنشئ مشروعًا جديدًا
mix phx.new oauth_tutorial
عند سؤالك عن تنزيل الاعتماديات، اختر ‘Y’
2 عدّل config/dev.exs لضبط بيانات اعتماد خادم قاعدة البيانات
# Configure your database
config :oauth_tutorial, OauthTutorial.Repo,
username: "postgres",
password: "your-password-goes-here",
hostname: "localhost",
database: "oauth_tutorial_dev",
stacktrace: true,
show_sensitive_data_on_connection_error: true,
pool_size: 10
3 أضف المنطق الخاص بتخزين المستخدمين وإدارتهم
mix phx.gen.schema Accounts.User users email:string:unique provider:string token:string
يمنحنا تشغيل هذا الأمر
- سياقًا جديدًا باسم
accountsفيlib/oauth_tutorial/accounts - مخطط User باسم
user.exفيlib/oauth_tutorial/accounts/user.ex - ملف ترحيل (migration) مختومًا بوقت إنشائه في المجلد
priv/repo/migrations
المخطط (Schema)
defmodule OauthTutorial.Accounts.User do
use Ecto.Schema
import Ecto.Changeset
schema "users" do
field :email, :string
field :provider, :string
field :token, :string
timestamps()
end
@doc false
def changeset(user, attrs) do
user
|> cast(attrs, [:email, :provider, :token])
|> validate_required([:email, :provider, :token])
|> unique_constraint(:email)
end
end
يحتوي مخطط المستخدم على كل تعريفات الحقول التي مررناها كوسائط إلى مولّد مخططات Phoenix. وإضافة إلى ذلك، يضيف الإطار تلقائيًا بعض الحقول (created_at, updated_at) عبر الدالة timestamps() في نهاية تعريف المخطط. يمكننا حذفها بالطبع، لكن الإبقاء عليها لا يضر، على الأقل في مشروع كهذا.
الترحيل (Migration)
defmodule OauthTutorial.Repo.Migrations.CreateUsers do
use Ecto.Migration
def change do
create table(:users) do
add :email, :string
add :provider, :string
add :token, :string
timestamps()
end
create unique_index(:users, [:email])
end
end
يعتمد إطار عمل Phoenix على مكتبة Ecto في كل التعاملات مع قاعدة البيانات، إلى جانب آلية ترحيل تتيح لنا بناء مخطط قاعدة البيانات وتعديل الجداول الموجودة وإضافة الفهارس وغير ذلك.
شغّل الترحيل لإنشاء قاعدة البيانات وجدول المستخدمين الوحيد الموصوف في ملف الترحيل الذي ولّده الأمر السابق.
mix ecto.create - ينشئ قاعدة بيانات على خادم قاعدة البيانات لدينا
mix ecto.migrate - ينفّذ عمليات الترحيل الموجودة في مجلد migrations
يمكنك الآن تسجيل الدخول إلى قاعدة بياناتك ورؤية الجداول التي أُنشئت لك؛ ويتضمن جدول المستخدمين حقولًا إضافية نتجت عن استدعاء timestamp() في مخططنا.
وحدة التحكم في المصادقة (Auth Controller)
بعد ذلك، عرّف وحدة تحكم مسؤولة عن منطق التفويض لدينا: ستتيح لنا تسجيل الدخول إلى التطبيق والخروج منه واستقبال البيانات من مزوّد OAuth الخارجي (GitHub في حالتنا) ضمن مسار مصادقة OAuth القياسي.
قبل كتابة كود وحدة التحكم نفسها، علينا إضافة مكتبة إلى المشروع تساعدنا في مصادقة OAuth. اسمها Ueberauth وهي توفر تكاملات مع مجموعة واسعة من المزوّدين. يمكنك معرفة المزيد عن المكتبة في صفحات المشروع على GitHub هنا.
أضف اعتماديتين إلى الدالة deps في الملف mix.exs:
{:ueberauth, "~> 0.7.0"},
{:ueberauth_github, "~> 0.8.1"}
عدّل ملف الإعدادات مرة أخرى وأضف إدخالين جديدين في نهايته:
config :ueberauth, Ueberauth,
providers: [
github: {Ueberauth.Strategy.Github, [default_scope: "user:email"]}
]
config :ueberauth, Ueberauth.Strategy.Github.OAuth,
client_id: "your-client-id",
client_secret: "your-client-secret"
للحصول على قيمتي clientId وclientSecret، سجّل الدخول إلى حسابك في GitHub وانتقل إلى Settings -> Developer Settings (في أسفل الصفحة تمامًا) -> OAuth Apps -> New OAuth App
بعد إضافة المكتبة وضبط الإعدادات، يمكننا مرة أخرى اللجوء إلى صديقنا mix لجلب الاعتماديات وتثبيتها:
mix deps.get
الآن يمكننا إنشاء وحدة التحكم وإجراء بعض الفحوصات الأساسية لمعرفة ما إذا كان التكامل يعمل كما نريد.
أنشئ ملفًا باسم auth_controller.ex في المجلد lib/oauth_tutorial_web/controllers.
في الوقت الحالي، لن تحتوي وحدة التحكم هذه إلا على دالة callback التي تعالج نتيجة المصادقة المرسلة من GitHub. ولجعل وحدة التحكم تستخدم مكتبة Ueberauth، علينا إضافة plug Ueberauth، وبعدها نكون قد أنهينا تقريبًا.
defmodule OauthTutorialWeb.AuthController do
use OauthTutorialWeb, :controller
plug Ueberauth
def callback(conn, params) do
IO.inspect(conn)
IO.inspect(params)
end
end
غير أن وحدة التحكم لن تعمل إلا بعد ضبط التوجيه في ملف router.ex الخاص بالمشروع. سنضيف نطاقًا (scope) جديدًا لمنطق المصادقة، يعالج حاليًا طلبين فقط:
1 طلب تتولاه مكتبة Ueberauth بنفسها لتوجيهنا إلى مزوّدنا
2 طلب يعالج الاستدعاءات العائدة من المزوّد.
scope "/auth", OauthTutorialWeb do
pipe_through :browser
get "/:provider", AuthController, :request
get "/:provider/callback", AuthController, :callback
end
ربما لاحظت أن دالة callback لدينا تكتفي بفحص البيانات الواردة. هذه ليست الطريقة المعتادة في Phoenix لمعالجة الطلبات في دوال وحدة التحكم، لذا توقع استثناءً كبيرًا بمجرد عودة هذه الدالة – لكن وحدة التحكم ستعرض لك كل البيانات التي أرسلها GitHub بعد مصادقة ناجحة.
شغّل التطبيق بالأمر mix phx.server وافتح http://localhost:4000/auth/github. يجب أن تُحوَّل تلقائيًا إلى صفحة تفويض في GitHub، حيث يمكنك السماح لتطبيق جديد باستخدام بيانات من حسابك. بعد أن تمنح التفويض، يعيد Github توجيه الطلب إلى دالة callback لدينا، التي تطبع القيم المستلمة مع استثناء كبير بخصوص عدم معالجة الكائن conn بشكل صحيح – لا تقلق بشأنه الآن، سنعالجه قريبًا.
بعد ذلك، لنحفظ بعض البيانات المستلمة من GitHub وننشئ مستخدمًا جديدًا في قاعدة بياناتنا.
تخزين البيانات

سنمر على الخطوات الموضحة في المخطط أعلاه. في البداية، نستخرج المعلومات اللازمة لإنشاء مستخدم جديد في قاعدة البيانات. ولفعل ذلك، نطبّق مطابقة الأنماط على قائمة وسائط الدالة callback:
def callback(%{assigns: %{ueberauth_auth: auth}} = conn, params) do
user_data = %{token: auth.credentials.token, email: auth.info.email, provider: "github"}
……
end
بعد حصولنا على البيانات، يمكننا إما البحث عن مستخدم موجود عبر البريد الإلكتروني المقدم أو إنشاء مستخدم جديد إن لم يوجد. يتطلب ذلك بناء changeset للمخطط واستدعاء بعض دوال repo. لنكتب دالة تجد مستخدمًا موجودًا أو تنشئ واحدًا، اعتمادًا على خريطة المعاملات المرسلة مع الاستدعاء:
defp findOrCreateUser(user_data) do
changeset = User.changeset(%User{}, user_data)
case Repo.get_by(User, email: changeset.changes.email) do
nil ->
IO.puts("User not found, creating new one")
Repo.insert(changeset)
user -> {:ok, user}
end
end
بعد ذلك، يمكننا ربط هذه الدالة وتنفيذ بقية المنطق داخل دالة callback، على النحو التالي:
def callback(%{assigns: %{ueberauth_auth: auth}} = conn, params) do
user_data = %{token: auth.credentials.token, email: auth.info.email, provider: "github"}
case findOrCreateUser(user_data) do
{:ok, user} ->
conn
|> put_flash(:info, "Welcome to OAuth Tutorial!")
|> put_session(:user_id, user.id)
|> redirect(to: "/")
{:error, changeset} ->
conn
|> put_flash(:error, "Something went wrong")
|> redirect(to: "/")
end
end
شغّل التطبيق مرة أخرى بالأمر mix phx.server، ويجب أن تظهر رسالة flash في الصفحة الرئيسية.
وظيفة تسجيل الخروج
تسجيل الدخول نصف القصة فقط – فبعد تسجيل الدخول نحتاج أيضًا إلى طريقة لتسجيل الخروج ومسح الجلسة. لتحقيق ذلك، نضيف دالة جديدة في وحدة التحكم ونربطها بنقطة نهاية نختارها في الملف router.ex.
def signout(conn, _params) do
conn
|> configure_session(drop: true)
|> redirect(to: Routes.page_path(conn, :index))
end
get "/signout", AuthController, :signout
تأكد من وضع هذا المسار قبل المسار /:provider؛ وإلا فسيُطابَق مسار المزوّد أولًا وسيعامل الكلمة signout كأنها مزوّد OAuth.
الأداة (Widget)
لدينا الآن تسجيل الدخول والخروج، ومن المفيد وضعهما في جزء مشترك من القالب حيث يمكننا فحص حالة الجلسة وتشغيل إجراءات تسجيل الدخول/الخروج وفقًا لذلك.
في القالب الافتراضي سنعرض الرابط Log In أو Log Out إلى جانب الروابط الأخرى في الزاوية العليا اليمنى من الترويسة.
ورغم أن كائن الجلسة لدينا يحتوي على user_id، فمن الأنسب كثيرًا أن يكون لدينا كائن مستخدم يمكننا قراءة خصائصه، مثلًا لتعيين صورة رمزية بناءً على البريد الإلكتروني للمستخدم. للحصول على واحد، سنعتمد على أداة Phoenix مفيدة تسمى plug. سنكتب plug صغيرًا يصبح جزءًا من مسار معالجة الطلب: يتحقق مما إذا كان user_id موجودًا في الجلسة، ويجلب كائن user المقابل من قاعدة البيانات ويسنده إلى كائن الاتصال، مما يجعله متاحًا عالميًا أينما احتجنا إليه.
defmodule OauthTutorial.Plugs.SetUser do
import Plug.Conn
import Phoenix.Controller
alias OauthTutorial.Repo
alias OauthTutorial.Accounts.User
def init(opts), do: opts
def call(conn, _opts) do
user_id = get_session(conn, :user_id)
cond do
user = user_id && Repo.get(User, user_id)->
assign(conn, :user, user)
true ->
assign(conn, :user, nil)
end
end
end
لاستخدام الـ plug، أضفه ببساطة إلى مسار معالجة الطلب في الملف router.ex:
pipeline :browser do
plug :accepts, ["html"]
plug :fetch_session
plug :fetch_live_flash
plug :put_root_layout, {OauthTutorialWeb.LayoutView, :root}
plug :protect_from_forgery
plug :put_secure_browser_headers
plug OauthTutorial.Plugs.SetUser
end
أخيرًا، وسّع القائمة في الترويسة ببعض العناصر الإضافية. تُعرَّف الترويسة في oauth_tutorial_web/templates/layout/root.html.heex
<ul>
<li><a href="https://hexdocs.pm/phoenix/overview.html">Get Started</a></li>
<%= if function_exported?(Routes, :live_dashboard_path, 2) do %>
<li><%= link "LiveDashboard", to: Routes.live_dashboard_path(@conn, :home) %></li>
<% end %>
<%= if @conn.assigns[:user] do %>
<li><%= link "Logout", to: Routes.auth_path(@conn, :signout) %></li>
<% else %>
<li>
<%= link "Sign in with Github", to: Routes.auth_path(@conn, :request, "github") %>
</li>
<% end %>
</ul>
ممتاز – يجب أن تتمكن الآن من تسجيل الدخول والخروج باستخدام GitHub كمزوّد OAuth. في الجزء الأخير من هذا الدليل، سنحمي بعض الموارد من الوصول غير المصرح به؛ أي سننشئ مورد ويب لا يظهر إلا بعد تسجيل الدخول.
حماية الموارد
لنُنشئ وظيفة قائمة مهام في تطبيق Phoenix لدينا. في Phoenix يستغرق ذلك بطبيعة الحال بضعة أوامر فقط:
mix phx.gen.html Todos Todo todos content:text user_id:references:users
بعد ذلك، سنعدّل مخططاتنا قليلًا لنخبر Ecto أن المستخدم الواحد يمكن أن يملك عدة مهام وأن كل مهمة تنتمي إلى مستخدم محدد. للقيام بذلك، عدّل المخططات هكذا:
مخطط User:
schema "users" do
field :email, :string
field :provider, :string
field :token, :string
has_many :todos, OauthTutorial.Todos.Todo
timestamps()
end
مخطط Todo:
schema "todos" do
field :content, :string
belongs_to :user, OauthTutorial.Accounts.User
timestamps()
end
الآن لنحدّث router.ex لتمكين معالجة المهام:
scope "/", OauthTutorialWeb do
pipe_through :browser
get "/", PageController, :index
resources "/todos", TodoController
end
كما هو موضح أعلاه، بدلًا من تعريف كل دالة مثل GET/POST/PUT/DELETE على حدة، نستخدم الماكرو المدمج في Phoenix resources، الذي يولّد مسارات ‘Restful’ للمورد المعطى نيابةً عنا.
يمكنك الآن فتح التطبيق والانتقال إلى /todos وتجربة وظيفة Todo.
حان وقت حماية مهامنا من الوصول غير المصرح به. سنكتب plug آخر يتحقق مما إذا كنت مسجلًا للدخول، وإن لم تكن كذلك يعيد توجيهك إلى الصفحة الرئيسية مع رسالة flash مناسبة تفيد بتعذر الوصول إلى المورد المطلوب.
defmodule OauthTutorial.Plugs.RequireAuth do
import Plug.Conn
import Phoenix.Controller
alias OauthTutorialWeb.Router.Helpers, as: Routes
def init(_params) do
end
def call(conn, _params) do
if conn.assigns[:user] do
conn
else
conn
|> put_flash(:error, "You are not authorized to access requested page.")
|> redirect(to: Routes.page_path(conn, :index))
|> halt()
end
end
end
لن نستخدم هذا الـ plug في الموجّه (router)؛ بل سنضعه مباشرة في وحدة التحكم، حيث نحدد صراحةً الدوال التي يجب حمايتها. بهذه الطريقة يمكنك مثلًا السماح لكل مستخدم بعرض المهام مع حصر تعديل البيانات بالمستخدمين المصرح لهم فقط.
في الملف todo_controller.ex الذي أُنشئ حديثًا، أضف require_auth على النحو التالي:
plug OauthTutorial.Plugs.RequireAuth when action in [:index, :new, :create, :show, :edit, :update, :delete]
إذا حاولت فتح صفحة المهام دون تسجيل الدخول، فيجب أن تحصل على رسالة الوصول غير المصرح به، كما هو موضح أدناه:
لمزيد من الراحة، سنضيف رابطًا إلى صفحة المهام بجانب الروابط الأخرى في الجانب الأيمن من الترويسة (بدلًا من الرابط الافتراضي Get Started)
<li><%= link "Todos", to: Routes.todo_path(@conn, :index) %></li>
ملاحظات ختامية
جاء هذا الدليل طويلًا نوعًا ما، لأنني أردت استعراض كل خطوة بالتفصيل، لكن في جوهره تتلخص إضافة OAuth إلى تطبيق Phoenix في بضع عمليات استيراد وبضعة تغييرات أخرى في الإعدادات وplug مخصص أو اثنين يدمجان OAuth في تطبيقك.
آمل أن يكون الدليل قد أعجبك!