v0.6.0

Security Settings

Configure security features including email verification, CAPTCHA, and Terms of Service.

Breadcrumb: System Configuration > Security Settings

Overview

Security Settings control authentication and fraud prevention features:

  • Email verification for new accounts

  • Google reCAPTCHA protection

  • Terms of Service content

  • Spam and bot prevention

These settings help protect your panel from abuse while ensuring legitimate users can register and use your services.

Settings Overview

Setting
Type
CLI
Admin Panel
Description

Require Email Verification

Select

✓

Email verification requirement level

Google CAPTCHA Verification

Boolean

✓

Enable reCAPTCHA on forms

Google CAPTCHA Site Key

Text

✓

reCAPTCHA site key (public)

Google CAPTCHA Secret Key

Secret

✓

reCAPTCHA secret key (private)

Terms of Service

Twig

✓

ToS page content

Note: Security settings are only configurable via Admin Panel, not the CLI wizard.

Configuration via Admin Panel

All security settings are managed through the Admin Panel.

Access Security Settings

  1. Log in to the Admin Panel

  2. Navigate to Settings in the main menu

  3. Click Security

  4. Update values

  5. Click Save

Setting Details

Require Email Verification

Setting Code: require_email_verification Field Type: Select (Dropdown) Required: Yes Default: disabled

Control email verification requirements for new user registrations.

Available Options:

Value
Description
Behavior

disabled

No verification

Users can log in immediately after registration

optional

Verification encouraged

Users can log in, but receive reminders to verify

required

Verification mandatory

Users must verify email before accessing panel

Option Details:

Disabled:

Optional:

Required:

Verification Flow (when Optional or Required):

  1. User registers account

  2. Email sent with verification link

  3. User clicks link in email

  4. Email address verified

  5. Access granted (if Required) or reminder dismissed (if Optional)

Best Practices:

Use "Required" If:

  • You want to prevent spam accounts

  • Need guaranteed valid email addresses

  • Require strong account security

  • Want to reduce bot registrations

  • Have reliable email delivery

Use "Optional" If:

  • Want balance between security and UX

  • Encourage verification without blocking access

  • Building trust gradually with users

  • Have other anti-abuse measures

Use "Disabled" If:

  • Using alternative verification (SMS, manual approval)

  • Want fastest possible onboarding

  • Have strong anti-abuse systems in place

  • Testing/development environment

  • Target audience may not have email access

Considerations:

  • Requires working SMTP configuration (see Email Settings)

  • Users may not check spam folder

  • Verification links typically expire after 24 hours

  • Provide easy resend verification option

  • Consider email deliverability to common providers

Impact on User Experience:

  • Required: Adds friction but ensures quality

  • Optional: Gentle reminder without blocking

  • Disabled: Smooth onboarding, potential for abuse

Google CAPTCHA Verification

Setting Code: google_captcha_verification Field Type: Boolean (Toggle) Required: No Default: false

Enable Google reCAPTCHA on registration and login forms.

When Enabled:

  • CAPTCHA displayed on forms

  • Prevents automated bot submissions

  • Reduces spam registrations

  • Protects against brute force

When Disabled:

  • No CAPTCHA challenge

  • Faster form submission

  • Better user experience

  • More vulnerable to bots

Protected Forms:

  • User registration

  • Login page

  • Password reset

  • Contact forms (if applicable)

reCAPTCHA Versions:

PteroCA supports Google reCAPTCHA v2 (checkbox).

Setup Required:

  1. Create Google reCAPTCHA account

  2. Register your site

  3. Get Site Key and Secret Key

  4. Configure in Security Settings

  5. Test CAPTCHA display

See Google reCAPTCHA Setup below for details.

Google CAPTCHA Site Key

Setting Code: google_captcha_site_key Field Type: Text Required: Only if CAPTCHA enabled Default: None

Your Google reCAPTCHA site key (public key).

Format:

Purpose:

  • Identifies your site to Google

  • Embedded in HTML

  • Public (visible in page source)

