Add Telesign transaction callback endpoint
What does this MR do and why?
Resolves https://gitlab.com/gitlab-org/modelops/anti-abuse/team-tasks/-/issues/411
Background
Identity verification feature requires some users to enter a code sent in an SMS to their phone number. This SMS is sent using Telesign.
Why?
Sometimes users are not able to receive the SMS when error occurs. Since these potential errors happen async (after GitLab sends the SMS) we can't record which makes it difficult to figure out why a user didn't receive a code.
What?
This MR adds an endpoint where Telesign can send status updates for SMS sent to users from GitLab. The endpoint receives a POST request from Telesign, authenticates it, and logs the event.
Docs
Screenshots or screen recordings
Sample log entry from the endpoint
{
"severity": "INFO",
"time": "2023-07-12T07:06:14.416Z",
"correlation_id": "01H54ER0Z1D8PA248TGFMWYRJ2",
"meta.caller_id": "Users::IdentityVerificationController#telesign_callback",
"meta.remote_ip": "104.193.12.13",
"meta.feature_category": "system_access",
"meta.client_id": "ip/104.193.12.13",
"message": "IdentityVerification::Phone",
"event": "Telesign transaction status update",
"telesign_reference_id": "362523AFDE4C050491948F0CFB10998F",
"telesign_status_code": "200 - Delivered to handset",
"telesign_status_updated_on": "2023-07-12T07:06:14.205428Z",
"telesign_errors": ""
}
Sample log entry from the endpoint (undelivered)
Phone number: +639200000000
{
"severity": "INFO",
"time": "2023-07-13T07:51:30.690Z",
"correlation_id": "01H573QMEDH3EG60HF9JTN7EM5",
"meta.caller_id": "Users::IdentityVerificationController#telesign_callback",
"meta.remote_ip": "104.193.12.13",
"meta.feature_category": "system_access",
"meta.client_id": "ip/104.193.12.13",
"message": "IdentityVerification::Phone",
"event": "Telesign transaction status update",
"telesign_reference_id": "362538EF31CC010491952AAD84D067F7",
"telesign_status_code": "207 - Error delivering message to handset (reason unknown)",
"telesign_status_updated_on": "2023-07-13T07:51:30.181896Z",
"telesign_errors": ""
}
How to set up and validate locally
-
Enable the relevant feature flags and configure required settings
$ rails c > Feature.enable(:telesign_callback) > Feature.enable(:identity_verification) > Feature.enable(:identity_verification_phone_number) > ApplicationSetting.first.update(email_confirmation_setting: "hard", require_admin_approval_after_user_signup: false)
-
Setup Telesign
$ rails c > ApplicationSetting.first.update(telesign_customer_xid: '<value_is_in_1Pass>', telesign_api_key: '<value_is_in_1Pass>')
-
Use ngrok to expose GDK instance
$ ngrok http http://localhost:3000
You also need to add
.ngrok.app
toallowed_hosts
# config/initializers/rails_host_authorization.rb Rails.application.config.hosts += [Gitlab.config.gitlab.host, 'unix', 'host.docker.internal', 'docker.for.mac.localhost', '.ngrok.app']
-
Copy the ngrok URL for your GDK instance
-
Setup Telesign to send transaction callbacks to the ngrok URL (if you don't have an account for the portal please let me know so I can assist you)
- Login to https://teleportal.telesign.com/
- Select
GitLab - Test Account
- Select
SMS Verify
product on the sidebar - Click
Manage Settings
- Add
<your_ngrok_gdk_url>/-/phone_verification/telesign_callback
toTransaction Callback URLs
field
-
Tail logs
$ tail -f log/application_json.log
-
Create a new user. After submitting the registration form you should see the Identity Verification page ("Help us keep GitLab secure")
-
To trigger the phone verification step, set the user's
arkose_risk_score
toMedium
$ rails console > UserCustomAttribute.create(user: User.last, key: 'arkose_risk_band', value: 'Medium')
-
Refresh the page. You should now see the phone verification step
-
Validate that a POST request is sent to
<your_ngrok_gdk_url>/-/phone_verification/telesign_callback
-
Validate that an entry like the one above is logged
MR acceptance checklist
This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.
-
I have evaluated the MR acceptance checklist for this MR.