LG-15121 Add a post_idv_followup_url configuration to service provi…

…ders (#11591)

We have been working through issues with a service provider who has observed that users do not return to their SP after entering their mailed code or passing fraud review. We identified an opportunity to provide users with a direct link back to the SP to re-initiate their session when they complete out-of-band proofing.

This commit adds a `post_idv_followup_url` to the SP configuration for this purpose. This URL is used in the `account_verified` email if it is present. In future changes we plan to add a CTA after the user enters a mailed code and to the account page if the user has not connected their account.

This change should not impact SPs that do not have a `post_idv_followup_url` configured.

[skip changelog]

app/controllers/idv/account_verified_cta_visited_controller.rb

@@ -22,7 +22,8 @@ def redirect_url
       if issuer.blank?
         root_url
       else
-        sp_return_url_resolver&.return_to_sp_url
+        sp_return_url_resolver&.post_idv_follow_up_url ||
+          sp_return_url_resolver&.return_to_sp_url
       end
     end
 

app/presenters/idv/account_verified_email_presenter.rb

@@ -16,7 +16,7 @@ def service_provider
     end
 
     def show_cta?
-      !service_provider || service_provider_homepage_url.present?
+      !service_provider || service_provider_post_idv_follow_up_url.present?
     end
 
     def sign_in_url
@@ -32,11 +32,11 @@ def sign_in_url
     end
 
     def displayed_sign_in_url
-      service_provider_homepage_url || root_url
+      service_provider_post_idv_follow_up_url || root_url
     end
 
-    def service_provider_homepage_url
-      sp_return_url_resolver.homepage_url if service_provider
+    def service_provider_post_idv_follow_up_url
+      sp_return_url_resolver.post_idv_follow_up_url if service_provider
     end
 
     def sp_name

app/services/sp_return_url_resolver.rb

@@ -24,6 +24,10 @@ def homepage_url
     service_provider.return_to_sp_url
   end
 
+  def post_idv_follow_up_url
+    service_provider.post_idv_follow_up_url || homepage_url
+  end
+
   private
 
   def inferred_redirect_url

config/service_providers.localdev.yml

@@ -217,6 +217,7 @@ test:
     assertion_consumer_logout_service_url: ''
     ial: 2
     allow_prompt_login: true
+    post_idv_follow_up_url: http://localhost/post_idv_follow_up_url
 
   'urn:gov:gsa:openidconnect:sp:server_ial1':
     agency_id: 2

db/primary_migrate/20241203163014_add_post_idv_follow_up_url_to_service_provider.rb

@@ -0,0 +1,5 @@
+class AddPostIdvFollowUpUrlToServiceProvider < ActiveRecord::Migration[7.2]
+  def change
+    add_column :service_providers, :post_idv_follow_up_url, :string, comment: 'sensitive=false'
+  end
+end

db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[7.2].define(version: 2024_11_15_215510) do
+ActiveRecord::Schema[7.2].define(version: 2024_12_03_163014) do
   # These are extensions that must be enabled in order to support this database
   enable_extension "citext"
   enable_extension "pg_stat_statements"
@@ -551,6 +551,7 @@
     t.boolean "use_legacy_name_id_behavior", default: false, comment: "sensitive=false"
     t.boolean "irs_attempts_api_enabled", comment: "sensitive=false"
     t.boolean "in_person_proofing_enabled", default: false, comment: "sensitive=false"
+    t.string "post_idv_follow_up_url", comment: "sensitive=false"
     t.index ["issuer"], name: "index_service_providers_on_issuer", unique: true
   end
 

spec/controllers/idv/account_verified_cta_visited_controller_spec.rb

@@ -15,20 +15,20 @@
   describe 'GET #show' do
     subject(:action) { get :show, params: }
 
-    context 'issuer provided and return_to_sp_url present' do
+    context 'issuer provided and post_idv_follow_up_url present' do
       let(:service_provider) do
         build(
           :service_provider,
           issuer: 'urn:my:awesome:issuer',
-          return_to_sp_url: 'https://some-sp.com',
+          post_idv_follow_up_url: 'https://some-sp.com',
         )
       end
 
       let(:params) do
         { issuer: 'urn:my:awesome:issuer', campaign_id: '123234234' }
       end
 
-      it 'redirects to the service provider home page and logs event' do
+      it 'redirects to the service provider follow_up url and logs event' do
         action
 
         aggregate_failures 'verify response' do
@@ -50,6 +50,7 @@
           :service_provider,
           issuer: 'urn:my:awesome:issuer',
           return_to_sp_url: nil,
+          post_idv_follow_up_url: nil,
           acs_url: nil,
           redirect_uris: nil,
         )

spec/presenters/idv/account_verified_email_presenter_spec.rb

@@ -57,11 +57,12 @@
   end
 
   context 'where there is a service provider' do
-    context 'when the service provider has no return URL' do
+    context 'when the service provider has no post-IdV follow-up URL' do
       let(:service_provider) do
         create(
           :service_provider,
           issuer: 'urn:my:awesome:sp',
+          post_idv_follow_up_url: nil,
           return_to_sp_url: nil,
           friendly_name: 'My Awesome SP',
         )
@@ -101,12 +102,12 @@
       end
     end
 
-    context 'when the service provider does have a return URL' do
+    context 'when the service provider does have a post-IdV follow-up URL' do
       let(:service_provider) do
         create(
           :service_provider,
           issuer: 'urn:my:awesome:sp',
-          return_to_sp_url: 'https://www.mysp.com',
+          post_idv_follow_up_url: 'https://www.mysp.com',
           friendly_name: 'My Awesome SP',
         )
       end

spec/services/sp_return_url_resolver_spec.rb

@@ -140,4 +140,35 @@
       end
     end
   end
+
+  describe '#post_idv_follow_up_url' do
+    let(:return_to_sp_url) { nil }
+    let(:sp_post_idv_follow_up_url) { nil }
+    let(:sp) do
+      build(
+        :service_provider,
+        return_to_sp_url: return_to_sp_url,
+        post_idv_follow_up_url: sp_post_idv_follow_up_url,
+      )
+    end
+    let(:instance) { described_class.new(service_provider: sp) }
+    subject(:post_idv_follow_up_url) { instance.post_idv_follow_up_url }
+
+    context 'with not homepage url or follow_up url configured' do
+      it { expect(post_idv_follow_up_url).to be_nil }
+    end
+
+    context 'with a homepage url configured' do
+      let(:return_to_sp_url) { 'https://sp.gov/return_to_sp' }
+
+      it { expect(post_idv_follow_up_url).to eq(return_to_sp_url) }
+    end
+
+    context 'with a follow_up url configured' do
+      let(:return_to_sp_url) { 'https://sp.gov/return_to_sp' }
+      let(:sp_post_idv_follow_up_url) { 'https://sp.gov/follow_up' }
+
+      it { expect(post_idv_follow_up_url).to eq(sp_post_idv_follow_up_url) }
+    end
+  end
 end