Analysis: Functional signing support in Altinn 3

[TheTechArch]

Description

Based on Altinn/altinn-studio#5145 and feedback from agencies it is identified that Altinn 3 needs support for functional signing

Identified Requirements

• It should be possible to sign the instance on 1 or many different process tasks
• It should be possible to define the role requirement for that task
• It should be possible to select which data to sign. Ideally down to fields in forms
• Functional signatures need to contain information about which user/party did sign data, information about which part of the data was signed
• For applications with multiple signing tasks it should be possible to configure that the signature is unique across tasks
• When signatures are added to instances we need to validate the business rules for signing. (unique signature)
• It should be possible to run custom signing task validation. Example: Call an external API to verify if a user is authorized to sign. based on some business requirement
• It should be possible to alert the signer when a new instance is ready to be signed. (how to identify the correct signer?) Notify signer about instance ready for signing app-frontend-react#965
• It should be possible to add comments about the signature
• A signer should be given access to a PDF presentation of the forms he/she is signing
• It should be possible to design a signature view for the form? (unclear if needed)
• It should be possible to configure an external signature view for binary attachments.
• It should be possible to download attachments to be signed from the signature view

Screenshots

TODO: Create signing view

Considerations

Signature documents

We need to store separate signature documents for each signature. The document needs to contain the following

• Which user or organization signed document (userId/partyId, ssn,orgno)
• The instance the signature is related to
• The task for the signing step that performed the signing
• A list of all data elements that are included in the signature and not. With room for comments
• A hash of all documents
  Example below

{
    "id" : "b80f910a-bde0-49e5-8ccf-7c9ba851eb28",
    "time" : "2018-04-05T17:31:00Z"
    "instanceguid" : "74df5b79-74cc-4731-930a-d2accde7084b",
    "signaturecomment" : "Dokumentasjonen på fradraget viser at dette er I henhold til skattelovgigning av 17. mai 1982",

    "signer" : {
      "userid" : 5,
      "partyid" : 5,
       "secondarysignerid" : "person/01038712345"
       },
    "data" : 
    [{
      "dataid":"533e302b-d5f7-44a7-a2b4-bd5fbb1ddea2",
       "md5hash": "23423424",
        "signed": true,
        "comment" : "Her er beviset"
      },
      {
      "dataid":"be7b5a28-579e-4f55-a005-55f78c9c2b99",
       "md5hash": "23423424",
        "signed" : false,
        "comment": "Her har eier gått langt for streken. Kan ikke signere på disse dokumentene"
      },
      {
      "dataid":"ba94413d-c31a-452b-9466-438cd5ed7fd2"
       "md5hash": "23423424"
      }
    ]
    "signedtask" : "sign1",
}

Signature API

Adding signature

The post API for creating a new signature needs to take in a document that references the documents that are included in the signature.

The API would need to add information about

• The user performing the signing
• Metadata about the document
• Timing
• Task information

We would need to create new APIS for signature in App

• Adding a signature (this would need to generate signature document in-app)
• Downloading signature (both app and storage)

When a signature is added the signing API needs to return if the valid amount of signatures is reached. This to

In storage, we need signature API

• To download signatures
• To list signatures for an instance

External Document Viewer

For the functionality where an external party needs to present a viewer for binary files attached to instance we need to be able to set up an external document viewer URL. This would need to take input on instanceID and dataId in URL. The windows should probably open a new window.

The document viewer would require the authentication and authorization of the signer.

If the viewer is located outside of the Altinn apps domain the viewer needs to be integrated with ID-porten. For authorization, it probably needs to get roles/rights from Altinn.

Digital signing of signature.

In Altinn 2 Altinn creates a digital signature of the signature document. There has not been indicated any need for this.

Suggest not to implement this in Altinn 3.

Process API

When NEXT is called on the process API it needs to do the following

• Verify that the number of signatures is valid
• Verify that signatures is unique
• Move instance to next task or end event

Technical Sequence diagram

Authorization

For the signature and process API, the app needs to authorize when users add signatures and pressing the next API.

• We need to define a new action that can be used in XACML. Suggestion. Use SIGN

We need to define a new policy for API for adding signature.

Read of signatures only requires rights for READ operation in XACML policy

MD5 checksum

We need to verify that MD5 checksum we add from blob can be verified externally. See here

Acceptance criteria

A signature needs to contain the following

• Information about the signer
• Time of signature
• InstanceId
• DataElementID
• Possible a list of data items included in signature with hash

Configuration

• It should be possible to define if the user can define self what data elements are signed or everything has to be signed. For this requirement, we probably need to at least define the minimum of data elements that are signed.

Specification tasks

• Development tasks are defined
• Test design / decide test need
• Signing view is designed
• Verify decision not to sign signature

Development tasks

Part 1

• Define Signature document
• Implement Signature API in App template (Create, list and delete)
• Implement support for signing Task in process processing
• Implement Signing API in Storage that enrich Signature with MD5 checksum for each dataelement

Part 2

• Implement the default signature view
• Create onEndProcessSignTask in AppBase
• Update validation service to check correct number of signature
• Update ProcessAPI top authorize correctly on signing
• Create Task implementation (requires that End user navigation between process tasks app-frontend-react#271 is implemented) and make it trigger the task implementation

Part 3

This is possible a separate issue

• Develop support for external viewer on dataelements

Definition of done

Verify that this issue meets DoD (Only for project members) before closing.

• Documentation is updated (if relevant)
  • Technical documentation (docs.altinn.studio)
  • User documentation (altinn.github.io/docs)
• QA
• Manual test is complete (if relevant)
• Automated test is implemented (if relevant)
• All tasks in this userstory are closed (i.e. remaining tasks are moved to other user stories or marked obsolete)