Auth Control

System → Auth Control focuses on how users log in and verify their identity. Configure email, SMS, social sign-in, and device authentication in one place, with built-in testing tools so every change can be validated instantly.

Module Overview

• Communication methods: Email + SMS login, complete with verification flows, whitelists, and message templates.
• Social accounts: Apple, Google, Facebook, GitHub, and Telegram can be toggled independently.
• Device authentication: Hardens device-based login with VM detection and communication keys.

The following sections mirror the cards you see in the admin panel—work through them in order, test, then save.

Communication Methods

Email authentication

1. Basic switches

   • Enable email sign-in: Controls whether the login form shows the email path.
   • Email verification: Forces new users or sensitive actions to complete email OTP first.
   • Domain whitelist: Only allow addresses from specific domains (one suffix per line, e.g. gmail.com).

2. SMTP platform

   • Server & Port: SMTP host/port (most providers use 25/465/587).
   • SSL/TLS: Match the encryption required by your provider.
   • Account / Password: SMTP credentials (app passwords recommended).
   • From address: What recipients see in their inbox; must match an allowed sender.
   • Send test email: Enter any inbox and send immediately to confirm deliverability.

3. Template tabs (Verify / Expiration / Maintenance / Traffic)

   • Templates are HTML-capable and support variables:
     • {{.Type}}: Email type (1 register, 2 reset password); combine with {{if eq .Type 1}} for conditions.
     • {{.SiteLogo}} / {{.SiteName}}: Branding assets.
     • {{.Expire}}: OTP expiration; {{.ExpireDate}}: Subscription expiration.
     • {{.Code}}: Verification code.
     • {{.MaintenanceDate}}, {{.MaintenanceTime}}: Maintenance notice specifics.
   • The embedded editor is WYSIWYG—save to apply instantly to new outbound mail.

SMS authentication

1. Login policy

   • Enable SMS sign-in: Turns the phone-number OTP entry on/off.
   • Whitelist area codes: When enabled, only listed codes (e.g. 1, 852, 886) are accepted.

2. Platform & dynamic fields

   • Select an SMS provider; the form reveals the exact fields that provider requires and offers a shortcut link to apply for service.
   • Common fields include Access Key, Secret Key, Endpoint, Template Code, Sign Name, and dedicated sender numbers.
   • If the provider expects custom templates, paste the body that contains {{code}} (or its vendor-specific variable).

3. Test SMS

   • Choose an area code, enter a number, and click “Test SMS” to call the gateway immediately.
   • Most failures trace back to invalid credentials, pending template review, or a mismatched signature—verify inside the vendor console.

Social Authentication

All social options share the same drawer layout: toggle the method, fill in the credentials, then save to expose the login button to end users.

Apple Sign-In

• Team ID / Key ID: From Apple Developer.
• Service ID (Client ID): Created under Apple Developer → Identifiers.
• Private Key: Contents of the .p8 key file (keep the BEGIN/END markers).
• Redirect URL: API endpoint the user returns to after Apple auth; omit trailing /.

Google Sign-In

• Client ID / Client Secret: OAuth credentials created in Google Cloud Console (Web application type).
• Add your site’s callback—for example /api/auth/google/callback—to the authorized redirect URIs.

Facebook Login

• App ID / App Secret: From the Facebook Developer portal. Make sure your domain is listed under “Valid OAuth Redirect URIs”.

GitHub Login

• Client ID / Client Secret: From GitHub Developer Settings → OAuth Apps.
• Set the callback to something like https://your-domain.com/api/auth/github/callback and require HTTPS.

Telegram Login

• Bot ID / Bot Token: Generated via @BotFather (enable the Login Widget permission).
• Users authorize by interacting with your bot; once configured the official Telegram dialog will pop up automatically.

Device Authentication

Best for client/TV apps that exchange a one-time device code.

• Enable device sign-in: Allows devices to authenticate via code or QR pairing.
• Show ads: Toggles advertising surfaces on the device experience.
• Block virtual machine: Rejects requests coming from emulators/VMs.
• Enable security: Forces every device request to include a shared communication key.
• Communication key: Paste your own or click the dice icon to auto-generate a 32-character GUID; create one per channel and keep it secret.

Operational Tips

• Snapshot SMTP/SMS credentials before switching providers so you can roll back quickly.
• Always use “Send test email” or “Test SMS” after editing settings—production users should never be the first to try a new config.
• Provider-specific SMS fields change dynamically; if a required field is missing, define it in the vendor console via template variables.
• For OAuth flows (Apple/Google/etc.), rehearse the entire login in a sandbox account to confirm the redirect URI and scopes are correct.
• Treat the communication key as a secret—share it only with trusted client apps and never commit it to version control.

FAQs

Email sends but users still see “verification failed”

• Confirm the domain whitelist includes the user’s email suffix.
• Some enterprise SMTP vendors require the From address to exactly match the authenticated account—otherwise the message is dropped.

SMS keeps failing

• Ensure the template is approved and that the placeholder name (e.g., {{code}}) matches what the vendor expects.
• Verify the destination area code is whitelisted.
• Still failing? Inspect the API error code in DevTools and cross reference it with the SMS provider documentation.

OAuth redirect mismatch errors

• Facebook, Google, and GitHub demand an exact match on the redirect URI, including protocol and trailing path—copy the admin value verbatim into the vendor console.

Related Docs

• System Config: Branding, SMTP defaults, and other site-wide settings.
• Payment Config: Configure gateways after your login flows are working.
• Ads Config: Pairs with the “Show ads” option in device authentication.