Areca DocsSign-in methods
Turn on email and password, GitHub, Google, Discord or Microsoft Entra ID sign-in, and keep registration invite-only.
Areca signs people in with email and password by default. You can add GitHub, Google, Discord or Microsoft Entra ID (formerly Azure AD) sign-in as well. Every method is switched on or off with environment variables, so you change sign-in by editing the CMS configuration and restarting it.
Registration is always invite-only. Signing in with a provider does not create an account on its own. Someone can only join if they were invited, or if they are the first person to complete first-run setup.
Methods at a glance
| Method | Turned on by | Notes |
|---|---|---|
| Email and password | On by default. AUTH_EMAIL_PASSWORD_ENABLED | Set to false to hide the form and block password sign-in. |
| GitHub | GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET | Both must be set. |
GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET | Both must be set. | |
| Discord | DISCORD_CLIENT_ID and DISCORD_CLIENT_SECRET | Both must be set. |
| Microsoft Entra ID | MICROSOFT_SSO_CLIENT_ID, MICROSOFT_SSO_CLIENT_SECRET and MICROSOFT_SSO_TENANT_ID | Environment only. Requires a tenant ID. |
The variables are described in configuration. A method that is off is removed from the sign-in page and cannot be used, even if someone sends a request for it by hand.
Before you start
Set BETTER_AUTH_URL to the public address people use to open the CMS, including the scheme, for example https://cms.example.com. Every provider callback is built from it. If the callback address does not match the URL in the provider's settings, sign-in fails.
Restart the CMS after you change any of these settings.
Email and password
Email and password is on unless you set AUTH_EMAIL_PASSWORD_ENABLED=false. When it is off, the form is removed from the sign-in page and password sign-in is rejected.
The first-run setup page still asks for a password, even when this setting is off. That lets you create the first admin account before you configure a provider.
Before you turn password sign-in off, confirm that at least one admin can sign in another way.
Social sign-in
GitHub, Google and Discord each need two values: a client ID and a client secret. Areca registers a provider only when both values are set. If you leave them unset or blank, the button does not appear.
To set up a provider:
Register an OAuth application. Create an OAuth app in the provider's developer settings.
Set the callback URL. Use the URL for that provider from the table below, with your own CMS address in place of the host.
Add the credentials. Set the client ID and client secret in the CMS environment, then restart the CMS.
| Provider | Callback URL |
|---|---|
| GitHub | https://cms.example.com/api/auth/callback/github |
https://cms.example.com/api/auth/callback/google | |
| Discord | https://cms.example.com/api/auth/callback/discord |
| Microsoft Entra ID | https://cms.example.com/api/auth/sso/callback/microsoft |
The host must match BETTER_AUTH_URL.
Microsoft Entra ID
Entra ID is configured only through the environment. You cannot add or change an identity provider in the admin interface, because the runtime SSO management endpoints are disabled.
Set these variables:
MICROSOFT_SSO_CLIENT_IDandMICROSOFT_SSO_CLIENT_SECRET, from an app registration in Entra ID.MICROSOFT_SSO_TENANT_ID, the directory (tenant) ID of the Entra ID tenant whose users should sign in. A concrete ID is required. The sharedcommonendpoint is not supported.MICROSOFT_SSO_DOMAIN, an email domain your tenant owns, such asagency.example. Entra ID does not say whether an email is verified, so Areca only trusts Microsoft addresses on this domain. Without it, Microsoft sign-in cannot link to an existing account (the sign-in page shows "Could not sign in" and the URL haserror=account not linked), and invited people cannot accept their invitation with Microsoft. It also routes sign-ins for that domain to Microsoft.
In the app registration, add the callback URL from the table above as a web redirect URI.
Entra ID only sends an email address when the account has a mail attribute. Directory accounts without one cannot sign in.
Areca trusts the email address that Entra ID reports as verified, and links the sign-in to an existing account with the same address.
Invite-only registration
A new account is created only in one of two cases:
- No accounts exist yet, during first-run setup.
- A pending invitation exists for that email address and has not expired.
Anyone else who signs in with a provider or Microsoft is turned away with the message "This account is not allowed to sign in. Ask an admin for an invitation first."
Invitations expire after seven days. To invite someone, see people and invitations. The address on the provider account must match the invited address.
Two-factor codes and provider sign-in
Areca's own two-factor authentication (TOTP) is a challenge after email and password sign-in. Sign-ins through GitHub, Google, Discord or Entra ID do not show that prompt. Areca relies on the identity provider to have done its own multi-factor check.
Agency admins still need two-factor authentication turned on in their Areca account, whichever method they use to sign in. This is controlled by ADMIN_MFA_REQUIRED, which defaults to true. Until an admin has enrolled and verified a local TOTP or backup code in the current session, admin functions are blocked. Sensitive actions also ask for a fresh authenticator code when that local proof is older than 10 minutes.
Read two-factor authentication and step-up for the enrollment steps and the step-up rules.
Keep the secret stable
BETTER_AUTH_SECRET signs every session and protects two-factor enrollment data. Changing it signs everyone out, and it can stop existing authenticator codes from working. Change it only in a planned maintenance window, after you confirm that an admin can sign in and has backup codes.
AI apps and sign-in
An AI app that a user connects to a site, such as ChatGPT, Claude or Cursor, signs the user in on the same sign-in page as the CMS. The user signs in with the methods you have turned on, and two-factor codes are asked for in the same way. After sign-in, the user sees a consent screen before the app is connected. See Connect AI.
AI apps need the public HTTPS address set in BETTER_AUTH_URL and APP_URL. See production.
Related
- Configuration: every sign-in variable and the
BETTER_AUTH_URLsetting. - Two-factor authentication and step-up
- Roles and permissions
- People and invitations
Configuration reference
Every environment variable and Docker Compose setting for the Areca CMS, grouped by purpose, with defaults and whether each one is required.
Storage and email
Configure S3-compatible storage for uploads, serve assets through a CDN, and send email through SMTP, with provider settings and delivery checks.