Allow users to opt back in to SMS (LG-3510)

CHANGELOG.md

@@ -7,6 +7,7 @@ Unreleased
 ### Improvements/Changes
 - Layout: Improve layout margins and typographical consistency across several content pages. (#5880, #5884, #5887, #5888, #5908)
 - Typography: Updated monospace font to Roboto Mono for consistency across login.gov sites. (#5891)
+- Multi-factor authentication: Add ability to opt numbers back in to receiving SMS that have replied "STOP" (#5894)
 - Icons: Replaced custom button icons using U.S. Web Design system icons. (#5904)
 
 ### Accessibility

Gemfile

@@ -11,6 +11,7 @@ gem 'aws-sdk-kms', '~> 1.4'
 gem 'aws-sdk-pinpoint'
 gem 'aws-sdk-pinpointsmsvoice'
 gem 'aws-sdk-ses', '~> 1.6'
+gem 'aws-sdk-sns'
 gem 'base32-crockford'
 gem 'blueprinter', '~> 0.25.3'
 gem 'bootsnap', '~> 1.9.0', require: false

Gemfile.lock

@@ -136,6 +136,9 @@ GEM
     aws-sdk-ses (1.44.0)
       aws-sdk-core (~> 3, >= 3.122.0)
       aws-sigv4 (~> 1.1)
+    aws-sdk-sns (1.49.0)
+      aws-sdk-core (~> 3, >= 3.122.0)
+      aws-sigv4 (~> 1.1)
     aws-sigv4 (1.4.0)
       aws-eventstream (~> 1, >= 1.0.2)
     axe-core-api (4.3.2)
@@ -689,6 +692,7 @@ DEPENDENCIES
   aws-sdk-pinpoint
   aws-sdk-pinpointsmsvoice
   aws-sdk-ses (~> 1.6)
+  aws-sdk-sns
   axe-core-rspec (~> 4.2)
   base32-crockford
   better_errors (>= 2.5.1)

app/controllers/two_factor_authentication/sms_opt_in_controller.rb

@@ -0,0 +1,97 @@
+module TwoFactorAuthentication
+  class SmsOptInController < ApplicationController
+    before_action :load_phone_configuration
+
+    def new
+      @other_mfa_options_url = other_options_mfa_url
+      @cancel_url = cancel_url
+
+      analytics.track_event(
+        Analytics::SMS_OPT_IN_VISIT,
+        new_user: new_user?,
+        has_other_auth_methods: has_other_auth_methods?,
+        phone_configuration_id: @phone_configuration.id,
+      )
+    end
+
+    def create
+      response = opt_out_manager.opt_in_phone_number(@phone_configuration.formatted_phone)
+
+      analytics.track_event(
+        Analytics::SMS_OPT_IN_SUBMITTED,
+        response.to_h.merge(
+          new_user: new_user?,
+          has_other_auth_methods: has_other_auth_methods?,
+          phone_configuration_id: @phone_configuration.id,
+        ),
+      )
+
+      if response.success?
+        redirect_to otp_send_url(otp_delivery_selection_form: { otp_delivery_preference: :sms })
+      else
+        @other_mfa_options_url = other_options_mfa_url
+        @cancel_url = cancel_url
+
+        if !response.error
+          # unsuccessful, but didn't throw an exception: already opted in last 30 days
+          render :error
+        else
+          # one-off error, show form so users can try again
+          flash[:error] = t('two_factor_authentication.opt_in.error_retry')
+          render :new
+        end
+      end
+    end
+
+    private
+
+    def opt_out_manager
+      Telephony::Pinpoint::OptOutManager.new
+    end
+
+    def mfa_context
+      @mfa_context ||= MfaContext.new(current_user)
+    end
+
+    def load_phone_configuration
+      if user_session.present? && (unconfirmed_phone = user_session[:unconfirmed_phone]).present?
+        @phone_configuration = PhoneConfiguration.new(phone: unconfirmed_phone)
+      elsif user_session.present? && (phone_id = user_session[:phone_id]).present?
+        @phone_configuration = mfa_context.phone_configuration(phone_id)
+      else
+        render_not_found
+      end
+    end
+
+    def other_options_mfa_url
+      if new_user?
+        two_factor_options_path
+      elsif has_other_auth_methods? && !user_fully_authenticated?
+        login_two_factor_options_path
+      end
+    end
+
+    def cancel_url
+      if user_fully_authenticated?
+        account_path
+      elsif decorated_session.sp_name
+        return_to_sp_cancel_path
+      else
+        sign_out_path
+      end
+    end
+
+    def has_other_auth_methods?
+      two_factor_configurations.
+        any? { |config| config.mfa_enabled? && config != @phone_configuration }
+    end
+
+    def new_user?
+      two_factor_configurations.none?
+    end
+
+    def two_factor_configurations
+      @two_factor_configurations ||= mfa_context.two_factor_configurations
+    end
+  end
+end

app/controllers/users/two_factor_authentication_controller.rb

@@ -177,6 +177,12 @@ def handle_telephony_result(method:, default:)
           otp_make_default_number: default,
           reauthn: reauthn?,
         )
+      elsif @telephony_result.error.is_a?(Telephony::OptOutError) &&
+            IdentityConfig.store.sms_resubscribe_enabled
+        # clear message from https://github.com/18F/identity-idp/blob/7ad3feab24f6f9e0e45224d9e9be9458c0a6a648/app/controllers/users/phones_controller.rb#L40
+        flash.delete(:info)
+        user_session[:phone_id] = phone_configuration.id if phone_configuration&.phone
+        redirect_to login_two_factor_sms_opt_in_path
       else
         invalid_phone_number(@telephony_result.error, action: action_name)
       end

app/services/analytics.rb

@@ -266,6 +266,8 @@ def browser_attributes
   SESSION_KEPT_ALIVE = 'Session Kept Alive'
   SESSION_TOTAL_DURATION_TIMEOUT = 'User Maximum Session Length Exceeded'
   SIGN_IN_PAGE_VISIT = 'Sign in page visited'
+  SMS_OPT_IN_SUBMITTED = 'SMS Opt-In: Submitted'
+  SMS_OPT_IN_VISIT = 'SMS Opt-In: Visited'
   SP_REDIRECT_INITIATED = 'SP redirect initiated'
   TELEPHONY_OTP_SENT = 'Telephony: OTP sent'
   THROTTLER_RATE_LIMIT_TRIGGERED = 'Throttler Rate Limit Triggered'

app/views/two_factor_authentication/sms_opt_in/error.html.erb

@@ -0,0 +1,37 @@
+<%= image_tag asset_url('alert/fail-x.svg'),
+              alt: t('errors.alt.error'),
+              width: 54,
+              class: 'margin-bottom-2' %>
+
+<%= render PageHeadingComponent.new.with_content(t('two_factor_authentication.opt_in.title')) %>
+
+<p>
+  <%= t(
+        'two_factor_authentication.opt_in.opted_out_last_30d_html',
+        phone_number: content_tag(:strong, @phone_configuration.masked_phone),
+      ) %>
+</p>
+
+<p><%= t('two_factor_authentication.opt_in.wait_30d_opt_in') %></p>
+
+<%= render(
+      'shared/troubleshooting_options',
+      heading_tag: :h3,
+      heading: t('components.troubleshooting_options.default_heading'),
+      options: [
+        @other_mfa_options_url && {
+          url: @other_mfa_options_url,
+          text: t('two_factor_authentication.login_options_link_text'),
+        },
+        decorated_session.sp_name && {
+          url: return_to_sp_cancel_path(location: 'sms_resubscribe_error'),
+          text: t('idv.troubleshooting.options.get_help_at_sp', sp_name: decorated_session.sp_name),
+        },
+        {
+          url: MarketingSite.contact_url,
+          text: t('links.contact_support', app_name: APP_NAME),
+        },
+      ].select(&:present?),
+    ) %>
+
+<%= render 'shared/cancel', link: sign_out_path %>

app/views/two_factor_authentication/sms_opt_in/new.html.erb

@@ -0,0 +1,31 @@
+<%= image_tag asset_url('alert/warning-lg.svg'),
+              alt: t('errors.alt.warning'),
+              width: 54,
+              class: 'margin-bottom-2' %>
+
+<%= render PageHeadingComponent.new.with_content(t('two_factor_authentication.opt_in.title')) %>
+
+<p>
+  <%= t(
+        'two_factor_authentication.opt_in.opted_out_html',
+        phone_number: content_tag(:strong, @phone_configuration.masked_phone),
+      ) %>
+</p>
+
+<%= link_to t('two_factor_authentication.mobile_terms_of_service'),
+            MarketingSite.messaging_practices_url,
+            class: 'margin-top-2' %>
+
+<%= button_to t('forms.buttons.send_security_code'),
+              login_two_factor_sms_opt_in_path,
+              class: 'usa-button usa-button--wide usa-button--big',
+              form_class: 'margin-y-5' %>
+
+<% if @other_mfa_options_url %>
+  <h2 class="margin-top-5"><%= t('two_factor_authentication.opt_in.cant_use_phone') %></h2>
+
+  <%= link_to t('two_factor_authentication.login_options_link_text'),
+              @other_mfa_options_url %>
+<% end %>
+
+<%= render 'shared/cancel', link: @cancel_url %>

config/application.yml.default

@@ -215,6 +215,7 @@ show_select_account_on_repeat_sp_visits: 'false'
 sp_context_needed_environment: 'prod'
 sp_handoff_bounce_max_seconds: '2'
 show_user_attribute_deprecation_warnings: 'false'
+sms_resubscribe_enabled: 'false'
 test_ssn_allowed_list: ''
 unauthorized_scope_enabled: 'false'
 usps_upload_enabled: 'false'

config/locales/links/en.yml

@@ -9,6 +9,7 @@ en:
     cancel: Cancel
     cancel_account_creation: '‹ Cancel account creation'
     contact: Contact
+    contact_support: 'Contact %{app_name} Support'
     continue_sign_in: Continue sign in
     copy: Copy
     create_account: Create an account

config/locales/links/es.yml

@@ -9,6 +9,7 @@ es:
     cancel: Cancelar
     cancel_account_creation: '‹ Cancelar la creación de cuenta'
     contact: Contactar
+    contact_support: 'Póngase en contacto con el soporte técnico de %{app_name}'
     continue_sign_in: Continuar el inicio de sesión
     copy: Copiar
     create_account: Crear cuenta

config/locales/links/fr.yml

@@ -9,6 +9,7 @@ fr:
     cancel: Annuler
     cancel_account_creation: '‹ Annuler la création du compte'
     contact: Contact
+    contact_support: 'Contactez %{app_name} le support'
     continue_sign_in: Continuer la connexion
     copy: Copier
     create_account: Créer un compte

config/locales/two_factor_authentication/en.yml

@@ -71,6 +71,17 @@ en:
       incorrectly too many times.
     mobile_terms_of_service: Mobile terms of service
     no_auth_option: No authentication option could be found for you to sign in.
+    opt_in:
+      cant_use_phone: 'Can’t use your phone?'
+      error_retry: 'Sorry, we are having trouble opting you in. Please try again.'
+      opted_out_html: 'You’ve opted out of receiving text messages at %{phone_number}.
+        You can opt in and receive a security code again to that phone number.'
+      opted_out_last_30d_html: 'You’ve opted out of receiving text messages at
+        %{phone_number} within the last 30 days. We can only opt in a phone
+        number once every 30 days.'
+      title: We could not send a security code to your phone number
+      wait_30d_opt_in: 'After 30 days, you can opt in and receive a security code to
+        that phone number.'
     otp_delivery_preference:
       instruction: You can change this selection the next time you sign in. If you
         entered a landline, please select “Phone call” below.

config/locales/two_factor_authentication/es.yml

@@ -77,6 +77,19 @@ es:
       forma incorrecta demasiadas veces.
     mobile_terms_of_service: Condiciones de servicio móvil
     no_auth_option: No se pudo encontrar ninguna opción de autenticación para iniciar sesión
+    opt_in:
+      cant_use_phone: '¿No puede utilizar su teléfono?'
+      error_retry: 'Lo sentimos, estamos teniendo problemas para aceptarlo. Por favor,
+        inténtelo de nuevo.'
+      opted_out_html: 'Ha optado por no recibir mensajes de texto en el
+        %{phone_number}. Puede optar por recibir un código de seguridad de nuevo
+        a ese número de teléfono.'
+      opted_out_last_30d_html: 'Canceló su suscripción para recibir mensajes de texto
+        al %{phone_number} en los últimos 30 días. Solo podemos suscribir un
+        número telefónico una vez cada 30 días.'
+      title: 'No hemos podido enviar un código de seguridad a su número de teléfono'
+      wait_30d_opt_in: 'Después de 30 días, podrá inscribirse y recibir un código de
+        seguridad para ese número de teléfono.'
     otp_delivery_preference:
       instruction: Puede cambiar esta selección la próxima vez que inicie sesión.
       no_supported_options: No podemos verificar los números de teléfono de %{location}

config/locales/two_factor_authentication/fr.yml

@@ -78,6 +78,20 @@ fr:
       PIV/CAC à de trop nombreuses reprises.
     mobile_terms_of_service: Conditions de service mobile
     no_auth_option: Aucune option d’authentification n’a été trouvée pour vous connecter
+    opt_in:
+      cant_use_phone: 'Vous ne pouvez pas utiliser votre téléphone?'
+      error_retry: 'Désolé, nous avons des difficultés à vous connecter. Veuillez
+        réessayer.'
+      opted_out_html: 'Vous avez choisi de ne plus recevoir de SMS à %{phone_number}.
+        Vous pouvez vous inscrire et recevoir à nouveau un code de sécurité à ce
+        numéro de téléphone.'
+      opted_out_last_30d_html: 'Vous avez choisi de ne plus recevoir de SMS au
+        %{phone_number} au cours des 30 derniers jours. Nous ne pouvons opter
+        pour un numéro de téléphone qu’une fois tous les 30 jours.'
+      title: 'Nous n’avons pas pu envoyer un code de sécurité à votre numéro de
+        téléphone'
+      wait_30d_opt_in: 'Après 30 jours, vous pouvez vous inscrire et recevoir un code
+        de sécurité à ce numéro de téléphone.'
     otp_delivery_preference:
       instruction: Vous pouvez modifier cette sélection lors de votre prochaine connexion.
       no_supported_options: Nous ne sommes pas en mesure de vérifier les numéros de

config/routes.rb

@@ -102,7 +102,9 @@
       get  '/login/two_factor/:otp_delivery_preference' => 'two_factor_authentication/otp_verification#show',
            as: :login_two_factor, constraints: { otp_delivery_preference: /sms|voice/ }
       post '/login/two_factor/:otp_delivery_preference' => 'two_factor_authentication/otp_verification#create',
-           as: :login_otp
+           as: :login_otp, constraints: { otp_delivery_preference: /sms|voice/ }
+      get '/login/two_factor/sms/opt_in' => 'two_factor_authentication/sms_opt_in#new'
+      post '/login/two_factor/sms/opt_in' => 'two_factor_authentication/sms_opt_in#create'
 
       get 'login/add_piv_cac/prompt' => 'users/piv_cac_setup_from_sign_in#prompt'
       post 'login/add_piv_cac/prompt' => 'users/piv_cac_setup_from_sign_in#decline'

lib/identity_config.rb

@@ -304,6 +304,7 @@ def self.build_store(config_map)
     config.add(:show_user_attribute_deprecation_warnings, type: :boolean)
     config.add(:skip_encryption_allowed_list, type: :json)
     config.add(:show_select_account_on_repeat_sp_visits, type: :boolean)
+    config.add(:sms_resubscribe_enabled, type: :boolean)
     config.add(:sp_context_needed_environment, type: :string)
     config.add(:sp_handoff_bounce_max_seconds, type: :integer)
     config.add(:sps_over_quota_limit_notify_email_list, type: :json)

lib/telephony.rb

@@ -15,6 +15,8 @@
 require 'telephony/test/sms_sender'
 require 'telephony/test/voice_sender'
 require 'telephony/pinpoint/aws_credential_builder'
+require 'telephony/pinpoint/pinpoint_helper'
+require 'telephony/pinpoint/opt_out_manager'
 require 'telephony/pinpoint/sms_sender'
 require 'telephony/pinpoint/voice_sender'
 

lib/telephony/pinpoint/opt_out_manager.rb

@@ -0,0 +1,43 @@
+module Telephony
+  module Pinpoint
+    class OptOutManager
+      # @return [Response]
+      def opt_in_phone_number(phone_number)
+        Telephony.config.pinpoint.sms_configs.each do |config|
+          client = build_client(config)
+          next if client.nil?
+
+          opt_in_response = client.opt_in_phone_number(phone_number: phone_number)
+
+          return Response.new(success: opt_in_response.successful?)
+        rescue Aws::SNS::Errors::InvalidParameter
+          # This is thrown when the number has been opted in too recently
+          return Response.new(success: false)
+        rescue Seahorse::Client::NetworkingError,
+               Aws::SNS::Errors::ServiceError => error
+          PinpointHelper.notify_pinpoint_failover(
+            error: error,
+            region: config.region,
+            channel: :notification_service,
+            extra: {},
+          )
+        end
+
+        PinpointHelper.handle_config_failure(:notification_service)
+      end
+
+      # @api private
+      # @param [PinpointSmsConfig] config
+      # @return [nil, Aws::SNS::Client]
+      def build_client(config)
+        credentials = AwsCredentialBuilder.new(config).call
+        return if credentials.nil?
+        Aws::SNS::Client.new(
+          region: config.region,
+          retry_limit: 0,
+          credentials: credentials,
+        )
+      end
+    end
+  end
+end