GitHub OAuth նույնականացման ավելացումը Phoenix հավելվածին
Phoenix-ը զարգանում է արագ տեմպերով։ Phoenix հավելվածում OAuth ինտեգրելու այս ձեռնարկը կօգնի ձեզ համընթաց քայլել դրա հետ։
Նոր տարին եկել է, դրա համար արված որոշումներն արդեն հեռու հիշողություն են, և վերջապես ժամանակ է գտնվել ներդրում անելու մեր աճի մեջ որպես ծրագրավորողներ :) ։ Իմ համեստ կարծիքով՝ ոչինչ այնպես չի լայնացնում մտահորիզոնը, հատկապես ֆունկցիոնալ ծրագրավորման աշխարհում, ինչպես այլ լեզուների և նոր ֆրեյմվորքների ուսումնասիրությունը, տեսնելը, թե ինչպես են դրանք լուծում խնդիրները, և հնարավոր է՝ ոգեշնչում ստանալը կամ գործիքակազմը նոր գործիքներով համալրելը։
Քանի որ 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-ը ինտեգրում են ձեր հավելվածին։
Հուսով եմ՝ ձեզ դուր եկավ։