Configure your application

Setup config files

  1. Open the config/ folder
  2. Copy the file config-sample.json and name it config.json. config-sample.json will be overwritten during an upgrade!
  3. Make your changes inside config.json

A complete reference guide, describing all configuration parameters in the config.json file, can be found at Configuration reference.

Override configuration

Override using config files

You can override your main configuration file by adding more configuration files, or by using environment variables. The result will be a merged configuration. This can be used for dividing and grouping configuration file into business units, such as dev and prod. If you are using the included start.sh or start.bat script files, you can set the environment variable SWF_CONFIG_JSON_FILES to specify a space-separated list of config files. The order of the files dictates the order of overriding. Files to the right have higher priority.

For example, using a file called main-config.json as a base and production.json as an override:

SWF_CONFIG_JSON_FILES="config/main-config.json config/production.json"
Click to copy

For example, the production.json file could contain only the following override that changes the settings for sending e-mail:

{
  "smtp": {
    "client": {
      "hostname": "production.mail.com",
      "login": "REQUIRED",
      "port": 587,
      "ssl": true,
      "username": "myuser"
    },
    "enabled": true,
  }
}
Click to copy

Override using environment variables

You can also override the configuration using environment variables. Environment variable override has higher priority than the file-based configurations.

For example, if you want to set/change the password for the smtp configuration, you can create an environment variable called smtp (case-sensitive) with the JSON string { "client": { "password": "foo" } }

Example 

smtp={ "client": { "password": "foo" } }
Click to copy

You can only use a root element from the configuration as an environment variable name.

Configure logging

Server logging is controlled by the file config/log4j2.xml. If this is a completely new installation, the file config/log4j2_template.xml should first be copied to config/log4j2.xml. The config/log4j2_template.xml contains a typical setup that should work as is. For extended configuration of log4j2 please see the documentation.

Web server and SSL termination

  1. Open config.json in a text editor
  2. Change the publicUrl parameter to the name of the server. Example:
"publicUrl": "https://signing-workflow.com/"
Click to copy

     3. Save the file.
     4. Whitelist the publicURL domain as an `allowedLogoutTarget` on the Signing Services config using this guide.
 

Important!

The Signing Workflow application server binds to port 8080 (can be changed by config parameter). SSL termination should be performed by external component, such as load balancer or reverse proxy. The load balancer / reverse proxy should proxy all the traffic to the backend Signing Workflow application server (on port 8080 by default).

Creating PDF file storage

PDF documents that are part of an ongoing workflow are stored in a folder on disk. Follow these steps to create this folder. Please adjust to suit your needs.

  1. Create a folder in the Signing Workflow root folder called files.
  2. Open config.json in a text editor.
  3. Point to the newly created folder by setting the fileDirectory parameter. This value can be relative (from the Signing Workflow root folder) or absolute. Default is files in the project root folder.
  4. Save config.json.

Example:

"fileDirectory": "files",
Click to copy

Add token signing certificate

The Signing Workflow application will sign tokens:

  • The JWT token for the Signing Services integration (Signing Workflow is the API client)
  • The SAML authnRequest for the SAML integration  (Signing Workflow is the SAML SP)

To be able to sign tokens, Signing Workflow needs a key and a corresponding certificate.

  1. Create a key pair, CSR and certificate using a tool of your choice (such as OpenSSL, Keystore Explorer, Windows cert mmc)
  2. Export the private key in DER / PKCS8 format (encrypted with a password)
  3. Export the certificate chain in PEM format.
  4. Create a folder in the Signing Workflow root folder, name the folder certs
  5. Add the private key file and the certificate file to the folder.
  6. Open config.json in a text editor.
  7. Change these parameters:
  8. privateKeyFile = <Private key file path>
  9. publicCertFile = <Public cert file path>
  10. privateKeyFilePassword = <Password to the private key file>

Example:

"privateKeyFile": "C:/PhenixID/SigningWorkflow/certs/token_signer.pkcs8",
"publicCertFile": "C:/PhenixID/SigningWorkflow/certs/token_signer.cer",
"privateKeyFilePassword" : "xyxFsgdbee"
Click to copy

     11. Save the file.

