Viewing latest docs.
Switch version: v3

Users & Authentication

Users

The user.ex schema looks like this:

user.ex
defmodulePetalPro.Accounts.Userdo
...
schema "users"do
field :name,:string
field :email,:string
field :password,:string,virtual:true,redact:true
field :hashed_password,:string,redact:true
field :confirmed_at,:naive_datetime
field :role, Ecto.Enum, values: [:admin, :user], default: :user
field :avatar,:string
field :last_signed_in_ip,:string
field :last_signed_in_datetime,:utc_datetime
field :is_suspended,:boolean,default:false
field :deleted_at,:utc_datetime
field :is_onboarded,:boolean,default:false
field :current_org,:map,virtual:true
many_to_many :orgs,Org,join_through:"orgs_memberships",unique:true
timestamps()
end
...
end

Users have some extra fields not included by phx.gen.auth:

Field Type Description
name :string A users full name
avatar :string A URL to the users avatar image
last_signed_in_ip :string The IP address of the last sign-in, from PetalProWeb.UserAuth.get_ip/1. Behind a proxy, set CLIENT_IP_HEADER (fly-client-ip on Fly) or TRUSTED_PROXY_HOPS, or this records your proxy’s address. See PetalProWeb.ClientIp.
role Ecto.Enum :admin or :user. Admins get access to a special dashboard where they can modify users, see logs, etc.
is_suspended :boolean An admin can suspend a user, preventing them from logging in.
deleted_at :utc_datetime Set when the account is deleted (soft delete). User.active/1 scopes a query to users where it’s nil.
is_onboarded :boolean Track whether or not a user has seen an onboarding screen after registering.

Marketing email opt-in isn’t a field on the user. It’s a marketing_notifications row in the user_notification_preferences table.

Authentication

We used phx.gen.auth (email/password) and modified the templates to use Tailwind and Petal Components.

Sign-in limits

Since 4.5.2 the password sign-in form allows ten tries per ten minutes per account. Every try is counted before the password is checked, and a correct password counted on the account starts the count again. Past the limit, even the right password goes back to the sign-in page with “Too many attempts. Please try again later.” An email with no account gets the same answer, so a refusal doesn’t show which emails have accounts. A malformed post is answered “Invalid email or password” and isn’t counted.

So that a stranger can’t lock someone out by using up their count, a browser that has signed in with the password gets a cookie, _petal_pro_web_sign_in_device, and is counted on its own first. It grants no access and stops counting once the password changes. A sign-in from that browser leaves the account’s count as it is, so other browsers stay refused until the window ends. List it in your cookie policy. A password reset starts the account’s sign-in counts again, so it’s the way back in for a locked-out user.

Asking for a password reset and resending the confirmation email are each limited to three per ten minutes per account. The resend count is shared with POST /api/send-instructions.

All of these are counted on the account, found through the database, not on the email as typed. See Rate Limiting for every limit, the cookie and how to clear a count by hand.

Setting and accessing the current user

Controller actions

For controller actions we use the plug provided by mix phx.gen.auth to set conn.assigns.current_user .

user_auth.ex
defmodule PetalProWeb.UserAuth do
...
def fetch_current_user(conn, _opts) do
{user_token, conn} = ensure_user_token(conn)
user = user_token && Accounts.get_user_by_session_token(user_token)
assign(conn, :current_user, user)
end
...
end

You can see the :fetch_current_user plug used in the :browser pipeline in the router.

router.ex
defmodule PetalProWeb.Router do
...
pipeline :browser do
plug :accepts, ["html"]
plug :fetch_session
plug :fetch_live_flash
plug :put_root_layout, {PetalProWeb.Layouts, :root}
plug :protect_from_forgery
plug :put_secure_browser_headers
plug :fetch_current_user
plug PetalProWeb.SetLocalePlug, gettext: PetalProWeb.Gettext
end
...
end

If you want to enforce the user then you can use the :require_authenticated_user plug.

router.ex
scope "/", PetalProWeb do
pipe_through [:browser, :require_authenticated_user]
# Routes that require a logged in user go here
end

Live views

We can’t rely on our plugs in live views, since live views connect over web sockets and avoid the traditional request/response lifecycle. However, a live view will have access to the session, which contains the user token set upon login. Hence, in the live view mount we can use the token to find the user_token set in our database for that users session, and from there obtain the logged in user.

Instead of doing this on every live view mount function, we can extract this out into an on_mount function and then apply it in the router, like a mini pipeline.

