Authmk
Website: https://authmk.com
Status: 1.2 The public API, plugin API, endpoints and error codes are stable: see the stability guide.
Why
Elixir has good building blocks for authentication: phx.gen.auth, Ueberauth,
Guardian, Assent, and Ash Authentication if you use Ash. What it doesn't have is
a framework where a plugin can add database tables, routes and lifecycle hooks
in one place, the way Better Auth does for TypeScript. Authmk aims to bring that
model to Phoenix and Ecto.
Getting started
-
Add the dependency:
{:authmk, "~> 1.2"} -
Define an auth module:
defmodule MyApp.Auth do use Authmk, otp_app: :my_app, repo: MyApp.Repo, plugins: [Authmk.Plugins.EmailPassword] @impl Authmk def send_reset_password(%{user: user, url: url}, _ctx) do MyApp.Mailer.deliver_reset_link(user.email, url) end end -
Set a secret, configure, start it after your repo, and mount it:
mix authmk.gen.secret # put the output in AUTHMK_SECRET# config/runtime.exs config :my_app, MyApp.Auth, base_url: "https://example.com" # application.ex children = [MyApp.Repo, MyApp.Auth, ...] # router.ex (Phoenix or Plug.Router) forward "/auth", MyApp.Auth -
Generate and run the migration:
mix authmk.gen.migration mix ecto.migrate -
Load the signed-in user in your own pipelines:
plug Authmk.Plug.FetchSession, auth: MyApp.Auth # assigns :current_user, :current_session plug Authmk.Plug.RequireUser, redirect_to: "/sign-in"
In Phoenix, Authmk.Phoenix.Router mounts authmk and LiveView sessions
(authmk_live_session, with Authmk.LiveView's hooks), and
Authmk.Components gives sign-in, sign-up, password reset, two-factor,
passkey and account-settings components that work without JavaScript. See
the Phoenix and LiveView guide; SPAs,
desktop and mobile apps are in this guide, and
moving from phx.gen.auth, Pow or Ash Authentication in the migration
guides.
Clients then call POST /auth/sign-up/email, POST /auth/sign-in/email,
GET /auth/get-session and so on. See Authmk.Endpoints and
Authmk.Plugins.EmailPassword for every endpoint. Working Plug and Phoenix
apps are in examples/.
Social sign-in takes a line per provider, with 44 built in and any other
OpenID Connect or OAuth 2.0 provider through :generic:
config :my_app, MyApp.Auth,
social_providers: [
github: [client_id: "...", client_secret: "..."],
staff: [provider: :keycloak, issuer: "https://sso.example.com/realms/staff", client_id: "...", client_secret: "..."]
]
See the social sign-in guide.
Two-factor authentication (authenticator apps, codes by email or SMS, backup codes, trusted devices) is a plugin, and applies to every sign-in method:
plugins: [
Authmk.Plugins.EmailPassword,
{Authmk.Plugins.TwoFactor, issuer: "My App", send_otp: &MyApp.Auth.send_two_factor_code/2}
]
See Authmk.Plugins.TwoFactor.
More sign-in methods, each a plugin:
| Plugin | What it adds |
|---|---|
Authmk.Plugins.Username |
Sign in with a username and password |
Authmk.Plugins.Anonymous |
Guests who sign up later, keeping their data |
Authmk.Plugins.PhoneNumber |
Codes by SMS; phone number and password |
Authmk.Plugins.MagicLink |
Sign-in links by email |
Authmk.Plugins.EmailOTP |
Codes by email: sign in, verify, reset, change email |
Authmk.Plugins.Passkey |
Passkeys (WebAuthn); needs {:wax_, "~> 0.7"} |
Authmk.Plugins.OneTap |
Google One Tap, popup and redirect modes |
Authmk.Plugins.SIWE |
Sign-In with Ethereum; needs {:ex_secp256k1, "~> 0.8"} and {:ex_keccak, "~> 0.7"} |
Your app as an identity provider: Authmk.Plugins.OAuthProvider makes it an
OAuth 2.1 authorization server and OpenID Connect provider, with PKCE,
consent, refresh-token rotation, resource indicators, DPoP, pushed
authorization requests, private_key_jwt, dynamic client registration and
logout. Authmk.Plug.RequireAccessToken protects your APIs with its tokens.
For business customers, Authmk.Plugins.SSO signs organizations in with
their own OpenID Connect or SAML 2.0 identity providers, with DNS domain
verification and automatic provisioning (SAML is read with OTP's xmerl and
public_key, refusing DTDs, unsigned and replayed assertions), and Authmk.Plugins.SCIM lets their directories
(Okta, Entra ID, Google Workspace) provision and deprovision people and
groups over SCIM 2.0.
Authorization: Authmk.AccessControl defines roles and permissions, checked
without a database call. Authmk.Plugins.Admin manages users (roles, bans,
sessions, impersonation) with them, Authmk.Plugins.Organization adds
organizations with members, invitations, teams and their own roles, and
Authmk.Plugins.APIKey issues hashed API keys with permissions, usage
limits and rate limits, and Authmk.Plugins.ServiceAccount gives programs
their own identities (with roles, expiry and IP allow-lists), seen by your
plugs as current_principal. Authmk.Plugins.Gate answers "may this user
do this on this record?" from app roles, organization roles, team roles and
roles inside teams, with defaults in code that each organization may adjust.
Sessions and security, also plugins:
| Plugin | What it adds |
|---|---|
Authmk.Plugins.Bearer |
Sessions through Authorization: Bearer instead of cookies |
Authmk.Plugins.JWT |
JWTs from sessions, with a JWKS endpoint and key rotation |
Authmk.Plugins.MultiSession |
Several signed-in accounts on one device |
Authmk.Plugins.OneTimeToken |
Hand a signed-in user over to another app or domain |
Authmk.Plugins.DeviceAuthorization |
Sign-in on TVs and CLIs (RFC 8628) |
Authmk.Plugins.Captcha |
Turnstile, reCAPTCHA, hCaptcha or CaptchaFox on chosen endpoints |
Authmk.Plugins.HaveIBeenPwned |
Refuses passwords from known data breaches |
Authmk.Plugins.LastSignInMethod |
Remembers how a user last signed in, for "Last used" hints |
Authmk.Plugins.OAuthProxy |
Social sign-in on previews and localhost through production's callback URL |
Authmk.Plugins.AuditLog |
Who did what to which account, with retention and export |
Authmk.Plugins.Security |
Credential stuffing, sign-up abuse, email checks, impossible travel, geo and bot blocking, proof-of-work |
Authmk.Plugins.OpenAPI |
An OpenAPI 3.1 description of every enabled endpoint, and a reference page |
Payments, also plugins (one payment provider per app):
| Plugin | What it adds |
|---|---|
Authmk.Plugins.Stripe |
Customers, Checkout, the customer portal, subscriptions, trials, organization subscriptions, tax collection |
Authmk.Plugins.Polar |
Checkout, the customer portal, subscriptions, usage events and meters |
Authmk.Plugins.Chargebee |
Customers, hosted pages, subscriptions, trials |
Authmk.Plugins.Creem |
Checkout, the customer portal, subscriptions, access checks |
Authmk.Plugins.DodoPayments |
Checkout, the customer portal, subscriptions |
Authmk.Plugins.Commet |
Subscriptions, the customer portal, feature access, usage, seats |
Authmk.Plugins.Autumn |
Plans, balances and feature access kept by Autumn |
Authmk.Plugins.Dub |
Sign-ups from Dub links as leads, sales, and Dub accounts linked to users |
They share one set of endpoints (/billing/checkout, /billing/portal,
/billing/subscriptions, /billing/cancel, /billing/webhook) and tables.
Webhooks are checked against the provider's signature, and each
subscription is then read again from the provider's API. A user or
organization gets one trial and one subscription at a time. Your code asks
Authmk.Payments.allowed?(MyApp.Auth, user.id, :projects, 3). See the
payments guide.
An admin dashboard (licensed separately: see License below) mounts in any
Plug or Phoenix router with one line,
forward "/admin/auth", Authmk.Dashboard, auth: MyApp.Auth, to run your
app's auth: analytics by date range and organization (active users,
sign-ins and sign-ups by method, failed sign-ins, verification and
two-factor adoption) with CSV exports; managing users (create, edit with
your own fields, verify, set passwords and roles, ban, revoke sessions,
unlink accounts, impersonate) and organizations (members, roles, teams,
invitations); what each user can see and do, and why; earnings and
subscriptions with a payment plugin; health checks of your senders,
providers, certificates, storage and jobs; and your branding. Every change
made there goes to the audit log. In Mudrock's light and dark themes.
With Authmk.Dashboard.Branding, the app's name, logo and colour are
edited in the dashboard and used by authmk's pages and emails.
When a social, SSO or One Tap sign-in, or an OAuth authorization, fails
with nowhere to send the user, authmk shows its own error page at
/auth/error (themed, light and dark, with the error code and a way back,
and your branding). Render your own template there with
errors: [page: {MyAppWeb.AuthErrorHTML, :page}], or pass
error_callback_url (or set errors: [error_url: ...]) to send users to
your own page instead.
Authmk.Emails has ready-made Swoosh emails for every callback, and
Authmk.SMS is the behaviour for sending phone codes.
In your app's tests, Authmk.Testing creates users and sessions and signs
test conns in, and Authmk.Testing.Inbox catches the codes and links authmk
sends. To test passkey and wallet sign-in in your own app, Authmk.Testing.FakeAuthenticator
and Authmk.Testing.FakeWallet play the authenticator and the wallet.
Design
Plugins
A plugin is a module that implements the Authmk.Plugin behaviour. It can contribute:
- Schema: new tables, or extra fields on core tables such as
user - Endpoints: served under the auth router
- Hooks:
before_endpoint/2, which can stop a request,after_endpoint/3, which can change the result, anddatabase_hook/4around every write - Options: validated in
init/1
defmodule MyApp.Auth do
use Authmk,
otp_app: :my_app,
repo: MyApp.Repo,
plugins: [
{Authmk.Plugins.EmailPassword, require_email_verification: true},
MyApp.Auth.AuditPlugin
]
# Your auth module gets the same hooks as plugins.
@impl Authmk
def before_endpoint(:sign_up_email, ctx) do
if String.ends_with?(ctx.raw_params["email"], "@example.com"),
do: {:cont, ctx},
else: {:halt, Authmk.Error.new(:forbidden)}
end
def before_endpoint(_endpoint, ctx), do: {:cont, ctx}
end
Schema declared in config
As in Better Auth, the schema is declared in config. Core models, plugin models and your own settings are merged at compile time into one resolved schema. That schema drives the Ecto schemas, input validation and migrations.
use Authmk,
repo: MyApp.Repo,
table_naming: :plural, # :plural (default) | :singular
table_prefix: "auth_", # optional
schema: [
user: [
module: MyApp.Accounts.User,
table: "users", # an explicit table name always wins
fields: [name: [source: :full_name]],
additional_fields: [
role: [type: :string, default: "user", input: false]
]
]
]
- Table names: an explicit
table:wins; otherwisetable_prefixplus the singular or plural model name. - References: these point at models, not tables, so renaming a table updates every foreign key.
- Existing databases: you can map authmk onto tables you already have, such
as
usersfromphx.gen.auth, including renamed columns.
Models the library owns (sessions, accounts, verifications and so on) are generated for you. Models you own, like the user, keep your own module and pull in authmk's fields with a macro:
defmodule MyApp.Accounts.User do
use Ecto.Schema
use Authmk.Schema, auth: MyApp.Auth, model: :user
schema "users" do
authmk_fields()
has_many :posts, MyApp.Blog.Post
timestamps()
end
end
Migrations
Migrations are generated from the resolved schema. Authmk compares it with a snapshot committed to your repo, similar to drizzle-kit, and writes normal Ecto migrations:
mix authmk.gen.migration # write a migration for schema changes
mix authmk.gen.migration --baseline # record existing tables, write nothing
mix authmk.gen.migration --check # fail in CI if a migration is missing
mix authmk.gen.migration --existing users # adopt your own users table
mix ecto.migrate
Destructive changes such as drops need --allow-destructive. Likely
renames are asked about, so data is kept. On SQLite, a changed column
rebuilds its table, keeping rows, indexes and the foreign keys pointing at
it.
mix authmk.create_admin ada@example.com # password from AUTHMK_ADMIN_PASSWORD
mix igniter.upgrade authmk # runs mix authmk.upgrade between versions
Databases
SQLite, PostgreSQL, MySQL and MariaDB are all supported through Ecto. Authmk follows whichever adapter your repo uses, and there is no default.
To stay compatible with all of them, the schema only uses features they all
share. That means no array columns, no citext, no partial indexes, no
defaults computed by the database, and no defaults on :text or :map fields
(MySQL rejects them). IDs are generated by the app, emails are
normalized in code, and any field a plugin adds to an existing table must be
nullable or have a default, because SQLite can't change an existing column.
Validation
Input is validated with Ecto changesets built from the field specs. That
means validation errors work with Phoenix forms (to_form/1) without any
adapter code.
Language
Authmk is English only. Errors carry a stable code, such as
:invalid_credentials, so apps can show their own text if they want.
Changelog
See CHANGELOG.md for what changed in each release.
Installation
def deps do
[
{:authmk, "~> 1.0"}
]
end
Documentation: https://hexdocs.pm/authmk
Acknowledgements
Authmk's design borrows heavily from Better Auth: its plugin model, schema-in-config approach and CLI-driven schema generation. Authmk is an independent project and is not affiliated with Better Auth.
License
MIT © Mudrock Software LTD. See LICENSE.
The admin dashboard, its analytics and branding, in licensed/, aren't MIT licensed:
they're source available, under licensed/LICENSE.md.
You may read and change them, and use them free in development and tests;
changes you send back to Mudrock become Mudrock's. They ship in the Hex
package and in every build of authmk; that needs no key as long as you
don't mount Authmk.Dashboard. Running the dashboard in production needs a licence key
(https://license.mudrock.dev). Without a valid key in AUTHMK_LICENCE_KEY,
the dashboard refuses every request outside development and tests, and
Authmk.Dashboard.Branding leaves pages and emails with authmk's look.