Account Security

The following split document Account model takes effect from Formbird versions 1.3.xxx onward.

There are three (3) Formbird documents that define a user's access and permissions to the Formbird application.

• account - generally editable by the user and used by the application to control application behaviour that a user can interact with.

• accountControl - ability to have an "admin" key against it so that it is read only to the user. It is expected that systems would be configured so that most users cannot modify this document for their own account. Accounts with access to the necessary keys would be able to modify this document.

• accountSecurity - ie. password and apiKey - to never leave the server and sent to the client.

account document

The account document contains the following:

Other attributes and fields may be added to this document, as this will be the modifiable "User Account" form that people see in the system.

accountControl document

The accountControl document contains the following attributes, which are stored here so a corresponding user cannot modify their own access without explicit permission/allowance :

Sample accountControl document

{
    "documentId": "b334a702-12ab-11e8-94b9-cbba9a646574",
    "systemHeader": {
        "templateId": "54d96f610bc006eb84369a8d",
        "systemType": "accountControl",
        "createdWith": "54d96f610bc006eb84369a8d",
        "keyIds": [
            "05D0CCF4-3CB7-4183-8E33-082D77DD949B"
        ],
        "versionId": "6c2c5542-12b7-11e8-97a6-85e4002fe04c",
        "excludeGeneralSearch": false,
        "currentVersion": true,
        "createdDate": "2018-02-16T01:19:23.797Z",
        "createdBy": "540e51dd83fb24502699c931",
        "serverUpdatedDate": "2018-02-16T01:19:23.879Z",
        "serverCreatedDate": "2018-02-16T01:19:23.879Z",
        "previousVersionId": "48e4a7e2-12b7-11e8-97a6-85e4002fe04c"
    },
    "accessKeys": [
        {
            "keyId": "543c99dd2dafa7c211b38488",
            "rights": [
                "Create",
                "Update",
                "Read"
            ]
        },
        {
            "keyId": "452dda8d6803fa98058b1236",
            "rights": [
                "Read"
            ]
        },
        {
            "keyId": "56396997d95e72dc090e09de",
            "rights": [
                "Create",
                "Update",
                "Read"
            ]
        }
    ],
    "attachKeys": [
        "0b9385c7-d73e-45a5-b9db-99f55d243807",
        "2a26394c-5c98-468d-8403-64af2033dd58"
    ],
    "verified": true,
    "accountRel": [
        {
            "documentId": "85100e92-2a6e-11e6-98b2-c32ee74e5f0f",
            "name": "User Account - johndavis@formbird.com"
        }
    ]
}

Setting Up A Public Account

1. In the Account's Control Document, make the following modifications:

   "publicAccount": true,
   "accountPublicURL": "public"
   

   • Here, "accountPublicURL" should be a unique string, such as 'public', 'crm', 'fleet', 'water', or any other identifier you prefer. Note that this is just a base path name and not an actual URL.

2. In the configuration document, under 'clientConfiguration,' add the following:

   "clientConfiguration" : {
       "publicSignupURL" : "/public/form/bc8b7260-ec59-11e8-b0a0-7786a4732180"
   

   • Replace 'public' with the "accountPublicURL" you specified in the Account's Control Document.
   • Replace 'bc8b7260-ec59-11e8-b0a0-7786a4732180' with the actual documentId of the account creation template that the public account should have access to.
   • This URL will be used as the account creation template, and users will be redirected to it when they click the 'Create An Account' link on the login page.
   • With a public account, users can access public templates without the need to log in.

Troubleshooting

• If you encounter the following error message:

  'Public login failed because the account is not public'
  

  and you've already set "publicAccount" to true in the account's control document, you may need to flush redis or clear the cache.

accountSecurity document

The accountSecurity document contains the following attributes.

Account Templates

The account, accountControl and accountSecurity documents all need to have a configured template that they are written with. These template documentIds then need be stored in the Formbird application configuration document:

These templates can be configured by the implementor. They may vary from implementation to implementation.

Generally it would be suggested that only high level users (administrators) have editing access to accountControl and accountSecurity templates.

accountRel field

The accountControl and accountSecurity templates both require a field able to provide the link to the corresponding account document.

This uses a related document construct to link to an account. The related document construct is what is saved by a sc-related-document component or similar. This is an array structure, but must be limited to one entry.

Eg:

"accountRel": [
  {
    "documentId": "85100e90-2a6e-11e6-98b2-c32ee74e5f0f",
    "name": "User Account - [johndavis@formbird.com](mailto:johndavis@formbird.com)"
  }
]

So for any template for the accountControl document, we need to have the singleSelection option set to true, eg.:

{
  "componentName": "sc-related-document",
  "label": "Account",
  "mandatory": false,
  "name": "accountRel",
  "singleSelection": true,   <<<<<< SINGLE SELECTION TRUE
  "fullWidth": false,
  "enabled": true,
  "filter": "{'query':{'bool':{'must':[{'term':{'systemHeader.systemType':'account'}}]}}}",
  "showDropDown": true
}