Obtaining Site Key:

  1. Visit https://www.google.com/recaptcha/admin

  2. Click "Register a new site" or "+"

  3. Fill in site information:

    • Label: Your panel name

    • reCAPTCHA type: reCAPTCHA v2 → "I'm not a robot" Checkbox

    • Domains: Add your domain(s)

      • panel.example.com

      • localhost (for testing)

  4. Accept Terms of Service

  5. Click Submit

  6. Copy Site Key

Multiple Domains: Add all domains where panel is accessible:

Security:

  • Public key, safe to expose

  • Specific to your domains

  • Cannot be used on other sites (by Google enforcement)

Google CAPTCHA Secret Key

Setting Code: google_captcha_secret_key Field Type: Secret (Password) Required: Only if CAPTCHA enabled Default: None

Your Google reCAPTCHA secret key (private key).

Format:

Purpose:

  • Verifies CAPTCHA response on server

  • Kept secret

  • Never exposed to clients

Obtaining Secret Key:

Follow same steps as Site Key above. Secret Key is shown alongside Site Key in reCAPTCHA admin console.

Security:

  • Keep absolutely confidential

  • Never commit to version control

  • Store in environment variables if possible

  • Rotate if compromised

Verification Process:

  1. User solves CAPTCHA

  2. Google returns response token

  3. PteroCA sends token + secret key to Google

  4. Google validates and responds

  5. PteroCA allows/denies form submission

Terms of Service

Setting Code: terms_of_service Field Type: Twig Template (Textarea) Required: No Default: None

Content for your Terms of Service page.

Purpose:

  • Legal protection

  • User agreement

  • Service conditions

  • Liability disclaimers

Format:

Supports HTML formatting for rich content.

HTML Example:

Best Practices:

  1. Consult Legal Counsel:

    • ToS is legal document

    • Seek professional advice

    • Ensure compliance with local laws

  2. Cover Key Topics:

    • Account terms

    • Payment and refunds

    • Service availability

    • Acceptable use

    • Limitation of liability

    • Privacy policy reference

    • Governing law

    • Contact information

  3. Keep Updated:

    • Review and update regularly

    • Notify users of changes

    • Include "Last Updated" date

  4. Make Accessible:

    • Link in footer

    • Show during registration

    • Easy to find and read

  5. Use Clear Language:

    • Avoid excessive legal jargon

    • Break into sections

    • Use headings and lists

Legal Considerations:

Depending on your jurisdiction, you may need to cover:

  • GDPR compliance (EU)

  • CCPA compliance (California)

  • Data retention policies

  • Cookie usage

  • Age restrictions

  • Intellectual property

  • Dispute resolution

Checkbox on Registration:

PteroCA displays ToS with acceptance checkbox during registration:

User cannot register without checking this box.

Google reCAPTCHA Setup

Complete guide to setting up Google reCAPTCHA.

Step 1: Create reCAPTCHA Account

  1. Visit https://www.google.com/recaptcha/admin

  2. Sign in with Google account

  3. You'll see reCAPTCHA Admin Console

Step 2: Register Your Site

Click "+" or "Register a new site"

Configuration:

  1. Label:

  2. reCAPTCHA type:

    • Select: reCAPTCHA v2

    • Choose: "I'm not a robot" Checkbox

  3. Domains: Add all domains (one per line):

  4. Owners:

    • Add email addresses of admins

    • They can manage reCAPTCHA settings

  5. Accept reCAPTCHA Terms of Service:

    • ☑ Accept

  6. Submit

Step 3: Copy Keys

After registration, you'll see:

Copy both keys.

Step 4: Configure in PteroCA

  1. Navigate to Settings → Security

  2. Enable "Google CAPTCHA Verification"

  3. Paste Site Key

  4. Paste Secret Key

  5. Save

Step 5: Test CAPTCHA

  1. Log out of panel

  2. Go to registration page

  3. Verify reCAPTCHA checkbox appears

  4. Complete registration with CAPTCHA

  5. Verify it works

Troubleshooting reCAPTCHA

CAPTCHA not appearing:

  1. Check JavaScript errors in browser console

  2. Verify Site Key is correct

  3. Clear browser cache

  4. Check domain is registered in Google Admin

"Invalid site key" error:

  1. Verify Site Key (not Secret Key) in HTML

  2. Check domain matches registered domain

  3. Ensure reCAPTCHA type matches (v2)

CAPTCHA validation fails:

  1. Verify Secret Key is correct

  2. Check server can reach Google APIs

  3. Verify no firewall blocking

  4. Test with different network

Rate limiting:

Google may rate limit if:

  • Too many requests from same IP

  • Suspicious activity detected

Solution: Wait and retry, or contact Google support.

Best Practices

Email Verification

  1. Clear Communication:

    • Explain verification is required

    • Provide resend option

    • Set reasonable expiration (24-48 hours)

  2. Email Deliverability:

    • Ensure SMTP is configured correctly

    • Check spam folders

    • Use verified sender domain

  3. Fallback Options:

    • Manual verification by admin

    • Support contact for issues

    • Alternative verification methods

CAPTCHA Implementation

  1. Balance Security vs UX:

    • Use on high-risk forms only

    • Consider invisible reCAPTCHA for better UX

    • Don't overuse

  2. Accessibility:

    • Provide audio alternative

    • Ensure keyboard navigation

    • Consider accessibility guidelines

  3. Monitor Effectiveness:

    • Track bot registration attempts

    • Adjust if needed

    • Consider rate limiting as alternative

Terms of Service

  1. Legal Review:

    • Have lawyer review

    • Ensure compliance

    • Update when laws change

  2. User Understanding:

    • Write clearly

    • Use headings

    • Highlight key points

  3. Version Control:

    • Keep historical versions

    • Log when users accepted

    • Notify of major changes

Troubleshooting

Email Verification Issues

Problem: Verification emails not received

Causes:

  • Email configuration broken

  • Spam filtering

  • Invalid email address

  • Email send rate limiting

Solutions:

  1. Test Email Settings:

    • Settings → Email → Test SMTP Connection

    • Send test email

  2. Check Spam Folder:

    • Instruct users to check spam

    • Whitelist sender address

  3. Resend Verification:

    • Provide resend button

    • Check rate limiting

  4. Manual Verification:

    • Admin can verify users manually

    • User Management → Edit User → Verify Email

Problem: Verification link expired

Cause: Default expiration is 24 hours

Solutions:

  1. Resend verification email

  2. User requests new link

  3. Admin manually verifies

CAPTCHA Problems

Problem: CAPTCHA not loading

Causes:

  • Google reCAPTCHA API blocked

  • JavaScript errors

  • Adblockers

  • Network issues

Solutions:

  1. Check Browser Console:

    • F12 → Console

    • Look for errors

  2. Disable Adblockers:

    • Some block reCAPTCHA

    • Whitelist your domain

  3. Test Different Browser:

    • Rule out browser-specific issues

  4. Check Firewall:

    • Ensure access to www.google.com/recaptcha

    • Port 443 must be open

Problem: "Invalid site key" error

Cause: Site Key mismatch or domain not registered

Solutions:

  1. Verify Site Key:

    • Check for typos

    • Ensure using Site Key (not Secret)

  2. Check Domain Registration:

    • Google Admin Console

    • Add current domain

  3. Clear Cache:

    • Browser cache

    • Application cache

Problem: CAPTCHA validation fails

Cause: Secret Key incorrect or server cannot reach Google

Solutions:

  1. Verify Secret Key:

    • Check for typos

    • Regenerate if needed

  2. Test Google API Access:

  3. Check Server Firewall:

    • Allow outbound HTTPS to google.com

Terms of Service Issues

Problem: ToS page blank

Cause: Content not set

Solution:

  1. Navigate to Settings → Security

  2. Add Terms of Service content

  3. Save

Problem: Twig syntax error

Cause: Invalid Twig template

Solutions:

  1. Check HTML Syntax:

    • Verify properly closed tags

    • Validate HTML structure

  2. Test Content:

    • Start with simple HTML

    • Test display after changes

Problem: ToS checkbox not appearing

Cause: JavaScript or template issue

Solutions:

  1. Check Browser Console:

    • Look for JavaScript errors

  2. Clear Cache:

  3. Verify Template:

    • Check registration template

Related Settings

Additional Resources

PreviousTheme SettingsNextPayment Settings

Last updated