feat(#479): Send returnUrl to BankID as part of the auth/sign/payment requests

* feat(#479): Send returnUrl to BankID as part of the auth/sign/payment requests

* Use existing logic in active login to provide the correct return url depending on device, os, etc. This logic is currently used when setting the return url as part of the auto launch url and should be applied when sending the return url to bankid as part of the auth, sign or payment request as well.

---------

Co-authored-by: Elin Fokine <ElinO@activesolution.se>

Author: Zonnex

src/ActiveLogin.Authentication.BankId.Api/BankIdAppApiClientExtensions.cs

@@ -6,7 +6,7 @@ namespace ActiveLogin.Authentication.BankId.Api;
 /// Extensions to enable easier access to common api scenarios.
 /// </summary>
 public static class BankIdAppApiClientExtensions
-{
+{
     /// <summary></summary>
     /// <param name="appApiClient">The <see cref="IBankIdAppApiClient"/> instance.</param>
     /// <param name="endUserIp">
@@ -27,21 +27,26 @@ public static class BankIdAppApiClientExtensions
     /// <param name="userVisibleDataFormat">
     /// If present, and set to "simpleMarkdownV1", this parameter indicates that userVisibleData holds formatting characters which, if used correctly, will make the text displayed with the user nicer to look at.
     /// For further information of formatting options, please study the document Guidelines for Formatted Text.
+    /// </param>
+    /// <param name="returnUrl">
+    /// If present the user will be redirected to this URL when the order is completed. Any return URL provided in the start URL when the BankID app was launched will be ignored.
     /// </param>
     public static Task<AuthResponse> AuthAsync(
         this IBankIdAppApiClient appApiClient,
         string endUserIp,
         Requirement? requirement = null,
         string? userVisibleData = null,
         byte[]? userNonVisibleData = null,
-        string? userVisibleDataFormat = null)
+        string? userVisibleDataFormat = null,
+        string? returnUrl = null)
     {
         return appApiClient.AuthAsync(new(
             endUserIp,
             userVisibleData: userVisibleData,
             userNonVisibleData: userNonVisibleData,
             requirement: requirement,
-            userVisibleDataFormat: userVisibleDataFormat));
+            userVisibleDataFormat: userVisibleDataFormat,
+            returnUrl: returnUrl));
     }
 
     /// <summary>
@@ -81,8 +86,8 @@ public static Task<AuthResponse> AuthAsync(this IBankIdAppApiClient appApiClient
     public static Task<SignResponse> SignAsync(this IBankIdAppApiClient appApiClient, string endUserIp, string userVisibleData)
     {
         return appApiClient.SignAsync(new SignRequest(endUserIp, userVisibleData));
-    }
-
+    }
+
     /// <summary>
     /// Initiates an authentication order. Use the collect method to query the status of the order.
     /// </summary>
@@ -100,14 +105,18 @@ public static Task<SignResponse> SignAsync(this IBankIdAppApiClient appApiClient
     /// </param>
     /// <param name="userNonVisibleData">
     /// Data not displayed to the user.
+    /// </param>
+    /// <param name="returnUrl">
+    /// If present the user will be redirected to this URL when the order is completed. Any return URL provided in the start URL when the BankID app was launched will be ignored.
     /// </param>
     /// <returns>If the request is successful, the OrderRef and AutoStartToken is returned.</returns>
-    public static Task<SignResponse> SignAsync(this IBankIdAppApiClient appApiClient, string endUserIp, string userVisibleData, byte[] userNonVisibleData)
+    public static Task<SignResponse> SignAsync(this IBankIdAppApiClient appApiClient, string endUserIp, string userVisibleData, byte[] userNonVisibleData, string? returnUrl = null)
     {
         return appApiClient.SignAsync(new SignRequest(
             endUserIp,
             userVisibleData,
-            userNonVisibleData: userNonVisibleData));
+            userNonVisibleData: userNonVisibleData,
+            returnUrl: returnUrl));
     }
 
     /// <summary></summary>

src/ActiveLogin.Authentication.BankId.Api/Models/Request.cs

