diff options
Diffstat (limited to 'doc/integration/arkose.md')
| -rw-r--r-- | doc/integration/arkose.md | 101 |
1 files changed, 92 insertions, 9 deletions
diff --git a/doc/integration/arkose.md b/doc/integration/arkose.md index 09a7defcff8..ae90f1f9574 100644 --- a/doc/integration/arkose.md +++ b/doc/integration/arkose.md @@ -13,7 +13,7 @@ Arkose Protect on GitLab.com. While this feature is theoretically usable in self is not recommended at the moment. GitLab integrates [Arkose Protect](https://www.arkoselabs.com/arkose-protect/) to guard against -credential stuffing and bots in the sign-in form. GitLab will trigger Arkose Protect if the user: +credential stuffing and bots in the sign-in form. GitLab triggers Arkose Protect if the user: - Has never signed in before. - Has failed to sign in twice in a row. @@ -26,6 +26,28 @@ the `Sign in` button. The challenge needs to be completed to proceed with the si 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. +```mermaid +sequenceDiagram + participant U as User + participant G as GitLab + participant A as Arkose Labs + U->>G: User loads form <br />(POST /api/:version/users/captcha_check) + 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-in attempts? Users are not denied access if Arkose Protect considers they are malicious. However, @@ -61,17 +83,78 @@ To enable Arkose Protect: Feature.enable(:arkose_labs_prevent_login) ``` -## QA tests caveat +## Triage and debug ArkoseLabs issues + +You can triage and debug issues raised by ArkoseLabs with: + +- The [GitLab production logs](https://log.gprd.gitlab.net). +- The [Arkose logging service](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/arkose/logger.rb). + +### View ArkoseLabs Verify API response for a user session + +To view an ArkoseLabs Verify API response for a user, [query the GitLab production logs](https://log.gprd.gitlab.net/goto/54b82f50-935a-11ed-9f43-e3784d7fe3ca) with the following KQL: + +```plaintext +KQL: json.message:"Arkose verify response" AND json.username:replace_username_here +``` + +If the query is valid, the result contains debug information about the user's session: + +| Response | Description | +|---------|-------------| +| `json.response.session_details.suppressed` | Value is `true` if the challenge was not shown to the user. Always `true` if the user is allowlisted. | +| `json.arkose.risk_band` | Can be `low`, `medium`, or `high`. Ignored on sign in. Use to debug identity verification issues. | +| `json.response.session_details.solved` | Indicates whether the user solved the challenge. Always `true` if the user is allowlisted. | +| `json.response.session_details.previously_verified` | Indicates whether the token has been reused. Default is `false`. If `true`, it might indicate malicious activity. | + +### 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](https://log.gprd.gitlab.net/goto/b97c8a80-935a-11ed-85ed-e7557b0a598c) with the following KQL: + +```plaintext +KQL: json.message:"Challenge was not solved" AND json.username:replace_username_here` +``` + +## Allowlists -Several GitLab QA test suites need to sign in to the app to test its features. This can conflict -with Arkose Protect as it would identify QA users as being malicious because they are being run with -a headless browser. To work around this, ArkoseLabs has allowlisted the unique token -that serves as QA session's User Agent. While this doesn't guarantee that the session won't be -flagged as malicious, Arkose's API returns a specific telltale when we verify the sign in -attempt's token. We are leveraging this telltale to bypass the verification step entirely so that the -test suite doesn't fail. This bypass is done in the `UserVerificationService` class. +To ensure end-to-end QA test suites can pass during staging and production, we've [allowlisted](https://developer.arkoselabs.com/docs/verify-api-v4#creating-allowlists-and-denylists) the [GITLAB_QA_USER_AGENT](https://start.1password.com/open/i?a=LKATQYUATRBRDHRRABEBH4RJ5Y&v=6gq44ckmq23vqk5poqunurdgay&i=u2wvs63affaxzi22gnfbjjw2zm&h=gitlab.1password.com). Each QA user receives an `ALLOWLIST` [risk category](https://developer.arkoselabs.com/docs/risk-score). + +You can find the usage of the allowlist telltale in our [Arkose::VerifyResponse](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/arkose/verify_response.rb#L38) 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 + +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](https://developer.chrome.com/docs/devtools/device-mode/override-user-agent/). You can find the appropriate string in [1Password](https://start.1password.com/open/i?a=LKATQYUATRBRDHRRABEBH4RJ5Y&v=6gq44ckmq23vqk5poqunurdgay&i=5v3ushqmfgifpwyqohop5gv5xe&h=gitlab.1password.com). + +Alternatively, to request specific behaviors, modify the `setConfig` to include a `data.id` property: + +- `'ML_defence'` - Force a challenge to appear. +- `'customer_request'` - Suppress a challenge. If you suppress a challenge, ArkoseLabs considers your session safe. + +For example, this `setConfig` suppresses a challenge: + +```javascript + arkoseObject.setConfig({ + data: { id: 'customer_request' }, + ... + }); +``` + +## Additional resources + +<!-- markdownlint-disable MD044 --> +The [Anti-abuse team](https://about.gitlab.com/handbook/engineering/development/data-science/anti-abuse/#team-members) owns the ArkoseLabs Protect feature. You can join our ArkoseLabs/GitLab collaboration channel on Slack: [#ext-gitlab-arkose](https://gitlab.slack.com/archives/C02SGF6RLPQ). +<!-- markdownlint-enable MD044 --> + +ArkoseLabs also maintains the following resources: + +- [ArkoseLabs portal](https://portal.arkoselabs.com/) +- [ArkoseLabs Zendesk](https://support.arkoselabs.com/) +- [ArkoseLabs documentation](https://developer.arkoselabs.com/docs/documentation-guide) |