User interaction framework for delivery

The /userInteraction framework for delivery allows the Service Provider to request additional information from the user once the service delivery process has started. If the Service Providers service requires some information from the user before starting service delivery, we recommend to use the Service Description mechanism, as it has been designed to be used in the setup phase.

For a complete look at the architecture and the order of operations have a look at our Architecture pages .

The information that is requested from the user is presented in a form to which many fields can be added. Each field defined in the request has a direct correspondence with a system UI component that will be rendered in the form shown to the user. For a better user experience grouping of related fields is a good idea although generally the forms should be kept as short as possible. Once a user is done with a form they submit it with the submit button. This means that if a field depends on input from another field they need to be in separate forms.

/userInteraction is an API operation like any other of the ones listed in the developer portal API page, for example /ccm/install. The difference is that instead of interacting with the card, the SP gets to interact with the user.

The general flow of service delivery with /userInteraction:

API

As described in the API documentation under the title Service Delivery requests, as soon as the service provider receives the service delivery request, it will be able to request a specific data from the user or in other words, a user interaction. To do that, the service provider just needs to POST a JSON formatted request to the /userInteraction endpoint, using a similar request to the following code:

{
          "fields": [
            "label": {
              "en": "English label",
              "se": "Swedish label"
            },
            "id": "any_field_id",
            "type": "edit",
            "format": "number"
            ...
          ],
          "encrypted": "false"
        }

A user interaction request is composed by an array fields. Each element of fields is described in the following table:

Fields inside a request
Name Description Type
label The text label that will appear together with the system UI component defined by the type field. Multilanguage is supported. Dictionary where the key represents language id and the value is the translated text
id The id used to identify this field String
type The type of UI control that the user will see in the Fidesmo App String
format Provides an extra information about how the UI control will be rendered or what kind of data it will support. The format is optional and if not supplied or an unknown format is used the field falls back to the default. String

And finally, this is the list of type and format supported:

Supported data type and format
Name Type Format Description
Date field date - Shows a date input to the user
Input text field edit text Shows a text input. Default if format is not specified or not supported
number Text input, accepting numbers only
Text field text - Shows a static text to the user
Check box field checkbox - Shows a checkbox with text to the user
Option field option button Set of buttons for each line of a label. If a button is pressed by the user the form is submitted. Having buttons in the form automatically hides the submit-button. Default if format is not specified or not supported
radio Set of radio buttons for each line of a label.
Payment card field paymentcard - Payment card information as number, expiration date and CVV code

Date field

Parameter String A label to show to the user above the date input
Returns String A date string formatted as YYYY-MM-DD

Input text field

Parameter String A title for the text input field to show to the user
Returns String The user input string.

Text field

Parameter String The text to show to the user

Checkbox field

Parameter String The text to show to the user next to the checkbox
Returns String "true" or "false"

Option field

Parameter String The string to show next to the radiobuttons/on the buttons. Divide the lines with \n.
Returns String The (zero-based) position of the picked radiobutton/button in the array that was provided.

Payment card

Returns JSONObject
{
                  "cardNumber": "XXXXXXXXXXXXXXXX",
                  "expiryMonth": "XX",
                  "expiryYear", "XXXX",
                  "cvv", "XXX"
                }

Result

The userInteraction request will yield an operationId and UUID. After some time (the user is filling in the required information) the service provider will receive the ID of the operation, a status code and the results. The result will be in JSON and formatted like for example:

{
          "operationId": "0276F6A6-E21C-4307-B63C-1F70D6C36045",
          "sessionId": "C4D14B40-8F1C-456C-A7E2-4069B5F8CBBC",
          "statusCode": 200,
          "fields": {
            "any_field_id": "field_string_value"
          }
        }

Encryption

It is possible to specify that the data submitted by the user travels encrypted from the mobile client to the service provider, so that sensitive data such as payment card details cannot be compromised.

Encrypted user interactions are done with a combination of symmetric and asymmetric encryption. An ephemeral AES key is generated by the client and used to encrypt the /userInteraction data. Then, this key is encrypted with the public key of the service provider. The client returns the ephemeral-key encrypted data, and the public-key encrypted ephemeral key. Upon receival, the service provider decrypts the ephemeral key with its private key, and then, with the newly decrypted ephemeral key, decrypts all the data.

To activate encryption the service provider needs to pass a public key as a certificate along with the service description:

{
          "title": "The encrypted userInteraction service",
          "description": "This is an encrypted userInteraction service.
          Keep out of reach from children.",
          ...
          "certificate": [A X.509 certificate encoded as ASN1.DER]
        }

To encrypt a /userInteraction the service provider must also set the encrypted flag to true like for example:

{
          "fields": [
            "label": {
              "en": "English label"
            },
            "id": "any_field_id",
            "type": "edit",
            "format": "number",
            ...
          ],
          "encrypted": "true"
        }

The encrypted data together with the encrypted ephemeral key will be sent back as previously described in the Result section but with the fields being encrypted and the additional field "ephemeralKey":

{
          "operationId" : "0276F6A6-E21C-4307-B63C-1F70D6C36045",
          "sessionId" : "C4D14B40-8F1C-456C-A7E2-4069B5F8CBBC",
          "statusCode": 200,
          "fields": {
            "any_field_id": [byte array in a hex form]
          },
          "ephemeralKey": [byte array in a hex form]
        }

The "ephemeralKey" is encrypted using RSA/OAEP algorithm with a SHA512 for hashing and MGF1 Padding (RSA/NONE/OAEPWithSHA512AndMGF1Padding). To obtain field data one needs to decrypt the "ephemeralKey" first and then using the obtained key to decrypt each field separately using AES/CBC algorithm with a PKCS7 padding (AES/CBC/PKCS7Padding). As initialization vector an array with 16 zero bytes can be used.

Example

Goal

Show the user a policy text plus a checkbox for accepting the very same.

Code

{
          "fields": [
            {
              "label": {
                "en": "Generic Brands collects information to provide a
                better service our users. The information we collect might
                include your name, telephone number and credit card."
              },
              "id": "my_text_field_id",
              "type": "edit",
              "format": "text"
            },
            {
              "label": {
                "en": "I accept terms and conditions"
              },
              "id": "my_text_checkbox_id",
              "type": "checkbox"
            }
          ],
          "encrypted" : "false"
        }

Result

Screen shown to the user

Returned when user checks box and presses submit

{
          "operationId" : "MOCK",
          "sessionId" : "MOCK",
          "statusCode": 200,
          "fields": {
            "my_text_field_id": "",
            "my_text_checkbox_id": "true"
          }
        }