Գնահատել նախագիծը
← Բոլոր հրապարակումները

GitHub OAuth նույնականացման ավելացումը Phoenix հավելվածին

Phoenix-ը զարգանում է արագ տեմպերով։ Phoenix հավելվածում OAuth ինտեգրելու այս ձեռնարկը կօգնի ձեզ համընթաց քայլել դրա հետ։

12 րոպե
Phoenix frameworkGithubGithub Outh AuthenticationOAuth libraryElixir

Նոր տարին եկել է, դրա համար արված որոշումներն արդեն հեռու հիշողություն են, և վերջապես ժամանակ է գտնվել ներդրում անելու մեր աճի մեջ որպես ծրագրավորողներ :) ։ Իմ համեստ կարծիքով՝ ոչինչ այնպես չի լայնացնում մտահորիզոնը, հատկապես ֆունկցիոնալ ծրագրավորման աշխարհում, ինչպես այլ լեզուների և նոր ֆրեյմվորքների ուսումնասիրությունը, տեսնելը, թե ինչպես են դրանք լուծում խնդիրները, և հնարավոր է՝ ոգեշնչում ստանալը կամ գործիքակազմը նոր գործիքներով համալրելը։

Քանի որ Phoenix-ն ու Elixir-ը շարունակում են ժողովրդականություն վայելել (գոնե Stack Overflow Developers Survey 2022-ի համաձայն), ես որոշեցի փորձել դրանք։

Elixir-ը ֆունկցիոնալ լեզու է, սակայն դինամիկ տիպավորմամբ, ինչը բավականին տարօրինակ է թվում այն մարդու համար, ով երկար տարիներ գրել է Scala-ով։ Այդուհանդերձ, այն հաճելի է՝ գոնե այն մի քանի նախագծերում, որոնք ես մինչ այժմ կառուցել եմ դրանով։ Ով երբևէ ինչ-որ բան գրել է Ruby On Rails-ով (ինչպես ես՝ մի քանի տասնամյակ առաջ ;) ), շուտով կնկատի, որ գաղափարը գրեթե նույնն է, պարզապես ներքևում աշխատում է ֆունկցիոնալ ծրագրավորման լեզու, և դա իսկապես լավ է զգացվում։

Phoenix ֆրեյմվորքը կարող է օգտակար գործիք լինել՝ անշուշտ CRUD հնարավորություններ առաջարկող պարզ միկրոսերվիսների համար, ինչպիսիք մենք կառուցում էինք Play framework-ով, բայց հավանաբար շատ ավելիի համար՝ մինչև լիարժեք արտադրական հավելված, հատկապես իր LiveView հնարավորության շնորհիվ, որը այս ձեռնարկում չի քննարկվում։

Առաջին խոչընդոտը, որին հավանաբար կհանդիպեք ֆրեյմվորքը ուսումնասիրելիս և փորձարկելիս, այն է, որ Phoenix-ը շատ է փոխվում, ուստի շատ բաներ այնպես չեն աշխատում, ինչպես նկարագրված է մոտ մեկ տարուց ավելի հին առցանց ձեռնարկներում կամ դասընթացներում։ Ես հենց դրան բախվեցի՝ փորձելով օգտագործել OAuth գրադարանը երրորդ կողմի պրովայդերի հետ, ուստի որոշեցի ավելացնել ևս մեկ բլոգային գրառում Phoenix-ով OAuth-ի մասին։ Ստորև կգտնեք բոլոր քայլերը, որոնք անհրաժեշտ են 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-ում
  • ստեղծման ժամանակով դրոշմված միգրացիայի ֆայլ priv/repo/migrations թղթապանակում

Սխեմա

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

User սխեման պարունակում է բոլոր դաշտերի սահմանումները, որոնք մենք փոխանցեցինք որպես արգումենտներ Phoenix-ի սխեմաների գեներատորին։ Դրանից բացի՝ ֆրեյմվորքն ավտոմատ ավելացնում է մի քանի դաշտ (created_at, updated_at) սխեմայի սահմանման վերջում գտնվող timestamps() մեթոդի միջոցով։ Մենք, իհարկե, կարող ենք այն հեռացնել, սակայն թողնելը վնաս չի տա, գոնե այսպիսի նախագծում։

