CAPTCHAs in the Loginapp REST API and the Loginapp UI

CAPTCHAs are used in services that are accessible to non-authenticated users. They are intended to prevent bots or automated scripts from accessing Airlock IAM Self-Services.

  • CAPTCHAs are supported by the IAM Loginapp UI and in custom UIs (via Loginapp Design Kit) for:
  • User registration self-service flows.
    • SelfRegHCaptcha
  • Public self-service flows (such as password reset).
    • PublicSelfServiceReCaptch
  • Authentication flows (in the user-identifying and the username password step).
    • CaptchaAuthFlow

To configure CAPTCHAs in custom configuration-based UIs, see Loginapp Design Kit page settings configuration.

Supported types of CAPTCHAs

  • Airlock IAM supports the following types:
  • ReCaptcha (Google)
  • hCaptcha (hCaptcha)

Both CAPTCHA types are 3rd-party services and require an API key to be used. They are free up to a (relatively large) number of usages per month and both can be tested in Airlock IAM without an account. Refer to the service's web pages for further information.

Other 3rd-party CAPTCHA services may be integrated as long as they are compatible with the ReCaptcha API. To do so, use the Custom CAPTCHA plugin. Note that the UI part has to be manually integrated using the Loginapp Design Kit.

Usage and configuration in IAM flows

CAPTCHAs are supported in self-registration and in public self-service flows. To enable CAPTCHAs, just add (or connect) a CAPTCHA plugin in the corresponding flow step. Refer to the documentation in the Config Editor for further information.

  • At the time this article was written, the following flow steps were supported:
  • User Data Registration Step (self-registration flow)
  • Email Verification Step (self-registration flow)
  • Phone Number Verification Step (self-registration flow)
  • User Identification Step (Public Self-Service)
  • User Identification Step (authentication flow)

When using a Custom Flow Processors plugin (instead of the corresponding default processors plugin), make sure to place the CAPTCHA Processor first in the list.

Note that in the Email Verification Step and the Phone Number Verification Step, messages are sent before verifying the CAPTCHA.

Loginapp UI settings

To use CAPTCHAs with the Loginapp UI, you need to adapt the configured CSP (content security policy):

  1. Go to:
    Loginapp >> UI Settings >> Loginapp UI Content Security Policy (CSP)
  2. Add the required elements to the Content Security Policy for the chosen type of CAPTCHA. Refer to the CAPTCHA plugin documentation in the Config Editor to find out what you need to add. Look for hCAPTCHA or reCAPTCHA plugins.
  • Note that changing the display language of a page containing a hCaptcha does not cause the CAPTCHA's UI to change the language, too.
  • For ReCaptcha, only V2 CAPTCHAS are supported.
  • Incorrectly solved CAPTCHAs do not affect failure counters. The number of retries is therefore not limited by Airlock IAM.

Configuration example

CAPTCHAs should be configured on steps where the user is not yet authenticated. This is why CAPTCHA service plugins (hCAPTCHA or reCAPTCHA) often are configured on registration and verification flow steps.

Without going into details, an example IAM self-service registration flow with CAPTCHAs enabled might look like this (steps with CAPTCHA configuration option are marked):

CAPTCHA example self-service flow
  1. To enable one of the CAPTCHA services e.g. on the Email Verification Step:
  2. Navigate to the Email Verification Step - Email Verification and edit the step.
  3. In property CAPTCHA, select hCAPTCHA or reCAPTCHA plugin.

    4. The chosen CAPTCHA service must be configured with a valid Site key and Secret Key account details of the service.

  4. The CAPTCHA checkbox appears in the Loginapp UI at the email verification step.