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

• Telesign Transaction Callback Service
• Authenticating Transaction Callbacks

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

1. 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)

2. Setup Telesign

   $ rails c
   > ApplicationSetting.first.update(telesign_customer_xid: '<value_is_in_1Pass>', telesign_api_key: '<value_is_in_1Pass>')

3. Use ngrok to expose GDK instance

   $ ngrok http http://localhost:3000

   You also need to add .ngrok.app to allowed_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']

4. Copy the ngrok URL for your GDK instance

5. 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)

   1. Login to https://teleportal.telesign.com/
   2. Select GitLab - Test Account
   3. Select SMS Verify product on the sidebar
   4. Click Manage Settings
   5. Add <your_ngrok_gdk_url>/-/phone_verification/telesign_callback to Transaction Callback URLs field
   Click to expand

   

6. Tail logs

   $ tail -f log/application_json.log

7. Create a new user. After submitting the registration form you should see the Identity Verification page ("Help us keep GitLab secure")

8. To trigger the phone verification step, set the user's arkose_risk_score to Medium

   $ rails console
   > UserCustomAttribute.create(user: User.last, key: 'arkose_risk_band', value: 'Medium')

9. Refresh the page. You should now see the phone verification step

10. Enter your phone number then click Send code

11. Validate that a POST request is sent to <your_ngrok_gdk_url>/-/phone_verification/telesign_callback

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