Trusted Central Signing Service - PhenixID Document Seal Web Application
Prerequisites
- PAS 4.1 Service installed
- Add the seal certificate (keystore) to PhenixID Authentication Server (as a Keystore)
- Get the keystore ID value of the seal certificate
- The reader of this document should have some basic knowledge about PhenixID Server.
- Changes will be made to the file phenix-store.json, so please make sure to have a backup of this file.
Add PhenixID Document Seal Web Application module
- Login to PhenixID Authentication Services - Configuration manager
- Click on the tab Advanced
- Click on the pen to the right of Modules
- Append these modules
{
"name": "com.phenixidentity~phenix-prism",
"enabled": "true",
"config": {
"base_url": "/sealapp",
"auth_redirect_url": "/sealapp/authenticate/sealapp",
"module_refs": "sealappmod",
"display_name": "PhenixID Document Seal"
},
"id": "sealapp"
},
{
"name": "com.phenixidentity~phenix-prism-signingclient",
"enabled": "false",
"config": {
"display_name": "PhenixID Document Seal",
"base_uri": "sealapp",
"signPipeID": "SealAppDocSignPipe",
"verifyPipeID": "SignAppDocVerifyPipe",
"showPipeID": "SignAppDocShowPipe"
},
"id": "sealappmod"
}
- Click Stage Changes and Commit Changes
- Click on the pen to the right of NODE_GROUPS
- Add the module "sealapp" to module_refs.
-Click Stage Changes and Commit Changes
Add LDAP Connection
- Logon to Configuration Manager
- Click on Scenarios
- Click Connectios
- Click + next to LDAP and configure your LDAP connection.
- When done, click the Advanced tab
- Expand Database Connections
- Copy the id value of the database (ldap) object created. This will be used in later steps.
Add authenticator for PhenixID Document Seal Web Application
First of all, decide which authenticator(s) to be used from this list of available authenticators for PhenixID web apps authentication.
- Click on the pen to the right of Authentication - HTTP
- Add your authenticator(s) via the step-by-steps described here.
Make sure the successURL is /sealapp/.
In this example, a simple username and password authenticator is used.
{
"alias": "sealapp",
"name": "PostUidAndPassword",
"configuration": {
"pipeID": "pipeSealAppAuth",
"successURL": "/sealapp/",
"translationKey": "login.messages.information.body.enduser",
"headingtranslationKey": "login.messages.information.header.enduser",
"title": "login.messages.information.title.enduser",
"allowLanguageChange": "true"
},
"id": "sealapp"
}
- Click Stage changes and Commit changes
- Click on the pen to the right of Pipes
- Add this pipe configuration. Change connection_ref to the id value fetched in previous step. Change base_dn and filter_template to suit your environment.
{
"id": "pipeSealAppAuth",
"valves": [
{
"name": "LDAPSearchValve",
"config": {
"connection_ref": "replacewithyourconnectionid",
"base_dn": "DC=example,DC=org",
"scope": "SUB",
"size_limit": "0",
"filter_template": "(uid={{request.username}})",
"attributes": ""
}
},
{
"name": "LDAPBindValve",
"config": {
"connection_ref": "replacewithyourconnectionid",
"password_param_name": "password"
}
}
]
}
- Click Stage changes and Commit changes
Add execution flow (pipe) to display pdf
See this chapter: Add execution flow (pipe) to display pdf
Add execution flow (pipe) for seal
- Click on the pen to the right of Pipes
- Add the pipe below. The configuration in this pipe will fetch the keystore from the config, sign the pdf and email the signed (seal) pdf to the logged-in user.
Please note that this might not suit your environment. Valves can be replaced, removed or added based on your needs. Please view the documentation to get a list of available valves.
Change these values to suit your environment:
- LDAPSearchValve: connection_ref, base_dn, filter, attributes
- AddImageToPDFValve, use this valve if you want to add a picture to the end of the PDF file. Point to the picture that should be used. The position is set with the parameter "imagelocation" and value can be northwest, northeast and so on.
NOTE: AddImageToPDFValve will generate the property "pdfupdated" as seen in the example below:
{{item.pdfupdated}}
If AddImageToPDFValve is removed from the flow, "pdfSourceData", on PADESSignValve needs to be changed to "{{item.temporary}}".
- PADESSignValve: keyStoreID (change to keystore ID to be used, see Prerequisites)
- SMTPValve: smtp_host, smtp_port, smtp_username, smtp_password.
NB! An item property named mail is expected to be returned by the pipe. In cases where the emailadress is stored on another attribute than mail in the user store, make sure to add an item property named mail containing the user email adress.
{
"id": "SealAppDocSignPipe",
"description": "Sign document",
"valves": [
{
"name": "LDAPSearchValve",
"config": {
"connection_ref": "replacewithyourconnectionid",
"base_dn": "DC=example,DC=org",
"scope": "SUB",
"size_limit": "0",
"filter_template": "uid={{request.userid}}",
"attributes": "givenName,sn,mail,displayName"
}
},
{
"name": "SessionLoadValve",
"config": {
"id": "{{request.session_id}}"
}
},
{
"name": "PropertyAddValve",
"config": {
"name": "b64",
"value": "{{session.pdf_data}}"
}
},
{
"name": "PropertyAddValve",
"config": {
"name": "signerID",
"value": "SEAL"
}
},
{
"name": "PropertyAddValve",
"config": {
"name": "filename",
"value": "{{session.pdf_filename}}"
}
},
{
"name": "PropertyAddValve",
"config": {
"name": "Content-Type",
"value": "{{session.pdf_contentType}}"
}
},
{
"name": "PropertyBase64DecoderValve",
"config": {
"source": "b64",
"dest": "temporary"
}
},
{
"name": "AddImageToPDFValve",
"enabled": "true",
"config": {
"pathToImage": "C:/Program Files/PhenixID/Server/sign_image/PhenixID-overlay.png",
"pdfSource": "{{item.temporary}}",
"imagelocation": "northwest"
}
},
{
"name": "PADESSignValve",
"enabled": "true",
"config": {
"keyStoreID": "PhenixID_Demo_SEAL.p12",
"pdfSourceData": "{{item.pdfupdated}}",
"pdfTarget": "document"
}
},
{
"name": "ScriptEvalValve",
"config": {
"mime_type": "application/javascript",
"script": "var array = flow.items().get(0).getPropertyValue('filename').split('.');var fileExt = array.pop();var fileName = array.join('.');flow.items().get(0).replaceProperty('filename', fileName);flow.items().get(0).replaceProperty('filext', fileExt);"
}
},
{
"name": "PropertyRemoveValve",
"config": {
"name": "b64"
}
},
{
"name": "PropertyAddValve",
"config": {
"name": "filename_to_attach",
"value": "sealed_{{item.filename}}.pdf"
}
},
{
"name": "SMTPValve",
"config": {
"userid_param_name": "userid",
"smtp_username": "[email protected]",
"smtp_password": "{enc}xxxxxxxxxxxxxxxxxxxxxxxxxxx",
"mail_param_name": "{{item.mail}}",
"attachment_param_name": "document",
"attachment_name_param_name": "filename_to_attach",
"message_subject": "Your signed document attached",
"message_body": "Signing procedure completed! Please find the signed document attached!"
}
},
{
"name":"EventValve",
"config":{
"event_key":"EVT_000052",
"parameters":[
{
"parameter":"duser",
"value":"{{item.signerID}}"
},
{
"parameter":"msg",
"value":"Successfully signed"
},
{
"parameter":"phenixIDIdentifier",
"value":"SIGN"
},
{
"parameter":"proto",
"value":"PADES"
}
]
}
}
]
}
- Click Stage changes and Commit changes
Add execution flows (pipe) for verify
- Create a jks trust store file
- Add all the CAs you trust to issue certificates to sign PDFs
- Place the jks file in a folder (example: C:/Program Files/PhenixID/SigningService/custom/trustedcas.jks)
- Click on the pen to the right of Pipes
- Add this pipe. The configuration in this pipe will validate the signature to make sure the data has not been altered.
Please note that this might not suit your environment. Valves can be replaced, removed or added based on your needs. Please view the documentation to get a list of available valves. Please also view this document to see how the certificates can be extracted from the signatures (in order to validate the certificates using this valve).
{
"id": "SignAppDocVerifyPipe",
"description": "Verify pdf document signature(s)",
"valves": [
{
"name": "ItemCreateValve",
"config": {
"dest_id": "{{request.userid}}"
}
},
{
"name": "PropertyAddValve",
"config": {
"name": "b64",
"value": "{{request.body}}"
}
},
{
"name": "PropertyBase64DecoderValve",
"config": {
"source": "b64",
"dest": "temporary"
}
},
{
"name": "PDFSignatureStatusValve",
"enabled": "true",
"config": {
"pdfSource": "{{item.b64}}",
"trustStorePath": "C:/Program Files/PhenixID/SigningService/custom/trustedcas.jks",
"trustStorePassword": "secret (change this to your jks file pwd)"
}
}
]
}
- Click Stage changes and Commit changes
Test
- Browse to https://<phenix_server>:<phenix_server_http_port>/sealapp/
- You should be redirected to https://<phenix_server>:<phenix_server_http_port>/signapp/authenticate/sealapp
- Authenticate
- You should now be logged in to the PhenixID Document Seal Web application
- Upload a pdf document and click Sign
- Verify that a signed pdf document was sent to your mail box (ie, with a seal)
- Download the signed pdf document
- Upload the signed pdf document and click Verify.
- Signature validation should result in a successful (green bar) response
Troubleshooting
Check server.log file.