@@ -47,7 +47,7 @@ public Request(string endUserIp, string userVisibleData, byte[] userNonVisibleDa
     /// The user IP address as seen by RP. IPv4 and IPv6 is allowed.
     /// Note the importance of using the correct IP address.It must be the IP address representing the user agent (the end user device) as seen by the RP.
     /// If there is a proxy for inbound traffic, special considerations may need to be taken to get the correct address.
-    /// 
+    ///
     /// In some use cases the IP address is not available, for instance for voice based services.
     /// In this case, the internal representation of those systems IP address is ok to use.
     /// </param>
@@ -71,7 +71,7 @@ public Request(string endUserIp, string userVisibleData, string userVisibleDataF
     /// The user IP address as seen by RP. IPv4 and IPv6 is allowed.
     /// Note the importance of using the correct IP address.It must be the IP address representing the user agent (the end user device) as seen by the RP.
     /// If there is a proxy for inbound traffic, special considerations may need to be taken to get the correct address.
-    /// 
+    ///
     /// In some use cases the IP address is not available, for instance for voice based services.
     /// In this case, the internal representation of those systems IP address is ok to use.
     /// </param>
@@ -93,7 +93,7 @@ public Request(string endUserIp, string userVisibleData, byte[]? userNonVisibleD
     /// The user IP address as seen by RP. IPv4 and IPv6 is allowed.
     /// Note the importance of using the correct IP address.It must be the IP address representing the user agent (the end user device) as seen by the RP.
     /// If there is a proxy for inbound traffic, special considerations may need to be taken to get the correct address.
-    /// 
+    ///
     /// In some use cases the IP address is not available, for instance for voice based services.
     /// In this case, the internal representation of those systems IP address is ok to use.
     /// </param>
@@ -141,7 +141,7 @@ public Request(string endUserIp, string? userVisibleData, byte[]? userNonVisible
         App = app;
 
         RiskFlags = riskFlags;
-        UserVisibleTransaction = userVisibleTransaction; 
+        UserVisibleTransaction = userVisibleTransaction;
     }
 
     /// <summary>
@@ -189,7 +189,15 @@ public Request(string endUserIp, string? userVisibleData, byte[]? userNonVisible
     public string? UserNonVisibleData { get; }
 
     /// <summary>
-    /// Orders started on the same device (started with autostart token) will call this URL when the order is completed, ignoring any return URL provided in the start URL when the BankID app was launched.
+    /// Orders started on the same device (started with autostart token) will call this URL when the order is completed,
+    /// ignoring any return URL provided in the start URL when the BankID app was launched.
+    ///
+    /// If the user has a version of the BankID app that does not support getting the returnUrl from the server,
+    /// the order will be cancelled and the user will be asked to update their app.
+    /// 
+    /// The return URL you provide should include a nonce to the session.
+    /// When the user returns to your app or web page, your service should verify that
+    /// the device receiving the returnUrl is the same device that started the order.
     /// </summary>
     [JsonPropertyName("returnUrl"), JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
     public string? ReturnUrl { get; set; }

src/ActiveLogin.Authentication.BankId.Api/Models/SignRequest.cs

@@ -10,7 +10,7 @@ public class SignRequest : Request
     /// The user IP address as seen by RP. IPv4 and IPv6 is allowed.
     /// Note the importance of using the correct IP address.It must be the IP address representing the user agent (the end user device) as seen by the RP.
     /// If there is a proxy for inbound traffic, special considerations may need to be taken to get the correct address.
-    /// 
+    ///
     /// In some use cases the IP address is not available, for instance for voice based services.
     /// In this case, the internal representation of those systems IP address is ok to use.
     /// </param>

src/ActiveLogin.Authentication.BankId.AspNetCore/DataProtection/Serialization/BankIdUiStateSerializer.cs

@@ -80,7 +80,7 @@ protected override void Write(BinaryWriter writer, BankIdUiState model)
             writer.Write(paymentState.BankIdPaymentProperties.RiskWarning == null);
             writer.Write(paymentState.BankIdPaymentProperties.RiskWarning ?? string.Empty);
 
-            writer.Write(paymentState.BankIdPaymentProperties.RiskFlags == null); 
+            writer.Write(paymentState.BankIdPaymentProperties.RiskFlags == null);
             var riskFlagsStr = paymentState.BankIdPaymentProperties.RiskFlags != null ? string.Join(",", paymentState.BankIdPaymentProperties.RiskFlags.Select(r => r.ToString())) : string.Empty;
             writer.Write(riskFlagsStr);
 

src/ActiveLogin.Authentication.BankId.Core/Flow/BankIdFlowService.cs

@@ -69,7 +69,9 @@ IBankIdEndUserDeviceDataResolverFactory bankIdEndUserDeviceDataResolverFactory
     public async Task<BankIdFlowInitializeResult> InitializeAuth(BankIdFlowOptions flowOptions, string returnRedirectUrl)
     {
         var detectedUserDevice = _bankIdSupportedDeviceDetector.Detect();
-        var response = await GetAuthResponse(flowOptions, detectedUserDevice);
+        var returnUrl = await GetReturnUrl(flowOptions, returnRedirectUrl);
+
+        var response = await AuthAsync(flowOptions, detectedUserDevice, returnUrl);
 
         await _bankIdEventTrigger.TriggerAsync(new BankIdInitializeSuccessEvent(personalIdentityNumber: null, response.OrderRef, detectedUserDevice, flowOptions));
 
@@ -91,11 +93,11 @@ public async Task<BankIdFlowInitializeResult> InitializeAuth(BankIdFlowOptions f
         }
     }
 
-    private async Task<AuthResponse> GetAuthResponse(BankIdFlowOptions flowOptions, BankIdSupportedDevice detectedUserDevice)
+    private async Task<AuthResponse> AuthAsync(BankIdFlowOptions flowOptions, BankIdSupportedDevice detectedUserDevice, string? returnUrl)
     {
         try
         {
-            var request = await GetAuthRequest(flowOptions);
+            var request = await GetAuthRequest(flowOptions, returnUrl);
             return await _bankIdAppApiClient.AuthAsync(request);
         }
         catch (BankIdApiException bankIdApiException)
@@ -105,7 +107,7 @@ private async Task<AuthResponse> GetAuthResponse(BankIdFlowOptions flowOptions,
         }
     }
 
-    private async Task<AuthRequest> GetAuthRequest(BankIdFlowOptions flowOptions)
+    private async Task<AuthRequest> GetAuthRequest(BankIdFlowOptions flowOptions, string? returnUrl)
     {
         var endUserIp = _bankIdEndUserIpResolver.GetEndUserIp();
         var resolvedRequirements = await _bankIdAuthRequestRequirementsResolver.GetRequirementsAsync();
@@ -130,7 +132,7 @@ private async Task<AuthRequest> GetAuthRequest(BankIdFlowOptions flowOptions)
             userVisibleData: userData.UserVisibleData,
             userNonVisibleData: userData.UserNonVisibleData,
             userVisibleDataFormat: userData.UserVisibleDataFormat,
-            returnUrl: null,
+            returnUrl: returnUrl,
             returnRisk: returnRisk,
             web: webDeviceData,
             app: appDeviceData
@@ -140,7 +142,9 @@ private async Task<AuthRequest> GetAuthRequest(BankIdFlowOptions flowOptions)
     public async Task<BankIdFlowInitializeResult> InitializeSign(BankIdFlowOptions flowOptions, BankIdSignData bankIdSignData, string returnRedirectUrl)
     {
         var detectedUserDevice = _bankIdSupportedDeviceDetector.Detect();
-        var response = await GetSignResponse(flowOptions, bankIdSignData, detectedUserDevice);
+        var returnUrl = await GetReturnUrl(flowOptions, returnRedirectUrl);
+
+        var response = await SignAsync(flowOptions, bankIdSignData, detectedUserDevice, returnUrl);
 
         await _bankIdEventTrigger.TriggerAsync(new BankIdInitializeSuccessEvent(personalIdentityNumber: null, response.OrderRef, detectedUserDevice, flowOptions));
 
@@ -162,11 +166,11 @@ public async Task<BankIdFlowInitializeResult> InitializeSign(BankIdFlowOptions f
         }
     }
 
-    private async Task<SignResponse> GetSignResponse(BankIdFlowOptions flowOptions, BankIdSignData bankIdSignData, BankIdSupportedDevice detectedUserDevice)
+    private async Task<SignResponse> SignAsync(BankIdFlowOptions flowOptions, BankIdSignData bankIdSignData, BankIdSupportedDevice detectedUserDevice, string? returnUrl)
     {
         try
         {
-            var request = GetSignRequest(flowOptions, bankIdSignData);
+            var request = GetSignRequest(flowOptions, bankIdSignData, returnUrl);
             return await _bankIdAppApiClient.SignAsync(request);
         }
         catch (BankIdApiException bankIdApiException)
@@ -176,11 +180,13 @@ private async Task<SignResponse> GetSignResponse(BankIdFlowOptions flowOptions,
         }
     }
 
-    private SignRequest GetSignRequest(BankIdFlowOptions flowOptions, BankIdSignData bankIdSignData)
+    private SignRequest GetSignRequest(BankIdFlowOptions flowOptions, BankIdSignData bankIdSignData, string? returnUrl)
     {
         var endUserIp = _bankIdEndUserIpResolver.GetEndUserIp();
 
-        var certificatePolicies = bankIdSignData.CertificatePolicies.Any() ? bankIdSignData.CertificatePolicies: flowOptions.CertificatePolicies;
+        var certificatePolicies = bankIdSignData.CertificatePolicies.Any()
+            ? bankIdSignData.CertificatePolicies
+            : flowOptions.CertificatePolicies;
         var resolvedCertificatePolicies = GetResolvedCertificatePolicies(certificatePolicies, flowOptions.SameDevice);
 
         var requiredPersonalIdentityNumber = bankIdSignData.RequiredPersonalIdentityNumber ?? flowOptions.RequiredPersonalIdentityNumber;
@@ -199,7 +205,7 @@ private SignRequest GetSignRequest(BankIdFlowOptions flowOptions, BankIdSignData
             userNonVisibleData: bankIdSignData.UserNonVisibleData,
             userVisibleDataFormat: bankIdSignData.UserVisibleDataFormat,
             requirement: requestRequirement,
-            returnUrl: null,
+            returnUrl: returnUrl,
             returnRisk: returnRisk,
             web: webDeviceData,
             app: appDeviceData
@@ -221,7 +227,9 @@ private SignRequest GetSignRequest(BankIdFlowOptions flowOptions, BankIdSignData
     public async Task<BankIdFlowInitializeResult> InitializePayment(BankIdFlowOptions flowOptions, BankIdPaymentData bankIdPaymentData, string returnRedirectUrl)
     {
         var detectedUserDevice = _bankIdSupportedDeviceDetector.Detect();
-        var response = await GetPaymentResponse(flowOptions, bankIdPaymentData, detectedUserDevice);
+        var returnUrl = await GetReturnUrl(flowOptions, returnRedirectUrl);
+
+        var response = await PaymentAsync(flowOptions, bankIdPaymentData, detectedUserDevice, returnUrl);
 
         await _bankIdEventTrigger.TriggerAsync(new BankIdInitializeSuccessEvent(personalIdentityNumber: null, response.OrderRef, detectedUserDevice, flowOptions));
 
@@ -243,11 +251,11 @@ public async Task<BankIdFlowInitializeResult> InitializePayment(BankIdFlowOption
         }
     }
 
-    private async Task<PaymentResponse> GetPaymentResponse(BankIdFlowOptions flowOptions, BankIdPaymentData bankIdPaymentData, BankIdSupportedDevice detectedUserDevice)
+    private async Task<PaymentResponse> PaymentAsync(BankIdFlowOptions flowOptions, BankIdPaymentData bankIdPaymentData, BankIdSupportedDevice detectedUserDevice, string? returnUrl)
     {
         try
         {
-            var request = GetPaymentRequest(flowOptions, bankIdPaymentData);
+            var request = GetPaymentRequest(flowOptions, bankIdPaymentData, returnUrl);
             return await _bankIdAppApiClient.PaymentAsync(request);
         }
         catch (BankIdApiException bankIdApiException)
@@ -257,7 +265,7 @@ private async Task<PaymentResponse> GetPaymentResponse(BankIdFlowOptions flowOpt
         }
     }
 
-    private PaymentRequest GetPaymentRequest(BankIdFlowOptions flowOptions, BankIdPaymentData bankIdPaymentData)
+    private PaymentRequest GetPaymentRequest(BankIdFlowOptions flowOptions, BankIdPaymentData bankIdPaymentData, string? returnUrl)
     {
         var endUserIp = _bankIdEndUserIpResolver.GetEndUserIp();
 
@@ -291,7 +299,7 @@ private PaymentRequest GetPaymentRequest(BankIdFlowOptions flowOptions, BankIdPa
             userVisibleDataFormat: bankIdPaymentData.UserVisibleDataFormat,
             requirement: requestRequirement,
             returnRisk: returnRisk,
-            returnUrl: null,
+            returnUrl: returnUrl,
             riskFlags: riskFlags,
             app: appDeviceData,
             web: webDeviceData
@@ -323,6 +331,15 @@ private PaymentRequest GetPaymentRequest(BankIdFlowOptions flowOptions, BankIdPa
         return riskFlags.Select(x => x.ToString()).ToList();
     }
 
+    private async Task<string?> GetReturnUrl(BankIdFlowOptions flowOptions, string returnRedirectUrl)
+    {
+        if (!flowOptions.SameDevice) return null;
+
+        var launchUrlRequest = new LaunchUrlRequest(returnRedirectUrl, "");
+        var launchInfo = await _bankIdLauncher.GetLaunchInfoAsync(launchUrlRequest);
+
+        return launchInfo.ReturnUrl;
+    }
 
     private Task<BankIdLaunchInfo> GetBankIdLaunchInfo(string redirectUrl, string autoStartToken)
     {

src/ActiveLogin.Authentication.BankId.Core/Launcher/BankIdDevelopmentLauncher.cs

@@ -3,10 +3,11 @@ namespace ActiveLogin.Authentication.BankId.Core.Launcher;
 internal class BankIdDevelopmentLauncher : IBankIdLauncher
 {
     private const string DevelopmentLaunchUrl = "#";
+    private const string DevelopmentReturnUrl = "";
 
     public Task<BankIdLaunchInfo> GetLaunchInfoAsync(LaunchUrlRequest request)
     {
         // Always stay on same page, without reloading, in simulated mode
-        return Task.FromResult(new BankIdLaunchInfo(DevelopmentLaunchUrl, false, false));
+        return Task.FromResult(new BankIdLaunchInfo(DevelopmentLaunchUrl, false, false, DevelopmentReturnUrl));
     }
 }