PhenixID DocumentationPhenixID Signing ServicesPhenixID Signing Service 2.8 Configuration - External Identity ProviderTrusted Central Signing Service - PhenixID Document Signing Web Application - Use external SAML Identity Provider

Trusted Central Signing Service - PhenixID Document Signing Web Application - Use external SAML Identity Provider

Prerequisites

- PhenixID Signing Services 2.8 or higher installed

- Phenix Signing Services configured using instructions in this guide.

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

- Access to External SAML Identity Provider SAML Metadata as URL or XML file

- The entityID value of the external SAML Identity Provider. This can be found in the SAML Metadata content for the Identity provider.

Add trust to external SAML Identity Provider

- Login to PhenixID Authentication Services - Configuration manager

- Go to Scenarios->Federation->SAML metadata upload

- Add new metadata. Enter the URL or upload the xml file.

Fetch the authenticator used for PhenixID Document Signing Web Application

- Open Configuration Manager

- Find the authenticator used for the PhenixID Document Signing web application (by looking in this guide -> Add authenticator for PhenixID Document Signing Web Application )

- Example:

{
		"alias": "signapp",
		"name": "PostUidAndPassword",
		"configuration": {
			"pipeID": "pipeSignAppAuth",
			"successURL": "/signapp/",
			"translationKey": "login.messages.information.body.enduser",
			"headingtranslationKey": "login.messages.information.header.enduser",
			"title": "login.messages.information.title.enduser",
			"allowLanguageChange": "true"
		},
		"id": "signapp"
	}

- Change the alias value from "signapp" to "signapp_old"

 

Add new authenticator for PhenixID Document Signing Web Application

- Add a new authenticator and additional SAML Service Provider conf using this guide. Skip the first seven points below Configure SAML IdP trust and SAML SP.

- Once done, change the added SAMLServiceProviderAuthn authenticator configuration parameters (only the ones in bold):

{
 "id" : "samlsp",
 "alias" : "signapp",
 "name" : "SAMLServiceProviderAuthN",
 "displayName" : "External IdP",
 "configuration" : {
 "successURL" : "/signapp/",
 "sp" : "<no change needed>",
 "pipeID" : "<no change needed>",
 "targetIDP" : "<Set to external idp entityID value fetched in previous step>",
 "acsUrl" : "<your_phenixid_signing services_domain>/signapp/authenticate/signapp",
 "entityID" : "<no change needed>"
 }
 }

 

Change signing pipe

- Configuration manager -> Advanced -> Modules

- Fetch the prism-signingclient module

- Fetch the signPipeID value. Example:

"signPipeID": "SignAppDocSignPipe"

- Configuration manager -> Advanced -> Pipes

- Find the pipe with the signPipeID valve fetched in previous step

- Change these things:

* Remove LDAP searches

* Add an ItemCreateValve

* Add PropertyFromSessionToItem valves to handle values from the SAML attributes in the assertion issued by the IdP

* Rename properties derived from saml attributes for easier handling (for example, oid names should be copied to more friendly property names).

Example pipe. In this scenario, the SAML attributes urn:oid:2.16.840.1.113730.3.1.241 and urn:oid:0.9.2342.19200300.100.1.3 are fetched and copied to new property names displayName, mail. Also, the authentication method (derived from the SAML AuthenticationContextClassRef value) is fetched from the session and copied to a new property, auth_method and used as part of the certificate DN.

 

{
     "id": "SignAppDocSignPipe",
     "description": "Sign document",
     "valves": [
        {
          "name": "SessionLoadValve",
          "config": {
              "id": "{{request.session_id}}"
        }
},
      {
				"name": "ItemCreateValve",
				"enabled": "true",
				"config": {
					"dest_id": "{{request.session_id}}"
				}
			},
			{
				"name": "PropertyFromSessionToItem",
				"config": {
					"source": "urn:oid:2.16.840.1.113730.3.1.241"
				}
			},
			{
				"name": "PropertyFromSessionToItem",
				"config": {
					"source": "urn:oid:0.9.2342.19200300.100.1.3"
				}
			},
			{
				"name": "PropertyFromSessionToItem",
				"config": {
					"source": "authncontextclassref"
				}
			},
					
			{
				"name": "PropertyCopyValve",
				"config": {
					"dest": "displayName",
					"source": "urn:oid:2.16.840.1.113730.3.1.241"
				}
			},
			{
				"name": "PropertyCopyValve",
				"config": {
					"dest": "mail",
					"source": "urn:oid:0.9.2342.19200300.100.1.3"
				}
			},
			{
				"name": "PropertyCopyValve",
				"config": {
					"dest": "auth_method",
					"source": "authncontextclassref"
				}
			},
			
        {
          "name": "PropertyAddValve",
          "config": {
              "name": "b64",
              "value": "{{session.pdf_data}}"
        }
},
        {
          "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": "CreateShortTermKeyStoreValve",
          "enabled": "true",
          "config": {
              "subjectKeyParamater": "CN={{item.displayName}} ({{item.mail}})({{item.auth_method}}),OU=Demo,O=PhenixID",
              "caTemplateKeyParamater": "replacewithyourcaID",
              "keyUsage": [
                "true",
                "true"
              ]
        }
},
        {
          "name": "AddImageToPDFValve",
          "enabled": "true",
          "config": {
              "pathToImage": "C:/Program Files/PhenixID/Server/sign_image/PhenixID-overlay.png",
              "pdfSource": "{{session.pdf_data}}",
              "imagelocation": "northwest"
        }
},
        {
          "name": "PADESSignValve",
          "enabled": "true",
          "config": {
              "keyStoreID": "{{item.keyStoreId}}",
              "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": "signed_{{item.filename}}.pdf"
        }
},
        {
          "name": "SMTPValve",
          "config": {
              "userid_param_name": "userid",
              "smtp_host": "smtp.company.org",
              "smtp_port": "587",
              "smtp_username": "noreply@company.org",
              "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!"
        }
     }
   ]
}

 

Test

  1. Browse to https://<phenix_server>:<phenix_server_http_port>/signapp/
  2. You should be redirected to the external IdP
  3. Authenticate on the external IdP
  4. You should now be redirected back and logged in to the PhenixID Document Signing Web application
  5. Upload a pdf document and click Sign
  6. Verify that a signed pdf document was sent to your mail box
  7. Download the signed pdf document
  8. Upload the signed pdf document and click Verify.
  9. Signature validation should result in a successful (green bar) respons. Also, verify the the certificate subject content (CN) displays configured values.

Troubleshooting

Check server.log file.