Skip to content

Instantly share code, notes, and snippets.

@marteinn

marteinn/Guardian JWT.md

Forked from nikneroz/Guardian JWT.md
Last active December 9, 2019 18:46
Show Gist options
  • Save marteinn/cf6fb0830d5641262c0ef38a4bec710f to your computer and use it in GitHub Desktop.
Save marteinn/cf6fb0830d5641262c0ef38a4bec710f to your computer and use it in GitHub Desktop.
Download ZIP
Elixir + Phoenix Framework + Guardian + JWT. This is tutorial and step by step installation guide.
Raw
Guardian JWT.md

Elixir + Phoenix Framework + Guardian + JWT + Comeonin

This is a updated guide aimed to support Phoenix 1.3 and Guardian 1.0

Preparing environment

We need to generate secret key for development environment.

mix phx.gen.secret
# ednkXywWll1d2svDEpbA39R5kfkc9l96j0+u7A8MgKM+pbwbeDsuYB8MP2WUW1hf

Let's generate User model and controller.

mix ecto.create
mix phoenix.gen.json Accounts User users email:string name:string phone:string password_hash:string is_admin:boolean
mix ecto.migrate

First create a guardian module in lib/my_app_name/guardian.ex. You need to restart your server, after adding files to lib folder.

defmodule MyAppName.Guardian do
  use Guardian, otp_app: :my_app_name

  alias MyAppName.Repo
  alias MyAppName.User

  def subject_for_token(user = %User{}, _claims), do: {:ok, "User:#{user.id}"}
  def subject_for_token(_, _), do: {:error, "Unknown resource type"}

  def resource_from_claims(%{"sub" => "User:" <> uid_str}), do: {:ok, Repo.get(User, uid_str)}
  def resource_from_claims(_), do: {:error, "Unknown resource type"}
end

After that we need to add Guardian configuration. Add guardian base configuration to your config/config.exs

config :guardian, MyAppName.Guardian,
  allowed_algos: ["HS512"], # optional
  verify_module: Guardian.JWT,  # optional
  issuer: "MyAppName",
  ttl: { 30, :days },
  allowed_drift: 2000,
  verify_issuer: true, # optional
  secret_key: "ednkXywWll1d2svDEpbA39R5kfkc9l96j0+u7A8MgKM+pbwbeDsuYB8MP2WUW1hf" # Insert previously generated secret key!

Add guardian dependency to your mix.exs

defp deps do
  [
    # ...
    {:guardian, "~> 1.0"},
    # ...
  ]
end

Fetch and compile dependencies

mix do deps.get, compile

Guardian is ready!

Model authentication part

User tweaks

Now we need to add users path to our API routes.

defmodule MyAppName.Router do
  # ...
  scope "/api/v1", MyAppName do
    pipe_through :api

    resources "/users", UserController, except: [:new, :edit]
  end
  # ...
end

Next step is to add validations to web/models/user.ex. Virtual :password field will exist in Ecto structure, but not in the database, so we are able to provide password to the model’s changesets and, therefore, validate that field.

defmodule MyAppName.User do
  # ...
  schema "users" do
    field :email, :string
    field :name, :string
    field :phone, :string
    field :password, :string, virtual: true # We need to add this row
    field :password_hash, :string
    field :is_admin, :boolean, default: false

    timestamps()
  end
  # ...
end

Validations and password hashing

Add comeonin dependency to your mix.exs

#...
def application do
  [applications: [:comeonin]] # Add comeonin to OTP application
end
# ...
defp deps do
  [
    # ...
    {:comeonin, "~> 4.1"}, # Add comeonin to dependencies
    {:bcrypt_elixir, "~> 1.0.6"} # Make sure to include bcrypt as well
    # ...
  ]
end

Now we need to edit web/models/user.ex, add validations for [:email, password] and integrate password hash generation. Also we need separate changeset functions for internal usage and API registration.