Միգրացիա

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 գրադարանի վրա, ինչպես նաև միգրացիաների մեխանիզմի, որը թույլ է տալիս կառուցել տվյալների բազայի սխեման, փոփոխել առկա աղյուսակները, ավելացնել ինդեքսներ և այլն։

Գործարկեք միգրացիան՝ ստեղծելու տվյալների բազան և միակ users աղյուսակը, որը նկարագրված է նախորդ հրամանով գեներացված միգրացիայի ֆայլում։

mix ecto.create – ստեղծում է տվյալների բազա մեր սերվերի վրա

mix ecto.migrate – կատարում է migrations թղթապանակում գտնվող միգրացիաները

Այժմ կարող եք մուտք գործել ձեր տվյալների բազա և տեսնել ձեզ համար ստեղծված աղյուսակները. users աղյուսակը ներառում է լրացուցիչ դաշտեր, որոնք ստեղծվել են մեր սխեմայի timestamp() կանչով։

Auth կոնտրոլեր

Հաջորդը սահմանեք կոնտրոլեր, որը պատասխանատու է մեր թույլտվության տրամաբանության համար. այն հնարավորություն կտա մուտք գործել հավելված և դուրս գալ դրանից, ինչպես նաև ստանալ տվյալներ մեր երրորդ կողմի OAuth պրովայդերից (տվյալ դեպքում՝ GitHub-ից) OAuth նույնականացման ստանդարտ ընթացքի շրջանակում։

Մինչև հենց կոնտրոլերի կոդը գրելը՝ նախագծին պետք է ավելացնել գրադարան, որը կօգնի OAuth նույնականացմանը։ Այն կոչվում է Ueberauth և առաջարկում է ինտեգրացիաներ պրովայդերների լայն շրջանակի հետ։ Գրադարանի մասին ավելին կարող եք գտնել նախագծի GitHub էջերում այստեղ։

Ավելացրեք երկու կախվածություն mix.exs ֆայլի deps ֆունկցիայում.

