Feature/return risk (#487)

* Implement return risk.

* Update documentation about adding risk to claims.

* fix doc spelling err

---------

Co-authored-by: Elin Fokine <ElinO@activesolution.se>
Co-authored-by: Robert Folkesson <robert.folkesson@activesolution.se>
Co-authored-by: Robert Folkesson <robert.folkesson@gmail.com>

Author: 4 people

docs/articles/bankid.md

@@ -77,7 +77,7 @@ The root CA-certificates specified in _BankID Relying Party Guidelines_ (#7 for
 It is expected that you have a basic understanding of how [ASP.NET](https://docs.microsoft.com/en-us/aspnet/core/), [ASP.NET MVC](https://docs.microsoft.com/en-us/aspnet/core/mvc/overview) and [ASP.NET Authentication](https://docs.microsoft.com/en-us/aspnet/core/security/authentication/identity) works before getting started.
 
 
-Active Login is designed to make it very easy to get started with BankID, but in the end you are responsible for making sure that you are complient with the technical guidelines and/or legal agreements.
+Active Login is designed to make it very easy to get started with BankID, but in the end you are responsible for making sure that you are compliant with the technical guidelines and/or legal agreements.
 
 Therefore, before you start using Active Login, please read the documentation relevant to your needs. This will also make sure you understand the concepts better.
 
@@ -473,6 +473,13 @@ BankId options allows you to set and override some options such as the below req
     // the transaction will be blocked. The risk indication requires that the endUserIp is correct.
     // An incorrect IP-address will result in legitimate transactions being blocked.
     options.BankIdAllowedRiskLevel = BankIdAllowedRiskLevel.Low;
+
+    // If this is set to true a risk indicator will be included in the collect response when the order completes.
+    // If a risk indicator is required for the order to complete, for example, if a risk requirement is applied,
+    // the returnRisk property is ignored, and a risk indicator is always included; otherwise a default value of
+    // false is used. The risk indication requires that the endUserIp is correct. Please note that the assessed
+    // risk will not be returned if the order was blocked, which may happen if a risk requirement is set.
+    options.BankIdReturnRisk = true;
 });
 ```
 
@@ -482,6 +489,7 @@ If you want to apply some options for all BankID schemes, you can do so by using
 .Configure(options =>
 {
     options.BankIdRequireMrtd = true;
+    options.BankIdReturnRisk = true;
 });
 ```
 
@@ -666,6 +674,22 @@ public class BankIdPinHintClaimsTransformer : IBankIdClaimsTransformer
 }
 ```
 
+#### Example: Add risk claim
+
+If the application whats to act on the evaluated risk level for the transaction it could be extracted from the completion data returned by BankID.
+
+```csharp
+public class BankIdTxnClaimsTransformer : IBankIdClaimsTransformer
+{
+    public Task TransformClaims(BankIdClaimsTransformationContext context)
+    {
+        if (context.BankIdCompletionData != null && context.BankIdCompletionData.Risk != null)
+            context.AddClaim("user_risk", context.BankIdCompletionData.Risk);
+
+        return Task.CompletedTask;
+    }
+}
+```
 
 ### Return URL for cancellation
 

src/ActiveLogin.Authentication.BankId.AspNetCore/Auth/BankIdAuthHandler.cs

@@ -163,6 +163,7 @@ protected override async Task HandleChallengeAsync(AuthenticationProperties prop
             Options.BankIdSameDevice,
             Options.BankIdRequirePinCode,
             Options.BankIdRequireMrtd,
+            Options.BankIdReturnRisk,
             BankIdHandlerHelper.GetCancelReturnUrl(properties.Items),
             Options.StateCookie.Name ?? string.Empty
         );

src/ActiveLogin.Authentication.BankId.AspNetCore/Auth/BankIdAuthOptions.cs

@@ -39,6 +39,15 @@ public class BankIdAuthOptions : RemoteAuthenticationOptions
     /// </summary>
     public BankIdAllowedRiskLevel BankIdAllowedRiskLevel { get; set; } = BankIdAllowedRiskLevel.NoRiskLevel;
 
+    /// <summary>
+    /// If this is set to true a risk indicator will be included in the collect response when the order completes.
+    /// If a risk indicator is required for the order to complete, for example, if a risk requirement is applied,
+    /// the returnRisk property is ignored, and a risk indicator is always included; otherwise a default value of
+    /// false is used. The risk indication requires that the endUserIp is correct. Please note that the assessed
+    /// risk will not be returned if the order was blocked, which may happen if a risk requirement is set.
+    /// </summary>
+    public bool BankIdReturnRisk { get; set; } = false;
+
     /// <summary>
     /// Auto launch the BankID app on the current device.
     /// </summary>

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

@@ -15,6 +15,7 @@ protected override void Write(BinaryWriter writer, BankIdUiOptions model)
         writer.Write(model.SameDevice);
         writer.Write(model.RequirePinCode);
         writer.Write(model.RequireMrtd);
+        writer.Write(model.ReturnRisk);
         writer.Write(model.CancelReturnUrl);
         writer.Write(model.StateCookieName);
     }
@@ -38,6 +39,7 @@ protected override BankIdUiOptions Read(BinaryReader reader)
             reader.ReadBoolean(),
             reader.ReadBoolean(),
             reader.ReadBoolean(),
+            reader.ReadBoolean(),
             reader.ReadString(),
             reader.ReadString()
         );

src/ActiveLogin.Authentication.BankId.AspNetCore/Models/BankIdUiOptions.cs

@@ -11,6 +11,7 @@ public BankIdUiOptions(
         bool sameDevice,
         bool requirePinCode,
         bool requireMrtd,
+        bool returnRisk,
         string cancelReturnUrl,
         string stateCookieName)
     {
@@ -19,6 +20,7 @@ public BankIdUiOptions(
         SameDevice = sameDevice;
         RequirePinCode = requirePinCode;
         RequireMrtd = requireMrtd;
+        ReturnRisk = returnRisk;
         CancelReturnUrl = cancelReturnUrl;
         StateCookieName = stateCookieName;
     }
@@ -31,6 +33,8 @@ public BankIdUiOptions(
 
     public bool RequireMrtd { get; }
 
+    public bool ReturnRisk { get; }
+
     public BankIdAllowedRiskLevel AllowedRiskLevel { get; }
 
     public string CancelReturnUrl { get; }

src/ActiveLogin.Authentication.BankId.AspNetCore/Models/BankIdUiOptionsExtensions.cs

@@ -9,6 +9,7 @@ public static class BankIdUiOptionsExtensions
         options.AllowedRiskLevel,
         options.SameDevice,
         options.RequirePinCode,
-        options.RequireMrtd
+        options.RequireMrtd,
+        options.ReturnRisk
     );
 }

src/ActiveLogin.Authentication.BankId.AspNetCore/Sign/BankIdSignOptions.cs

@@ -23,6 +23,15 @@ public class BankIdSignOptions
     /// </summary>
     public bool BankIdRequireMrtd { get; set; } = false;
 
+    /// <summary>
+    /// If this is set to true a risk indicator will be included in the collect response when the order completes.
+    /// If a risk indicator is required for the order to complete, for example, if a risk requirement is applied,
+    /// the returnRisk property is ignored, and a risk indicator is always included; otherwise a default value of
+    /// false is used. The risk indication requires that the endUserIp is correct. Please note that the assessed
+    /// risk will not be returned if the order was blocked, which may happen if a risk requirement is set.
+    /// </summary>
+    public bool BankIdReturnRisk { get; set; } = false;
+
     /// <summary>
     /// Set the acceptable risk level for the transaction. If the risk is higher than the specified level,
     /// the transaction will be blocked. The risk indication requires that the endUserIp is correct.

src/ActiveLogin.Authentication.BankId.AspNetCore/Sign/BankIdSignService.cs

@@ -67,6 +67,7 @@ public Task InitiateSignAsync(BankIdSignProperties properties, string callbackPa
             options.BankIdSameDevice,
             options.BankIdRequirePinCode,
             options.BankIdRequireMrtd,
+            options.BankIdReturnRisk,
             BankIdHandlerHelper.GetCancelReturnUrl(properties.Items),
             options.StateCookie.Name ?? string.Empty
         );

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

@@ -115,6 +115,8 @@ private async Task<AuthRequest> GetAuthRequest(BankIdFlowOptions flowOptions)
         var requirePinCode = resolvedRequirements.RequirePinCode ?? flowOptions.RequirePinCode;
         var requestRequirement = new Requirement(resolvedCertificatePolicies, resolvedRiskLevel, requirePinCode, requireMrtd, requiredPersonalIdentityNumber?.To12DigitString());
 
+        var returnRisk = flowOptions.ReturnRisk;
+
         var authRequestContext = new BankIdAuthRequestContext(endUserIp, requestRequirement);
         var userData = await _bankIdAuthUserDataResolver.GetUserDataAsync(authRequestContext);
         var (webDeviceData, appDeviceData) = GetDeviceData();
@@ -126,7 +128,7 @@ private async Task<AuthRequest> GetAuthRequest(BankIdFlowOptions flowOptions)
             userData.UserNonVisibleData,
             userData.UserVisibleDataFormat,
             returnUrl: null,
-            returnRisk: null,
+            returnRisk: returnRisk,
             web: webDeviceData,
             app: appDeviceData
         );
@@ -181,6 +183,9 @@ private SignRequest GetSignRequest(BankIdFlowOptions flowOptions, BankIdSignData
         var requireMrtd = bankIdSignData.RequireMrtd ?? flowOptions.RequireMrtd;
         var requirePinCode = bankIdSignData.RequirePinCode ?? flowOptions.RequirePinCode;
         var requestRequirement = new Requirement(resolvedCertificatePolicies, resolvedRiskLevel, requirePinCode, requireMrtd, requiredPersonalIdentityNumber?.To12DigitString());
+
+        var returnRisk = flowOptions.ReturnRisk;
+
         var (webDeviceData, appDeviceData) = GetDeviceData();
 
         return new SignRequest(
@@ -190,7 +195,7 @@ private SignRequest GetSignRequest(BankIdFlowOptions flowOptions, BankIdSignData
             userVisibleDataFormat: bankIdSignData.UserVisibleDataFormat,
             requirement: requestRequirement,
             returnUrl: null,
-            returnRisk: null,
+            returnRisk: returnRisk,
             web: webDeviceData,
             app: appDeviceData
         );

src/ActiveLogin.Authentication.BankId.Core/Models/BankIdFlowOptions.cs

@@ -12,13 +12,15 @@ public BankIdFlowOptions(
         bool sameDevice,
         bool requirePinCode,
         bool requireMrtd,
+        bool requireRisk,
         PersonalIdentityNumber? requiredPersonalIdentityNumber = null)
     {
         CertificatePolicies = certificatePolicies;
         AllowedRiskLevel = allowedRiskLevel;
         SameDevice = sameDevice;
         RequirePinCode = requirePinCode;
         RequireMrtd = requireMrtd;
+        ReturnRisk = requireRisk;
         RequiredPersonalIdentityNumber = requiredPersonalIdentityNumber;
     }
 
@@ -30,6 +32,8 @@ public BankIdFlowOptions(
 
     public bool RequireMrtd { get; }
 
+    public bool ReturnRisk {  get; }
+
     public BankIdAllowedRiskLevel AllowedRiskLevel { get; }
 
     public PersonalIdentityNumber? RequiredPersonalIdentityNumber { get; }