defmodule MyAppName.User do
  #...
  def changeset(struct, params \\ %{}) do
    struct
    |> cast(params, [:email, :name, :phone, :password, :is_admin])
    |> validate_required([:email, :name, :password])
    |> validate_changeset
  end

  def registration_changeset(struct, params \\ %{}) do
    struct
    |> cast(params, [:email, :name, :phone, :password])
    |> validate_required([:email, :name, :phone, :password])
    |> validate_changeset
  end

  defp validate_changeset(struct) do
    struct
    |> validate_length(:email, min: 5, max: 255)
    |> validate_format(:email, ~r/@/)
    |> unique_constraint(:email)
    |> validate_length(:password, min: 8)
    |> validate_format(:password, ~r/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).*/, [message: "Must include at least one lowercase letter, one uppercase letter, and one digit"])
    |> generate_password_hash
  end

  defp generate_password_hash(changeset) do
    case changeset do
      %Ecto.Changeset{valid?: true, changes: %{password: password}} ->
        put_change(changeset, :password_hash, Bcrypt.hash_pwd_salt(password))
      _ ->
        changeset
    end
  end
  #...
end

API authentication with Guardian

First create a auth pipeline (this is a new feature in guardian 1.0)

defmodule MyAppName.AuthPipeline do
  @claims %{typ: "access"}

  use Guardian.Plug.Pipeline,
    otp_app: :my_app,
    module: MyAppName.Guardian,
    error_handler: MyAppName.AuthErrorHandler

  plug(Guardian.Plug.VerifySession, claims: @claims)
  plug(Guardian.Plug.VerifyHeader, claims: @claims, realm: "Bearer")
  plug(Guardian.Plug.EnsureAuthenticated)
  plug(Guardian.Plug.LoadResource, ensure: true)
end

Then let's add headers check in our web/router.ex for further authentication flow.

defmodule MyAppName.Router do
  # ...
  pipeline :api do
    plug :accepts, ["json"]
  end

  pipeline :authenticated do
    plug MyAppName.AuthPipeline
  end
  # ...
  scope "/api/v1", MyAppName do
    pipe_through :api

    pipe_through :authenticated # restrict unauthenticated access for routes below
    resources "/users", UserController, except: [:new, :edit]
  end
  # ...
end

Registration

Now we can't get access to /users route without Bearer JWT Token in header. That's why we need to add RegistrationController and SessionController. It's a good time to make commit before further changes.

Let's create RegistrationController. We need to create new file web/controllers/registration_controller.ex. Also we need specific registration_changeset that we declared before inside of web/models/user.ex

defmodule MyAppName.RegistrationController do
  use MyAppName.Web, :controller

  alias MyAppName.User

  def sign_up(conn, %{"user" => user_params}) do
    changeset = User.registration_changeset(%User{}, user_params)

    case Repo.insert(changeset) do
      {:ok, user} ->
        conn
        |> put_status(:created)
        |> put_resp_header("location", user_path(conn, :show, user))
        |> render("success.json", user: user)
      {:error, changeset} ->
        conn
        |> put_status(:unprocessable_entity)
        |> render(MyAppName.ChangesetView, "error.json", changeset: changeset)
    end
  end
end

Also we need RegistrationView. So, we need to create one more file named web/views/registration_view.ex.

defmodule MyAppName.RegistrationView do
  use MyAppName.Web, :view

  def render("success.json", %{user: user}) do
    %{
      status: :ok,
      message: """
        Now you can sign in using your email and password at /api/sign_in. You will receive JWT token.
        Please put this token into Authorization header for all authorized requests.
      """
    }
  end
end

After that we need to add /api/sign_up route. Just add it inside of API scope.

defmodule MyAppName.Router do
  # ...
  scope "/api", MyAppName do
    pipe_through :api

    post "/sign_up", RegistrationController, :sign_up
    # ...
  end
  # ...
end

It's time to check our registration controller. If you don't know how to write request tests. You can use Postman app. Let's POST /api/sign_up with this JSON body.

{
	"user": {}
}

We should receive this response

{
  "errors": {
    "phone": [
      "can't be blank"
    ],
    "password": [
      "can't be blank"
    ],
    "name": [
      "can't be blank"
    ],
    "email": [
      "can't be blank"
    ]
  }
}

It's good point, but we need to create new user. That's why we need to POST correct payload.