{: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 նույնականացման տրամաբանության համար, որն առայժմ մշակում է ընդամենը 2 հարցում.

1 մեկը, որը Ueberauth գրադարանը մշակում է ինքնուրույն՝ մեզ մեր պրովայդերի մոտ ուղարկելու համար
2 մյուսը, որը մշակում է պրովայդերից վերադարձող callback-ները։

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-ից ստացված տվյալների մի մասը և ստեղծենք նոր օգտատեր մեր տվյալների բազայում։

Տվյալների պահպանումը

տվյալների պահպանումը

Մենք կանցնենք վերևի դիագրամում ցուցադրված քայլերով։ Սկզբում դուրս ենք բերում տվյալների բազայում նոր օգտատեր ստեղծելու համար անհրաժեշտ տեղեկությունը։ Դրա համար pattern matching ենք անում մեր callback ֆունկցիայի արգումենտների ցանկի վրա.

def callback(%{assigns: %{ueberauth_auth: auth}} = conn, params) do
  user_data = %{token: auth.credentials.token, email: auth.info.email, provider: "github"}
    ……
end

Երբ տվյալները ձեռքի տակ են, կարող ենք կա՛մ գտնել առկա օգտատիրոջը տրամադրված email-ով, կա՛մ ստեղծել նորը, եթե այդպիսի օգտատեր չկա։ Սա պահանջում է կառուցել սխեմայի changeset և կանչել մի քանի repo մեթոդ։ Գրենք մեթոդ, որը գտնում է առկա օգտատիրոջը կամ ստեղծում է նորը՝ callback-ի հետ եկած պարամետրերի map-ի հիման վրա.

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 հաղորդագրություն։

Դուրս գալու ֆունկցիոնալը

Մուտք գործելը պատմության միայն կեսն է. մուտք գործելուց հետո մեզ անհրաժեշտ է նաև դուրս գալու և սեսիան մաքրելու միջոց։ Դրա համար ավելացնում ենք կոնտրոլերի նոր մեթոդ և համապատասխանեցնում այն մեր ընտրած endpoint-ին 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 պրովայդերի տեսակ։

Վիջեթ

Այժմ մենք ունենք և՛ մուտք, և՛ ելք, և հարմար կլինի դրանք տեղադրել template-ի ընդհանուր մասում, որտեղ կարող ենք ստուգել սեսիայի կարգավիճակը և համապատասխանաբար գործարկել մուտքի/ելքի գործողությունները։

Լռելյայն template-ում մենք ցույց կտանք կա՛մ Log In, կա՛մ Log Out հղումը՝ վերնագրի վերին աջ անկյունում գտնվող մյուս հղումների կողքին։

Թեև մեր սեսիայի օբյեկտը պարունակում է user_id, շատ ավելի հարմար կլինի ունենալ user օբյեկտ, որի հատկությունները կարող ենք կարդալ, օրինակ՝ avatar սահմանելու համար օգտատիրոջ email հասցեի հիման վրա։ Այն ստանալու համար կօգտագործենք Phoenix-ի մի հարմար գործիք, որը կոչվում է plug։ Մենք կգրենք փոքր plug, որը կդառնա հարցումների pipeline-ի մաս. այն ստուգում է՝ արդյոք 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-ը կիրառելու համար պարզապես ավելացրեք այն հարցումների pipeline-ին 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>

Հիանալի է. արդեն պետք է կարողանաք մուտք գործել և դուրս գալ՝ որպես OAuth պրովայդեր օգտագործելով GitHub-ը։ Այս ձեռնարկի վերջին մասում մենք որոշ ռեսուրսներ կպաշտպանենք չարտոնված մուտքից, այլ կերպ ասած՝ կստեղծենք վեբ ռեսուրս, որը տեսանելի կդառնա միայն մուտք գործելուց հետո։

Ռեսուրսների պաշտպանությունը

Եկեք մեր Phoenix հավելվածում գեներացնենք to-do ցանկի ֆունկցիոնալ։ Phoenix-ում դա, բնականաբար, պահանջում է ընդամենը մի քանի հրաման.

mix phx.gen.html Todos Todo todos content:text user_id:references:users
Այնուհետև մի փոքր կճշգրտենք մեր սխեմաները՝ Ecto-ին ասելու համար, որ մեկ օգտատեր կարող է ունենալ շատ to-do տարրեր, և յուրաքանչյուր to-do տարր պատկանում է մեկ կոնկրետ օգտատիրոջ։ Դրա համար սխեմաները ճշգրտեք այսպես.

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-ը՝ todo-ների մշակումը հնարավոր դարձնելու համար.

scope "/", OauthTutorialWeb do
 pipe_through :browser

 get "/", PageController, :index
 resources "/todos", TodoController
end

Ինչպես երևում է վերևում, յուրաքանչյուր մեթոդ, ինչպիսին GET/POST/PUT/DELETE-ն է, առանձին հայտարարելու փոխարեն մենք օգտագործում ենք Phoenix-ի ներկառուցված resources մակրոն, որը մեր փոխարեն գեներացնում է ‘Restful’ երթուղիներ տվյալ ռեսուրսի համար։

Այժմ կարող եք բացել հավելվածը, անցնել /todos և փորձարկել Todo ֆունկցիոնալը։

Ժամանակն է մեր 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-ների ցանկը՝ տվյալների փոփոխումը սահմանափակելով միայն թույլտվություն ունեցող օգտատերերով։

Նոր գեներացված todo_controller.ex-ում plug արեք require_auth-ը հետևյալ կերպ.

plug OauthTutorial.Plugs.RequireAuth when action in [:index, :new, :create, :show, :edit, :update, :delete]

Եթե փորձեք բացել todo-ների էջը առանց մուտք գործելու, պետք է ստանաք չարտոնված մուտքի մասին հաղորդագրություն, ինչպես ցույց է տրված ստորև.

Հարմարության համար մենք todo-ների էջի հղումը կավելացնենք վերնագրի աջ կողմի մյուս հղումների կողքին (լռելյայն Get Started հղման փոխարեն)

<li><%= link "Todos", to: Routes.todo_path(@conn, :index) %></li>

Եզրափակիչ նշումներ

Այս ձեռնարկը բավական երկար ստացվեց, քանի որ ուզում էի մանրամասն անցնել յուրաքանչյուր քայլով, բայց էությամբ OAuth-ի ավելացումը ձեր Phoenix հավելվածին հանգում է մի քանի import-ի, մի քանի լրացուցիչ կոնֆիգուրացիոն փոփոխության և մեկ-երկու սեփական plug-ի, որոնք OAuth-ը ինտեգրում են ձեր հավելվածին։

Հուսով եմ՝ ձեզ դուր եկավ։