# Authentication

> Sign up, SSO login, password rules, email verification, TOTP two-factor authentication with backup codes, project-wide 2FA enforcement, and invite-only mode for self-hosted Alphorn.

Source: https://docs.alphorn.dev/authentication/

Alphorn uses email-based authentication with optional two-factor authentication (2FA) and SSO.

## Sign Up

Create an account at [app.alphorn.dev](https://app.alphorn.dev) with your email address. For self-hosted instances, navigate to your instance URL.

- **Passwords** must have at least 8 characters, must not be your email address, and must not contain the part of your email before the `@` (when that part has 4 or more characters).
- **Email verification** - when the instance can send email, you get a verification link after sign-up and need to confirm your address before signing in. Self-hosted instances without SMTP skip this step.

When you sign up with email and password and no verification is needed, a first [project](/organizations) (e.g. "Jane's Project") is created for you right away. Otherwise (email verification or SSO sign-up) you're asked to create your first project after signing in. If you sign up through a shareable invite link, no project is created - you join the invited project instead.

### Invite-only mode (self-hosted)

Self-hosted instances can turn off public sign-up with `DISABLE_SIGNUP=true`:

- The **first account** on an empty instance can still sign up, so you can create your admin account after installing.
- After that, a new account can only be created for an email address that has a **pending email invitation** to a project. This applies to email/password sign-up and to SSO.
- Everyone else gets "Sign-ups are disabled on this instance. Ask an administrator for an invitation." on the sign-up page, or "Sign-ups are disabled. Ask an administrator for an invitation." when signing up through SSO.
- [Shareable invite links](/organizations#by-shareable-link) only work for people who already have an account.

## Single Sign-On (SSO)

Alphorn supports signing in with GitHub, Google, Microsoft, or any OIDC-compliant identity provider (Keycloak, Okta, Azure AD, etc.). Providers appear on the login page automatically when configured.

- **Hosted** - GitHub, Google, and Microsoft sign-in are available out of the box.
- **Self-hosted** - Set the provider environment variables to enable SSO. See [Self-Hosting → SSO / OAuth](/self-hosting#sso--oauth) for setup instructions.

If you sign in through SSO with the same email address as an existing account, the SSO login is linked to that account when:

- the existing account's email address is **verified**, and
- the provider is GitHub, Google, or Microsoft, or the OIDC provider reports the email as verified (`email_verified`)

Otherwise the sign-in fails with "account not linked". On self-hosted instances without SMTP, email addresses are never verified, so SSO logins can't be linked to existing email/password accounts - use one sign-in method per account there.

## Password Reset

Click **Forgot password?** on the sign-in page to get a reset link by email. This requires email sending, so it is not available on self-hosted instances without SMTP.

## Two-Factor Authentication (2FA)

Secure your account with TOTP-based two-factor authentication.

### Enabling 2FA

1. Go to **Profile → Security**
2. Click **Enable 2FA** and confirm with your current password
3. Scan the QR code with an authenticator app (Google Authenticator, Authy, 1Password, etc.)
4. Enter the 6-digit code to confirm
5. Save your **backup codes** in a secure location

### Backup codes

Each backup code can be used once instead of a 6-digit code - choose the backup code option on the 2FA prompt when signing in. If you've used or lost your codes, generate new ones with **Regenerate backup codes** under **Profile → Security**. Generating new codes invalidates the old ones.

### Project-wide 2FA

Admins and owners can require 2FA for everyone in a project:

1. Enable 2FA on your own account first - otherwise you'd lock yourself out
2. Go to **Settings → Security**
3. Enable **Require 2FA for all members**

Members who don't satisfy the requirement can't access that project until they enable 2FA under **Profile → Security**. Their other projects stay accessible.

Disabling 2FA (**Disable 2FA**, needs your password) is always possible, but you immediately lose access to every project that requires it.

<Callout type="info">
Accounts with a linked SSO login (GitHub, Google, Microsoft, or OIDC) count as having 2FA. Alphorn trusts the identity provider to enforce multi-factor authentication there.
</Callout>

### SSO-only accounts

Accounts that only sign in through SSO have no Alphorn password. **Profile → Security** shows that the account is managed by the identity provider, with no password or 2FA settings - those are handled by your provider.

## Account Settings

Under **Profile** you can:

- Change your name and email address. Changing the email needs your current password and email sending
- Change your password (**Profile → Security**)
- Delete your account (**Profile → Danger zone**). Projects where you are the only member are deleted with it. If one of those projects has an active paid subscription, cancel it first. If you are the only owner of a project that has other members, [transfer ownership](/organizations#transferring-ownership) first