How to use the ALTCHA Edge Function through Azion Marketplace

Azion’s ALTCHA Edge 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 Edge 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 Edge Function, ALTCHA integrates seamlessly with your Edge 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 an edge firewall

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

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

Setting up the Edge Firewall function

To instantiate the ALTCHA Edge Function, while still on the Edge 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.
  1. On the Arguments tab, add the parameters.
  2. Click the Save button.

Done. Now you have your ALTCHA Edge Function instanced.

Setting up the Edge 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:

Bot Manager

  1. In Edge 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.
    • In the Bot Manager JSON Args, set the redirect action to the ALTCHA verification endpoint so that traffic classified as suspicious is sent to the ALTCHA challenge page.
    • Align the same trigger criteria for both functions and use ALTCHA and Bot Manager in the Rules Engine. This ensures both solutions act on the same set of requests and that ALTCHA is always ready to receive redirects from Bot Manager.
  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.

Independently with Edge Firewall

  1. In Edge 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.

JSON Args

The ALTCHA function accepts the following JSON configuration arguments.

[{
"cookie_secret": "string",
"cookie_max_age": 86400,
"status_code": 200,
"captcha_localization": {
"error": "Custom error message",
"label": "Widget text",
"verifying": "Verifying...",
"verified": "Verified!"
},
"captcha_colors": {
"base": "#ffffff",
"border": "#cccccc",
"border_focus": "#007bff",
"text": "#333333",
"error_text": "#dc3545"
},
"custom_html": "Custom HTML"
}]

Configuration parameters

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

ParameterTypeRequiredDefault ValueDescription
allowed_domainsArray of stringsNo\${host}Defines which domains the function should allow redirects to. Note that the Edge Application host and relative redirects are always allowed. When an invalid value is provided, the function ignores it and logs a warning in Console > Edge Functions > Real-Time Events. Example of a valid input: “allowed_domains”: [“my-website.azion.app”, “third-party.azion.app”]
captcha_colorsObjectNo-Allows customization of the colors used in the ALTCHA widget.
captcha_colors.baseStringNo- (defined by ALTCHA)Base color of the ALTCHA widget. Expected to be a Hex Triplet color format.
captcha_colors.borderStringNo- (defined by ALTCHA)Border color of the ALTCHA widget. Expected to be a Hex Triplet color format.
captcha_colors.border_focusStringNo- (defined by ALTCHA)Border color of the ALTCHA widget when focused. Expected to be a Hex Triplet color format.
captcha_colors.error_textStringNo- (defined by ALTCHA)Color used for error messages in the ALTCHA widget. Expected to be a Hex Triplet color format.
captcha_colors.textStringNo- (defined by ALTCHA)Text color of the ALTCHA widget. Expected to be a Hex Triplet color format.
captcha_localizationObjectNo-Defines localization strings to be used in the ALTCHA challenge widget.
captcha_localization.errorStringNo- (defined by ALTCHA)Message shown when any error occurs while solving the ALTCHA challenge.
captcha_localization.labelStringNo- (defined by ALTCHA)Message displayed on the ALTCHA widget alongside the checkbox the user must click.
captcha_localization.verifiedStringNo- (defined by ALTCHA)Message displayed on the ALTCHA widget after detecting that the challenge was solved correctly. Note that the script redirects the user automatically after a successful solve, so most users won’t see this message.
captcha_localization.verifyingStringNo- (defined by ALTCHA)Message shown on the ALTCHA widget while the script is verifying the challenge solution.
cookie_max_ageIntegerNo86400Sets the maximum age for the session cookie.
cookie_secretStringNo@z10N!\${FUNCTION_VERSION}Secret key used to sign the session cookie.
custom_htmlStringNoThe default HTML is a simple white page with the ALTCHA widget.Allows you to customize the entire layout of the CAPTCHA challenge page. The function looks for the HTML tag {/* azion_captcha */} as an anchor to insert the ALTCHA widget. If the tag is not found, the widget is inserted at the end of the HTML body.
status_codeIntegerNo200Allows you to set the status code used in the ALTCHA challenge page response. If an invalid value is provided, or a status code that does not allow a response body (such as 101, 204, 205, or 304), the function ignores it and uses the default (200).

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 Edge 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 Edge 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.

{
"custom_html": "<!DOCTYPE html><html><head><title>Verification</title></head><body><h1>Complete the challenge</h1>{/* azion_captcha */}</body></html>"
}

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.

{
"captcha_localization": {
"error": "Verification error. Try again.",
"label": "Verify that you are human",
"verifying": "Verifying...",
"verified": "Successfully verified!"
}
}

Best practices

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

  1. Execution order: Always run ALTCHA before Bot Manager in the Rules Engine so the human challenge is solved before Bot Manager policies are applied, streamlining the security flow.
  2. Full URLs: Use full URLs (including scheme and hostname) in redirect parameters to avoid resolution issues and ensure users are directed correctly.
  3. 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.
  4. 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.
  5. 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:

Edge Firewall Rules Engine

Configure the following rules in your Edge Firewall Rules Engine:

Rule 1: ALTCHA Setup
- Criteria: Request URI matches `/api/submit` OR Request URI matches `/az-request-verify` OR Request URI matches `/az-request-captcha`
- Behavior: Run Function "ALTCHA"
Rule 2: Bot Manager
- Criteria: Request URI matches `/api/submit`
- Behavior: Run Function "Bot Manager"

ALTCHA JSON Args

Configure your ALTCHA instance parameters as needed. Example:

{
"cookie_max_age": 1800,
"captcha_localization": {
"label": "Verify that you are human"
},
"captcha_colors": {
"base": "#f8f9fa",
"border": "#dee2e6",
"text": "#495057"
}
}

This setup ensures that all access to the /api/submit endpoint goes through ALTCHA verification before Bot Manager analysis, providing multiple layers of protection.


ALTCHA Redirect — Version 1.2.0

To continuously improve security posture and functionality of the ALTCHA Edge 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.