تقدير المشروع
← كل المقالات

إضافة مصادقة GitHub OAuth إلى تطبيق Phoenix

يتطور Phoenix بوتيرة سريعة. سيساعدك هذا الدليل حول دمج OAuth في تطبيق Phoenix على مواكبته.

12 دقائق قراءة
إطار عمل PhoenixGithubمصادقة Github Outhمكتبة OAuthElixir

حلّ العام الجديد، وأصبحت القرارات التي اتخذناها له ذكرى بعيدة، وأخيرًا توفرت لحظة للاستثمار في نمونا كمبرمجين :) . في رأيي المتواضع، لا شيء يوسّع آفاقك أكثر – خاصة في عالم البرمجة الوظيفية – من استكشاف لغات وأطر عمل جديدة، ومعرفة كيف تتعامل مع المشكلات، وربما استلهام أفكار منها أو إضافة أدوات جديدة إلى صندوق أدواتك.

وبما أن 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 في تطبيقك.

آمل أن يكون الدليل قد أعجبك!