user_on_mount_hooks.ex
defmodule PetalProWeb.UserOnMountHooks do
...
def on_mount(:require_authenticated_user, _params, session, socket) do
socket = maybe_assign_user(socket, session)
if socket.assigns.current_user do
{:cont, socket}
else
{:halt, redirect(socket, to: ~p"/auth/sign-in")}
end
end
defp maybe_assign_user(socket, session) do
assign_new(socket, :current_user, fn ->
get_user(session["user_token"])
end)
end
...
end
router.ex
defmodule PetalProWeb.Router do
...
scope "/", PetalProWeb do
pipe_through [:browser, :require_authenticated_user]
live_session :protected, on_mount: {PetalProWeb.UserOnMountHooks, :require_authenticated_user} do
# Live routes that require a logged in user go here
end
end
...
end

Social login providers

Petal Pro uses Ueberauth to handle social providers. Ueberauth simplifies the oauth process and have a large number of providers supported. We have set up a couple of providers to get you started:

  • Google
  • Github

How does it work?

A user is redirected to a provider. The URL for this redirect is generated by the Ueberauth library:

~p"/auth/google"
~p"/auth/github"

When you setup either “Google” or “Github”, buttons will appear in the sign in and register pages that go to those URL’s above.

Once a user has successfully signed in to the provider, they are redirected back to your web application. You can see where they end up in routes/auth_routes.ex, which the router pulls in with use PetalProWeb.AuthRoutes:

auth_routes.ex
scope "/auth", PetalProWeb do
pipe_through [:browser, :redirect_if_user_is_authenticated]
...
get "/:provider", UserUeberauthController, :request
get "/:provider/callback", UserUeberauthController, :callback
end

In the file user_ueberauth_controller.ex there are callback functions - one for each provider. In these callback functions we take the user info provided by the provider and use that to sign in a user (registering them if they aren’t already):

user_ueberauth_controller.ex
def callback(%{assigns: %{ueberauth_auth: %{info: user_info}}} = conn, %{"provider" => "google"}) do
user_params = %{
email: user_info.email,
name: combine_first_and_last_name(user_info),
avatar: user_info.image
}
case Accounts.get_or_create_user(user_params, "external_provider") do
{:ok, user} ->
user = Accounts.confirm_user!(user)
UserAuth.log_in_user(conn, user)
{:error, _} ->
conn
|> put_flash(:error, "Authentication failed")
|> redirect(to: "/")
end
end

How does this fit in with the existing user schema?

The user table doesn’t change. Everything revolves around a user’s email address. A user might register with a password and some time later login via Google. As long as the email used for Google sign in is the same as the registered email, then the login will work. The same goes for Github and Twitter.

If a user doesn’t exist and they login via a provider, then they will be registered under the email address given by the provider. Since the user table has a not-null constraint on the hashed_password column, a password will be randomly generated. This way we don’t modify the original table structure of the mix phx.gen.auth generator.

If a user logs in with a provider and then wants to change their (randomly generated) password they will have to click “Forgot my password”.

What if the user forgets what social login they used?

Under this implementation there is nothing you can do apart from tell the user to try each provider and see which works. You could add a new field to the user schema (user.provider) if you like.

Setup Google sign in

  1. Create a Google Project
  2. Create Oauth 2.0 Client ID (you’ll likely have to create an OAuth consent screen before you can create the OAuth Client ID)
  • The user type you’ll require will be External

  • Go to “Create credentials” -> “OAuth client ID” and fill in the details - make sure of the following:

  • Authorized JavaScript origins - http://localhost:4000

  • Authorized redirect URIs - http://localhost:4000/auth/google/callback

  1. Add your client ID + client secret to your .envrc file:

  2. export GOOGLE_OAUTH_CLIENT_ID=””

  3. export GOOGLE_OAUTH_SECRET=””

  4. Stop your server and make sure you enter direnv allow

Setup Github sign in

  1. Create an OAuth App - it can be either under your personal account or an organization:

  2. Personal account:

  3. Click your avatar -> Settings

  4. Developer settings (down the bottom)

  5. Organization account:

  6. Go to your organization’s profile

  7. Developer settings (down the bottom)

  8. Fill in the details - the only thing that matters is “Authorization callback URL”, which should be http://localhost:4000/auth/github

  9. Paste client ID and secret into your .envrc file:

  10. export GITHUB_OAUTH_CLIENT_ID=""

  11. export GITHUB_OAUTH_SECRET=""

Adding more providers

See a list of Ueberauth strategies here. You can copy how we’ve done it for the previous 3 providers. Check out the file user_ueberauth_controller.ex for how to deal with the callbacks. Your main job is taking the data given by the provider and using it to register a user.

Passwordless

If enabled, users can both register and login without a password (it’s enabled by default).

Passwordless sign in was added in v1.2.0. You can toggle it on and off in config.exs. When it’s enabled, a “Continue with passwordless” button will show up on the sign-in and register pages.

