Arkose Protect

Arkose Protect is used on GitLab.com and is not supported for GitLab Self-Managed instances. The following documents the internal requirements for maintaining Arkose Protect on GitLab.com. While this feature is theoretically usable in GitLab Self-Managed instances, it is not recommended at the moment.

GitLab integrates Arkose Protect to guard against malicious users from creating accounts.

How does it work?

If Arkose Protect determines that the user is suspicious, it presents an interactive challenge below the Sign in button. The challenge needs to be completed to proceed with the sign-in attempt. If Arkose Protect trusts the user, the challenge runs in transparent mode, meaning that the user doesn't need to take any additional action and can sign in as usual.

%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
accTitle: Sequence of an Arkose Protect challenge
accDescr: How GitLab sends data to Arkose Labs to determine whether to present a challenge during the sign-in attempt.

    participant U as User
    participant G as GitLab
    participant A as Arkose Labs
    U->>G: User loads signup form
    G->>A: Sends device fingerprint and telemetry
    A->>U: Returns Session token and decision on if to challenge
    opt Requires Challenge
        U->>U: User interacts with Challenge iframe
    end
    U->>G: Submits form with Arkose Labs token
    G ->> A: Sends token to be verified
    A ->> G: Returns verification response
    Note over G: records `UserCustomAttribute::risk_band`
    alt session_details.solved == true
        G ->> U: Proceed
    else session_details.solved == false
        G ->> U: Do not proceed
    end

How do we treat malicious sign-up attempts?

Depending on the risk score received, a user might be required to perform up to three stages of identity verification to register an account.

Configuration

To enable Arkose Protect:

1. License ArkoseLabs.

2. Get the public and private API keys from the ArkoseLabs Portal.

3. Enable the ArkoseLabs login challenge. Run the following commands in the Rails console, replacing <your_public_api_key> and <your_private_api_key> with your own API keys.

   ApplicationSetting.current.update(arkose_labs_public_api_key: '<your_public_api_key>')
   ApplicationSetting.current.update(arkose_labs_private_api_key: '<your_private_api_key>')

To disable Arkose Protect, run the following command in the Rails console.

ApplicationSetting.current.update(arkose_labs_enabled: false)

Disabling Arkose also disables phone number and credit card verification. New users are only required to verify their email address.

It is important to note that disabling Arkose also disables phone number and credit card verification. All new users will only be required to verify their email address.

Triage and debug ArkoseLabs issues

You can triage and debug issues raised by ArkoseLabs with:

• ArkoseLabs and GitLab collaboration channel on Slack: #ext-gitlab-arkose

• The GitLab production logs.
• The Arkose logging service
• The Arkose Labs Portal (users can request access through the Okta portal)

Analysing Arkose Labs dashboard

• GitLab regularly sends session data to the Arkose team, which is used to apply custom telltales to prevent malicious users from signing up.
• When functioning normally, less than 10% of users should be classified as high risk and over 90% of sessions should be verified.

• If the percentage of high risk users or verified sessions is significantly different from the expected percentages, contact the #ext-gitlab-arkose Slack channel.

View ArkoseLabs Verify API response for a user session

To view an ArkoseLabs Verify API response for a user, query the GitLab production logs with the following KQL:

KQL: json.message:"Arkose challenge solved" AND json.username:replace_username_here

If the query is valid, the result contains debug information about the user's session:

Check if a user failed an ArkoseLabs challenge

To check if a user failed to sign in because the ArkoseLabs challenge was not solved, query the GitLab production logs with the following KQL:

KQL: json.message:"Arkose*" AND json.username:replace_username_here

Allowlists

To ensure end-to-end QA test suites can pass during staging and production, we've allowlisted the GITLAB_QA_USER_AGENT. Each QA user receives an ALLOWLIST risk category.

You can find the usage of the allowlist telltale in our Arkose::VerifyResponse class.

Feedback Job

To help Arkose improve their protection service, we created a daily background job to send them the list of blocked users by us. This job is performed by the Arkose::BlockedUsersReportWorker class.

Test your integration

Version history

• Requesting specific behaviors with Data Exchange introduced in GitLab 16.8 with a flag named arkose_labs_signup_data_exchange. Disabled by default.

In staging and development environments only, you can suppress a challenge, or force one to appear. You can use this feature if you want to receive a specific risk band.

To force a challenge, change your browser user agent string. You can find the appropriate string in 1Password.

Alternatively, to request specific behaviors, enable the arkose_labs_signup_data_exchange feature flag and modify the Data Exchange payload to include an interactive field with any of the following values:

• 'true' - Force a challenge to appear.
• 'false' - Suppress a challenge. If you suppress a challenge, ArkoseLabs considers your session safe.

For example, the following diff updates the payload to suppress the challenge:

diff --git a/ee/lib/arkose/data_exchange_payload.rb b/ee/lib/arkose/data_exchange_payload.rb
index 191ae0b5cf82..b2d888b98c95 100644
--- a/ee/lib/arkose/data_exchange_payload.rb
+++ b/ee/lib/arkose/data_exchange_payload.rb
@@ -35,6 +35,7 @@ def json_data
       now = Time.current.to_i

       data = {
+        interactive: 'false',
         timestamp: now.to_s, # required to be a string
         "HEADER_user-agent" => request.user_agent,
         "HEADER_origin" => request.origin,

Additional resources

• GitLab team members only. Identity Verification

ArkoseLabs also maintains the following resources:

• ArkoseLabs portal
• ArkoseLabs Zendesk
• ArkoseLabs documentation
• ArkoseLabs Data Exchange documentation