PhenixID Documentation

How to configure Signing Workflow

This document describes how to configure PhenixID Signing Workflow.

PhenixID Signing Workflow, and PhenixID Signing Services, (running on Linux) can also be configured using Ansible Automation tool. Please view https://bitbucket.org/phenixidentity/ansible-signing-workflow for more information.

Audience

System administrators.

Prerequisites

- PhenixID Signing Workflow installed

- Workflow database created

Setup PhenixID Signing Services

PhenixID Signing Workflow is dependant on PhenixID Signing Services.

Setup PhenixID Signing Services PDF API using this guide.
1. Please note that PhenixID Signing Services should be installed on a separate server with own DNS-name etc.
2. Fetch these values from the PhenixID Signing Services setup:
  1. API username and password
  2. The Files service endpoint URL (if you haven't changed the default values, the endpoint value will be https://<phenixid_signing_services>/files/integration_dev )
  3. The web app endpoint URL (if you haven't changed the default values, the endpoint value will be https://<phenixid_signing_services>/files/pdf_sign )

Configure Signing Workflow

Using the sample configuration file

Open the config/ folder
Copy the file config-sample.json and name it config.json
config-sample.json will be overwritten during an upgrade!
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

You can override your main configuration file by adding more configuration files or using environment variables. The result will be a merged configuration.

This can for example be used to divide the configuration file into multiple smaller ones.

If you are using the included start.sh or start.bat script files then you can set the following environment variable called 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"

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

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

Click to copy

Override using environment variables

You can also override the configuration using environment variables.
Environment variable override has higher priority then the file base 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" } }

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

Server Logging

Server logging is controlled by the file config/log4j.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

Open config.json in a text editor
Change the publicUrl parameter to the name of the server. Example
"publicUrl": "https://signing-workflow.phenixid.net/",
Save the file.

NB!
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).

4. White list the publicURL domain as an allowedLogoutTarget on the PhenixID Signing Services config using this guide.

SQL database connection

Open config.json in a text editor
Change the database parameters in the database section:
1. url = the jdbc url string. Format: "jdbc:<sql_driver_type>://<database_ip>:<database_port>;database=workflow". Please consult JDBC documentation for details.
2. driver_class = the sql driver java class. Please consult JDBC documentation for details.
3. user = the database user userID value.
4. password = the database user password value.

In the example below, the MS SQL database named workflow is located on a database server with the ip address 10.128.22.34 on port 61466. The database user workflow_owner with password Secret8899 is used by Signing Workflow to connect to the database. The connection is also set to not validate TLS certificates (trustServerCertificate=true).

 "database": {
    "url": "jdbc:sqlserver://10.128.22.34:61466;database=workflow;trustServerCertificate=true",
    "driver_class": "com.microsoft.sqlserver.jdbc.SQLServerDriver",
    "user": "workflow_owner",
    "password": "Secret8899",
    "maxPoolSize": "3",
    "changelog": "db_migrations/changelog.master.xml",
    "migrations_enabled": true
  }

3. Save the file

4. Start the PhenixID Signing Workflow service.

5. Check logs/server.log for database-related issues/errors.
(Other, subsequent errors can be ignored).

6. If no database-related issues/errors were found, connect to the database server and verify that new tables have been created in the workflow database.

Create temporary PDF file storage

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

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

Example:

"fileDirectory": "files",

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.

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

8. Save the file.

Add PhenixID Signing Services connection info

Open config.json in a text editor.
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.phenixid.net/pdf_sign/"
  },
  "fileService": {
    "url": "https://signing-service.phenixid.net/files/integration_dev",
    "username": "workflow",
    "password": "secret7zce"
  }

3. Save the file.

SAML Federation

Signing Workflow always rely 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.

Configure Signing Workflow as a SAML Service Provider

Open config.json in a text editor.
Change these parameters:
1. saml->assertionConsumerServiceUrl = The Assertion Consumer URL (POST) of this SAML SP. Set to <signing_workflow_public_url>/auth/saml
2. 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",
    "defaultLocale": "sv",

3. Save the file.

Create Signing Workflow SAML Service Provider metadata

Open a text editor.
Copy the xml template text below and paste it into the text editor.
Replace YOUR_ENTITY_ID with the issuerId value set in previous step
Replace YOUR_ASSERTION_URL with the assertionConsumerServiceUrl value set in previous step
Open the file refered to in jwt->publicCertFile in a text editor
Copy the content, without the PEM tags rows (----BEGIN.... and -----END...)
Replace YOUR_CERTIFICATE with the certificate content copied.
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>

Ready 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>

SAML attribute mapping

NameID

The NameID value from the IdP must be populated with:

- A unique identifier for internal users (=users residing in customer directory(ies), such as sAMAccountName, userPrincipalName, uid (depending on the user store etc). NB! Do not use an identifier that may expose personal data, e.g. social security number.

- A unique identifier for external users (=users not residing in customer directory(ies), such as social security number

Attributes

Open config.json in a text editor.
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 errands. 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 login and see the workflow errands 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"
    },

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

Fetch the SAML Identity Provider metadata (ask IdP admin if unknown)
Open the SAML Identity Provider metadata in a text editor
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 filepath 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"
    ],
    .
  },

SMTP

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

Open config.json
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.

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>"
    }
  },

To change email look and texts, please follow the instruction here.

User search

PhenixID Signing workflow includes person search functionality. The purpose is to find the users who should sign the document in the signing workflow errand. 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 PhenixID Authentication Services (=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.

Add endpoints and attribute mappings

Configure PhenixID Signing Services (or Authentication Services) with the Person search API.
Open config.json in a texteditor
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": "city",
      "firstName": "preferredGivenName",
      "lastName": "sn"
    }
  },
  }

4. Save config.json

5. Restart the PhenixID Signing Workflow service.

Test

Browse to the PhenixID Signing Workflow url
You should be redirected to the IdP
Authenticate
You should be redirected to Signing Workflow and be logged-in
Create signing errand (if you cant find that option you miss the correct role)
Assign one internal and one external signer to the errand.
Once created, verify that both users received a notification and is able to log in and see the errand.
The respective user should now sign the doc, verify that it works like expected
When both users signed, verify that you can download the result (the doc with two signatures)

PhenixID Documentation

How to configure Signing Workflow

Audience

Prerequisites

Setup PhenixID Signing Services

Configure Signing Workflow

Override configuration

Override using environment variables

Server Logging

Web server and SSL termination

SQL database connection

Create temporary PDF file storage

Add token signing certificate

Add PhenixID Signing Services connection info

SAML Federation

Configure Signing Workflow as a SAML Service Provider

Create Signing Workflow SAML Service Provider metadata

SAML attribute mapping

NameID

Attributes

Distribute info to the SAML Identity Provider administrator

Establish trust to SAML Identity Provider

SMTP

User search

Add endpoints and attribute mappings

Test

Topics

Other Resources

PhenixID Authentication Services

PhenixID Signing Services

PhenixID Password Self Service

PhenixID Signing Workflow