{
	"user": {
		"email": "[email protected]",
		"name": "John Doe",
		"phone": "033-64-22",
		"password": "MySuperPa55"
	}
}

We must get this response.

{
  "status": "ok",
  "message": "  Now you can sign in using your email and password at /api/v1/sign_in. You will receive JWT token.\n  Please put this token into Authorization header for all authorized requests.\n"
}

Session management

Wow! We've created new user! Now we have user with password hash in our DB. We need to add password checker function in web/models/user.ex.

defmodule MyAppName.User do
  # ...
  def find_and_confirm_password(email, password) do
    case Repo.get_by(User, email: email) do
      nil ->
        {:error, :not_found}
      user ->
        if Bcrypt.verify_pass(password, user.password_hash) do
          {:ok, user}
        else
          {:error, :unauthorized}
        end
    end
  end
  # ...
end

It's time to use our credentials for sign in action. We need to add SessionController with sign_in and sign_out actions, so create web/controllers/session_controller.ex.

defmodule MyAppName.SessionController do
  use MyAppName.Web, :controller

  alias MyAppName.User

  def sign_in(conn, %{"session" => %{"email" => email, "password" => password}}) do  
    case User.find_and_confirm_password(email, password) do
      {:ok, user} ->
         {:ok, jwt, _full_claims} = MyAppName.Guardian.encode_and_sign(user, %{}, permissions: %{user: []})

         conn
         |> render "sign_in.json", user: user, jwt: jwt
      {:error, _reason} ->
        conn
        |> put_status(401)
        |> render "error.json", message: "Could not login"
    end
  end  
end

Good! Next step is to add SessionView in web/views/session_view.ex.

defmodule MyAppName.SessionView do
  use MyAppName.Web, :view

  def render("sign_in.json", %{user: user, jwt: jwt}) do
    %{
      status: :ok,
      data: %{
        token: jwt,
        email: user.email
      },
      message: "You are successfully logged in! Add this token to authorization header to make authorized requests."
    }
  end
end

Add some routes to handle sign_in action in web/router.ex.

defmodule MyAppName.Router do
  use MyAppName.Web, :router
  #...
  scope "/api/v1", CianExporter.API.V1 do
    pipe_through :api

    post "/sign_up", RegistrationController, :sign_up
    post "/sign_in", SessionController, :sign_in # Add this line

    pipe_through :authenticated
    resources "/users", UserController, except: [:new, :edit]
  end
  # ...
end

Ok. Let's check this stuff. POST /api/sign_in with this params.

{
	"session": {
		"email": "[email protected]",
		"password": "MySuperPa55"
	}
}

We should receive this response

{
  "status": "ok",
  "message": "You are successfully logged in! Add this token to authorization header to make authorized requests.",
  "data": {
    "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJVc2VyOjEiLCJleHAiOjE0OTgwMzc0OTEsImlhdCI6MTQ5NTQ0NTQ5MSwiaXNzIjoiQ2lhbkV4cG9ydGVyIiwianRpIjoiZDNiOGYyYzEtZDU3ZS00NTBlLTg4NzctYmY2MjBiNWIxMmI1IiwicGVtIjp7fSwic3ViIjoiVXNlcjoxIiwidHlwIjoiYXBpIn0.HcJ99Tl_K1UBsiVptPa5YX65jK5qF_L-4rB8HtxisJ2ODVrFbt_TH16kJOWRvJyJIoG2EtQz4dXj7tZgAzJeJw",
    "email": "[email protected]"
  }
}

Now. You can take this token and add it to Authorization: Bearer #{token} header.

  • Credits to this guide for explaning the difference in clear example between Guardian 0.X and 1.0
@rodrigolck
Copy link

rodrigolck commented Jul 9, 2019 •
edited
Loading

Awesome Tutorial! I would only say to change Comeonin.Bcrypt.hashpwsalt to Bcrypt.hash_pwd_salt and Comeonin.Bcrypt.checkpw to Bcrypt.verify_pass since it was removed in newer versions of Comeonin

@marteinn
Copy link
Author

@rodrigolck Done, thank you so much for the feedback!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment