How to Use the ALTCHA Function

Azion’s ALTCHA Function is a serverless integration available through the Azion Marketplace.

It provides an additional security layer to protect your web applications against bots, spam, and malicious activity, while minimizing impact on end-user experience.

Unlike traditional CAPTCHA systems, ALTCHA is a free, modern, open-source alternative that runs at the edge, ensuring optimized performance, ultra-low latency, and low cost.

Key capabilities of the ALTCHA Function include:

• Native edge protection: Verification is processed in Azion’s distributed data centers, mitigating threats as close to the user as possible.
• Open-source: Its transparent, auditable nature provides greater trust and flexibility for developers.
• No external dependencies: Operates independently of third-party services, within Azion’s infrastructure.
• Optimized performance: Distributed processing at the edge ensures instant verification with minimal resource consumption and ultra-low latency.
• Native integration: As an Azion Function, ALTCHA integrates seamlessly with your Firewall security architecture and workflow.

Advantages over traditional CAPTCHAs:

• Accessibility: Compatible with screen readers and assistive technologies so all users can interact with your applications.
• Privacy: It does not collect personal data, respecting user privacy and data protection regulations.
• Efficiency: Instant verification with minimal resource usage, optimizing overall application performance.

How it works

ALTCHA ensures that only users with legitimate human behavior can be authenticated and access your applications, while bots and malicious traffic are blocked—maintaining a high security level with minimal impact on performance and usability.

The ALTCHA function creates two special endpoints in your application to manage the verification flow:

• /az-request-verify: The endpoint that displays the CAPTCHA challenge. Users should be redirected here whenever a challenge is required. Accessing it returns a new CAPTCHA challenge for verification.
• /az-request-captcha: After a user successfully solves the challenge, the ALTCHA script automatically calls this endpoint to validate the solution. If validation succeeds, the script sets a session cookie in the user’s browser, allowing future requests to be verified automatically without new challenges.

Workflow

1. The user accesses a protected endpoint in your application.
2. The security layer redirects the user to the /az-request-verify endpoint.
3. The CAPTCHA challenge is displayed to the user.
4. After solving the challenge, ALTCHA sets session cookies in the user’s browser.
5. The same user’s future requests are validated automatically via session cookies, without requiring new challenges.

Configuring the ALTCHA challenge

Setting up a firewall

ALTCHA runs on the Firewall. To enable it, first create a rule in Firewall, following these steps:

1. Open Azion Console > Firewall.
2. Click + Firewall.
3. Give a name to your firewall.
4. Enable the Functions switch.
5. Click Save.

Setting up the Firewall function

To instantiate the ALTCHA Function, while still on the Firewall page:

1. Go to the Functions Instances tab.
2. Click the + Function Instance button.
3. Give a name to your instance.
4. On the dropdown menu, select ALTCHA.

• This action will load the Arguments tab.

5. On the Arguments tab, add the parameters.
6. Click the Save button.

Done. Now you have your ALTCHA Function instanced.

Setting up the Firewall Rules Engine

To finish, you have to set up the Rules Engine to configure the behavior and the criteria to run ALTCHA. To do this:

Independently with Firewall

1. In Firewall, select Rules Engine.
2. Click + Rules Engine to create a rule that runs the ALTCHA function.
3. In the Name field, enter a unique, descriptive name.
4. In Criteria, define when to show the challenge.
   • The X-Azcaptcha-Success header indicates the ALTCHA challenge was solved successfully.
5. Ensure ALTCHA runs whenever a Request URI matches the endpoints /form, /az-request-verify, and /az-request-captcha.
   • When the request is for /form and the X-Azcaptcha-Success header does not exist, redirecting to /az-request-verify will start the challenge flow.
6. In Behavior, select Run Function > ALTCHA.
7. Keep Status as Active.
8. Click Save.

Setting up the redirect in Application

For the ALTCHA flow to work correctly, you also need to create a rule in the Application Rules Engine to redirect users to the verification endpoint when the challenge hasn’t been solved yet.

1. Open Azion Console > Applications.
2. Select the Application you want to protect with ALTCHA.
3. Go to the Rules Engine tab and click + Rule.
4. In the Name field, enter a unique, descriptive name.
5. In Phase, select Request.
6. In the Criteria section, configure the following conditions:
   • Variable: ${http_X_Azcaptcha_Success}
   • Operator: does not exist
   • Variable: ${uri}
   • Operator: is equal
   • Value: /form
7. In the Behavior section, select Redirect To (302 Found) and enter /az-request-verify as the destination.
8. Keep Status as Active.
9. Click Save.

This rule ensures that any user who accesses a protected endpoint without a valid session cookie is redirected to the ALTCHA challenge page, starting the verification flow.

JSON Args

The ALTCHA function accepts the following JSON configuration arguments.

Configuration parameters

The table below details each configuration parameter available for the ALTCHA Function:

Limitations

Keep these limitations in mind to ensure correct implementation and operation:

• HTTPS required: ALTCHA requires HTTPS due to the use of the Web Crypto API.
• Full URLs: Redirect parameters should include scheme and hostname.
• Reserved endpoints: The /az-request-verify and /az-request-captcha endpoints are reserved and must be used exclusively for ALTCHA Function control. Ensure your application does not use URLs with these terms.

Control headers

ALTCHA sets specific HTTP headers to control the flow and indicate verification status. These headers are useful for debugging and application logic:

• X-AZCAPTCHA-SUCCESS: true — Indicates the user solved the challenge successfully.
• X-AZCAPTCHA-VIOLATION: true — Signals that an attempt to bypass the system was detected.

Session cookies

ALTCHA uses two cookies to manage the verification session state:

1. az_\${FUNCTION_VERSION}_verify_payload: Contains the raw data of the challenge solution.
2. az_\${FUNCTION_VERSION}_verify_session: The signed session cookie used to validate future requests without a new challenge.

Customization

The ALTCHA Function provides several customization options to adapt the challenge experience to your brand and application needs.

Custom HTML

You can fully customize the page where the ALTCHA challenge is displayed using your own HTML. This allows you to keep visual and brand consistency with your application.

Localization

To provide a global and accessible experience, you can customize the messages displayed in the ALTCHA widget for different languages using the captcha_localization parameter.

Best practices

Follow these recommendations to maximize effectiveness and optimize usage of the ALTCHA Function:

1. Full URLs: Use full URLs (including scheme and hostname) in redirect parameters to avoid resolution issues and ensure users are directed correctly.
2. Appropriate cookie TTL: Configure cookie_max_age (TTL) based on your application’s security and usability needs. A very short TTL can cause frequent challenges; a very long TTL can reduce security.
3. Experience customization: Use custom_html and captcha_colors to style the challenge page and ALTCHA widget according to your brand for a consistent user experience.
4. Log monitoring: Actively monitor logs to identify bypass attempts or suspicious activity and adjust your configuration as needed.

Practical example

Consider an application where you want to protect the /api/submit route. You will need to:

Firewall Rules Engine

Configure the following rules in your Firewall Rules Engine:

ALTCHA Redirect — Version 1.2.0

To continuously improve security posture and functionality of the ALTCHA Function, we released ALTCHA Redirect version 1.2.0. Read the Release Notes to learn more.

Important information for existing ALTCHA Redirect users

• Update your ALTCHA redirect instances and configure the allowed domains parameter to protect users against open redirects.
• With the new allowed_domains JSON Args parameter, you can define which domains the function should allow redirects to.