Add Signing Services connection info

  1. Open config.json in a text editor.
  2. Change these parameters:
    1. signingService > url = Set to previously fetched value (Signing Services web app endpoint URL)
    2. fileService > url = Set to previously fetched value (Signing Services Files services REST endpoint URL)
    3. fileService > username = Set to previously fetched value (API username)
    4. fileService > password =  Set to previously fetched value (API password)

Example:

{
  "signingService": {
    "url": "https://signing.com/pdf_sign/"
  },
  "fileService": {
    "url": "https://signing-service.com/files/integration_dev",
    "username": "workflow",
    "password": "secret7zce"
  }
}
Click to copy

     3. Save the file.

Signing workflow includes person search functionality. The purpose is to find the users who should sign the document in the signing workflow task. User search is divided into three functions, all mandatory:

  • Search internal users – get a list of internal users to choose from, matching a specific search filter.
  • Lookup internal user – lookup a specific internal user.
  • Lookup external user – lookup a specific external user.

Signing Workflow calls out to external PAS (also known as Signing Services) over http. PAS performs the search against configured user store(s) and returns a result which Signing Workflow will parse and present / use.

Adding endpoints and attributes mapping

  1. Configure Signing Services (or Authentication Services) with the Person search API.
  2. Open config.json in a text editor
  3. Change these parameters
    1. Users > externalUserLookup = The URL of the Person search API method for external user lookup
    2. Users > internalUserLookup = The URL of the Person search API method for internal user lookup
    3. Users > internalUserSearch = The URL of the Person search API method for internal user search
    4. Users > internalUserAttributes > organization = The API method response parameter key name representing the organization
    5. Users > internalUserAttributes > userId = The API method response parameter key name representing the userId (should match with the NameID population for internal users)
    6. Users > internalUserAttributes > mail = The API method response parameter key name representing the email address
    7. Users > internalUserAttributes > firstName = The API method response parameter key name representing the given name of the user
    8. Users > internalUserAttributes > lastName = The API method response parameter key name representing the surname of the user
    9. Users > internalUserAttributes > mobile = The API method response parameter key name representing the mobile telephone number for the user
    10. Users > internalUserAttributes > department = The API method response parameter key name representing the department of the user
    11. Users > externalUserAttributes > info = The API method response parameter key name representing info about the external user
    12. Users > externalUserAttributes > mail = The API method response parameter key name representing the external user email address
    13. Users > externalUserAttributes > mobile = The API method response parameter key name representing the external user mobile phone number
    14. Users > externalUserAttributes > firstName = The API method response parameter key name representing the given name of the external user
    15. Users > externalUserAttributes > lastName = The API method response parameter key name representing the surname of the external user

Example:

"users": {
   …
   "externalUserLookup": "https://signing-service.net:7443/pipes/users/external",
   "internalUserLookup": "https://signing-service.net:7443/pipes/users/internal",
   "internalUserSearch": "https://signing-service.net:7443/pipes/users/search`,
   "internalUserAttributes": {
     "organization": "company",
     "userId": "sAMAccountName",
     "mail": "mail",
     "firstName": "givenName",
     "lastName": "sn",
     "mobile": "telephoneNumber",
     "department": "department"
   },
   "externalUserAttributes": {
     "info": "city",
     "mail": "mail",
     "mobile": "telephone",
     "firstName": "preferredGivenName",
     "lastName": "sn"
   }
}
Click to copy

     4. Save `config.json`
     5. Restart the Signing Workflow service.