How passwordless works

Enabling passwordless adds a new option on the sign-in and register screens. Passwordless allows users to either register or log in with their email address. They get sent a code and use the code as a temporary password. The code expires after 10 minutes, and after three wrong guesses it stops working and the user has to ask for a new one.

Each pin allows three guesses and lasts 10 minutes. Asking for a pin is limited to three per ten minutes per account, and since 4.5.1 any capitals count as the same email and “Resend” goes through that same limit, so an account gets nine guesses per ten-minute window. 4.5.2 closes a way round this: on some databases the same account could be reached under another spelling of its email, each with a count of its own. On 4.5.2 the count is kept on the account. Guesses are counted by UserPin.check_pin/3 in one database statement before the pin is compared. See Rate Limiting.

You can think of passwordless as another social login. However, instead of a company like Github verifying the user’s credentials, the user’s email service verifies them instead. The main difference is that you don’t get other information like a user’s name and avatar with passwordless - only the email address.

This means users can register and access your web app with only an email. For Petal Pro this is okay, as during onboarding we ask the user to add their name. We also generate a random password for them (every user requires a password as a database rule set by phx.gen.auth). A user therefore can click “Reset password” if they like and choose to use password-based login in the future.

The passwordless flow is handled in PetalProWeb.PasswordlessAuthLive.

Passwordless process:

  1. Find or create a user using the email (new users are given a random password, which they can reset at any time), and set the user to assigns.auth_user
  2. A user_token is generated with the encrypted pin code in it
  3. Push patch to /auth/sign-in/passwordless/enter-pin/:hashed_user_id (user id is obfuscated in a hashed format using the HashId lib)
  4. The user enters the code sent to their email (gets a limited number of attempts before the user_token is deleted
  5. If correct - generates a sign-in token for the user - however live views can’t insert cookies, so we need to make a trip to the server
  6. Place the sign-in token in a hidden field in a form (encoded it as base64)
  7. Submit the form using phx-trigger-action
  8. This POSTs it to PetalProWeb.UserSessionController.create_from_token/2
  9. create_from_token/2 will use the token to log the user in (set the appropriate cookie)

Two-factor authentication (2FA) with TOTP

2FA boosts the security of your web application by allowing users to opt into a two-factored sign-in procedure (their ordinary sign-in plus entering a one-time password).

Users can go to Settings > 2FA (/app/users/two-factor-authentication) and enable 2FA by syncing their account to a tool that implements the Time-based One-time Password (TOTP) algorithm (the main one being Google Authenticator). Setup is two numbered steps: scan the QR code (or switch to entering the secret by hand if you can’t scan it), then enter the 6-digit code. The code field is petal_components’ input_otp, which sets autocomplete="one-time-code" so password managers can fill it, and it still posts user_totp[code]. Disabling 2FA and regenerating backup codes both ask for confirmation in a dialog.

Once set up the user will also be provided with some backup codes (in case they lose their phone). Each backup code can be used once as a fallback if the authenticator app is unavailable.

Now, when signing in a user will be forced to enter a TOTP from their authenticator app. The sign-in flow presents a code entry screen after the initial password step.

Since 4.5.1 that screen allows five codes (TOTP or backup) per five minutes per user. Every submit counts, and a correct code starts the count again. Past the limit the form comes back with a 429 and “Too many attempts. Please try again later.” It’s keyed on the user, so it needs no proxy setting.

Until the code is entered the user isn’t fully signed in. Since 4.5.2 an admin in that state can’t impersonate anyone: POST /auth/impersonate sends them to the code step first. The same goes for an admin whose second factor is a passkey.

How is TOTP implemented?

The schema looks like this:

user_totp.ex
typed_schema "users_totps" do
field :secret, :binary
field :code, :string, virtual: true
belongs_to :user, PetalPro.Accounts.User
embeds_many :backup_codes, BackupCode, on_replace: :delete do
field :code, :string
field :used_at, :utc_datetime
end
timestamps(type: :utc_datetime)
end

The key field is the secret. This is what is passed to the authenticator app and allows the web application to work out which codes are correct.

How to turn off 2FA

The simplest way is to remove access to the 2FA settings. This will prevent users from setting it up. In future it will also be easy enough to turn it back on if you want.

  1. Remove the settings route from router.ex: live "/users/two-factor-authentication", EditTotpLive. Leave get "/users/totp" and post "/users/totp" (the sign-in code check, UserTOTPController) in place if any existing users already have 2FA on.

  2. Remove :edit_totp from the menu_items/1 list in user_settings_layout_component.ex. That’s the “2FA” item in the settings nav, defined in PetalProWeb.Menus.get_link(:edit_totp, _).