Test the connections

  1. Browse to the SWF url
  2. You should be redirected to the identity provider
  3. Authenticate
  4. You should be redirected to Signing Workflow and be logged in
  5. Create a signing task (if you can't find that option, you might not have the correct role)
  6. Assign one internal and one external signer to the task.
  7. Once created, verify that both users received a notification, and that they're able to log in and see the task.
  8. Both users should now be able to sign and verify that it works as expected
  9. When both users have signed, verify that you can download the result. The file should have two signatures, one for each signer.

SAML Federation

Signing Workflow relies on external authentication and authorization, using a SAML federation. Signing Workflow will always act as a SAML Service Provider, SP, against an external SAML Identity Provider, IdP.

Configuring Signing Workflow as a SAML Service Provider

  1. Open config.json in a text editor.
  2. Change these parameters:
  • Saml > assertionConsumerServiceUrl = The Assertion Consumer URL (POST) of this SAML SP. Set to <signing_workflow_public_url>/auth/saml
  • saml > issuerId = The entityID of this SAML SP. Set to `<signing_workflow_public_url>/saml/sp`

Example:

"saml": {
    "postSsoUrl": "https://idp.phenixid.net/saml/authenticate/idp",
    "assertionConsumerServiceUrl": "https://signing-workflow.phenixid.net/auth/saml",
    "issuerId": "https://signing-workflow.phenixid.net/saml/sp",
}
Click to copy

     3. Save the file.

Create Signing Workflow SAML Service Provider metadata

  1. Open a text editor.
  2. Copy the xml template text below and paste it into the text editor.
  3. Replace `YOUR_ENTITY_ID` with the issuerId value set in previous step
  4. Replace YOUR_ASSERTION_URL with the assertionConsumerServiceUrl value set in previous step
  5. Open the file referred to in jwt > publicCertFile in a text editor
  6. Copy the content, without the PEM tags rows (----BEGIN.... and -----END...)
  7. Replace YOUR_CERTIFICATE with the certificate content copied.
  8. Save the file as signing-workflow-sp-metadata.xml.

XML template:

<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="YOUR_ENTITY_ID">
  <md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>YOUR_CERTIFICATE</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="YOUR_ASSERTION_URL" index="1"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>
Click to copy

Real-life XML example:

<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://signing-workflow.phenixid.net/saml/sp">
  <md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIIDnTCCAoWgAwIBAgIQR0Czn5/+qq1LvP4IHzrkcTANBgkqhkiG9w0BAQsFADBVMRIwEAYKCZImiZPyLGQBGRYCc2UxGTAXBgoJkiaJk/IsZAEZFgljYW1iaW9zeXMxEzARBgoJkiaJk/IsZAEZFgNkZXYxDzANBgNVBAMTBmRldi1jYTAeFw0xNjEwMTcxMjQ4MjVaFw0yNjEwMTcxMjU4MjVaMFUxEjAQBgoJkiaJk/IsZAEZFgJzZTEZMBcGCgmSJomT8ixkARkWCWNhbWJpb3N5czETMBEGCgmSJomT8ixkARkWA2RldjEPMA0GA1UEAxMGZGV2LWNhMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmFuHm/mG/GMMIMHj2RJgFho5jZj9375TBrbKNg0phgPY6wcPR/cvMXMSwbFTs3sjoJAeW7686CnRYH94UPNCrrlgFfDx+aVcYmaIw1wvFeiZEjHV7EYw1CbE2DV0U8TX7I8kNmbalCKJdU46dSRzusyN3ZTMhh7fKmgqkjh+ssgWUWEjuLtKmFLt8AxR/ptRdaP9JVLLvYGfZZwOfSWP6+FS7YXHSCa94uo0uiIPIsY0YEyoqMhNpeiM0TmDIm2Ap0FBjnckyUA1QdfHMTTomHBEj9MdDypaXYu3pAMxLlpTOzSAm8NI6BVIsGT31fNUH8u0KuX4hwnisgvxh/kDIQIDAQABo2kwZzATBgkrBgEEAYI3FAIEBh4EAEMAQTAOBgNVHQ8BAf8EBAMCAYYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUKCZF837dqjBCGjNJC99MFpV1+AwwEAYJKwYBBAGCNxUBBAMCAQAwDQYJKoZIhvcNAQELBQADggEBAFFvC6WB+JwIATaCUTTN7SdPBfifbLgDG3fYvhh+FV31mmxjl9g8fXy/dp+dcRLePe/FZ5+YW9OCFLbUaCbaeCqh8YGyKpqgxI2EE/cxL4O6lhiK9I4ZjaI4BK7U3wgEr7MvvTTzgJtQDoeESWCwWsBectAwPS4JWPL09xyD1XzbuB8dmYej32Hk3zsCuWGzA03xqdw90HpLTGRr/BQm44+6NrMsUwyYcMMtfkIRNTHCiIv2XcZxvGfPq4pywf+bY1GcFi69C4q80L9pwrbTA6/R0R5p8ZoO5cED8xD6FCGc30waxAsdJ8fC5kd/BXpX0ybuLnCEd5bTvahD10V8ASs=</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://signing-workflow.phenixid.net/auth/saml" index="1"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>
Click to copy

SAML attribute mapping

NameID

The NameID value from the IdP must be populated with:

  • A unique identifier for internal users (i.e. users residing in customer directories), such as sAMAccountName, userPrincipalName, uid (depending on the user store).

Important!

Do not use an identifier that may expose personal data, e.g. social security number.

  • A unique identifier for external users (i.e. users not residing in customer directories), such as social security number

Attributes

  1. Open config.json in a text editor.
  2. Locate and change these parameters if needed:
    1. saml > attributes > authority = Name of the attribute containing a value defining the Signing Workflow role of the user. Signing workflow has one role which is called solicitor. Users with the solicitor role will be able to create new signing workflow tasks. This saml attribute must contain the string role:solicitor (or the configured roles > solicitor value) if the user is a solicitor. If the user is not a solicitor, the user will be able to log in and see only the workflow tasks where the user is a requested signer.
    2. saml > attributes > source = Name of the attribute containing the source value of the user. The attribute value must be set to INTERNAL (for internal users) or EXTERNAL (for external users)
    3. saml > attributes > firstName = Name of the attribute containing the given name value of the user. The given name value is only used for display purposes.
    4. saml > attributes > lastName = Name of the attribute containing the surname value of the user. The surname value is only used for display purposes.
    5. saml > attributes > mail = Name of the attribute containing the mail value of the user. The mail value is used for email notifications.

Example:

"saml": {
  …
  "attributes": {
    "authority": "role",
    "source": "source",
    "firstName": "givenName",
    "lastName": "sn",
    "mail": "mail"
  }
}
Click to copy

Distribute info to the SAML Identity Provider administrator

Distribute this info to the SAML Identity Provider administrator to establish trust:

  • signing-workflow-sp-metadata.xml
  • NameID value expected (according to the instruction above)
  • Attribute set (names and expected values according to instruction above

Establish trust to SAML Identity Provider

  1. Fetch the SAML Identity Provider metadata (ask IdP admin if unknown)
  2. Open the SAML Identity Provider metadata in a text editor
  3. Fetch these values:
    1. entityID
    2. SingleSignOnService > Binding=HTTP-Post > Location
    3. Signing certificate info.

Example:

     4. Set the fetched entityID value in saml > trustedIssuers
     5. Set the fetched SingleSignOnService > Binding=HTTP-Post > Location in saml > postSsoUrl
     6. Open a text editor and create an empty file
     7. Add this text as first line:

     -----BEGIN CERTIFICATE-----
     8. Add this text as second line:

     -----END CERTIFICATE-----
     9. Add a line between the first and second line and paste the fetched Signing certificate info.
     10. Save the file and name it samltrust.pem.
     11. Set saml > trustedCertificates to the file path of samltrust.pem
     12. Save config.json

Example:

"saml": {
    "postSsoUrl": "https://demo.phenixid.net/saml/authenticate/democ",
    …
    "trustedIssuers": [
      "https://demo.phenixid.net/saml/idp/democ"
    ],
    "trustedCertificates": [
      "C:/PhenixID/Certs/samltrust.pem"
    ],
    …
  },
Click to copy

Configuring the SAML solicitor role

The solicitor role is allowed to create new tasks and assign one or more signers. Non-solicitors are able to login to Signing Workflow. They will only see the Signing Workflow tasks where they are one of requested signers.

Finding the expected attribute name

  1. Open config.json in a text editor.
  2. Locate the saml > attributes > authority setting. The value is the expected SAML attribute name.

Example:

"saml": {
  …
  "attributes": {
    "authority": "employeetype"
Click to copy

     3. Locate the ...  (If not present, the SAML attribute value expected is role:solicitor)

Example.

"saml": { 
    …
    "roles": {
      "solicitor": "SOLICITOR"
Click to copy

Configure Identity Provider

Configure your Identity Provider based on the above name and value. Add the logic around when this attribute should be set (for example, according to group membership).

Setting up the SMTP service

An optional feature of Signing Workflow is email notifications, sent to signers and solicitors. The email contains information about the signing task and a link to the task. No sensitive data is added to the email.

  1. Open config.json
  2. Set these parameters:
    1. smtp > fromAddress = The email from address
    2. smtp > enabled = Enable SMTP true/false (string)
    3. smtp.client > hostname = SMTP hostname or IP
    4. smtp.client > port = SMTP communication port
    5. smtp.client > username = SMTP username.
    6. smtp.client > password = SMTP password.
  3. Save config.json. The configuration for the client can be extended with any of the available attributes from the Vert.x MailConfig options.

Example:

"smtp": {
    "fromAddress": "[email protected]",
    "enabled": "true",
    "client": {
      "hostname": "<hostname>",
      "port": 25,
      "starttls": "DISABLED",
      "login": "REQUIRED",
      "username": "<user>",
      "password": "<password>"
    }
  }
Click to copy

Configuring the overlay folder

Configuration files found in the resources/ folder are overwritten by new installs and upgrades. By creating the same structure
in a folder called overlay/, the upgrade process is simplified significantly. The overlay/ folder remains untouched by
upgrades and overrides (overlays) the files in the resource/ folder. The overlay/ folder is automatically created at
installation but the content is never changed. Using the overlay/ folder is totally optional and can be introduced gradually
by adding files only when needed.

Examples

By adding a file called default.json in the overlay folder, it will override the default.json in the resources/themes/ folder.

The `lang/` folder follows another overlay strategy, whereby the content is *merged* rather than overridden. This means that you can combine the contents of the resources/lang/ folder with the contents of the overlay/lang/ folder, where administrators can set the variables they want to change. The rest remains untouched.

Tags

A task can be extended with more information by using Tags.

When creating a new task, the first step is to collect basic information from the user. This is where you can add your tags
by adding additional configuration to your config.json file.

Checkbox

The most basic tag is a checkbox defined with the type  "type": "boolean"

"tags": [
  {
    "displayText": "label.tags.Archive",
    "name": "archive",
    "type": "boolean",
    "defaultValue": false,
    "description": "label.tags.description"
  }
]
Click to copy
  • displayText - the screen label. Optionally using a translation identifier.
  • name - Should be set to a unique name, and will be used when referencing the tag.
  • type -  checkbox is set to "boolean".
  • defaultValue - determines whether the checkbox is checked by default.
  • description (optional) - will set the description text as a tooltip (see picture above). Optionally using a translation identifier.

Select

Select is dropdown where the user can choose one of the preconfigured values. It will be added as an input after the three
existing inputs. Defined with the type `"type": "enum"`

"tags": [
  {
    "displayText": "label.tags.ArchiveLocation",
    "name": "ArchiveLocation",
    "type": "enum",
    "values": ["Stockholm", "Umeå", "Luleå"],
    "defaultValue": "Stockholm"
  }
]
Click to copy
  • displayText - the screen label. Optionally using a translation identifier.
  • name - should be set to a unique name and will be used when referencing the tag.
  • type -  select is set to "enum".
  • defaultValue - determines whether the checkbox is checked by default.
  • values - an array with the selectable values.
  • description - will set the description text as a tooltip but in this example it is not used.