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": "PropertyCopyValve",
"config": {
"dest": "signerID",
"source": "{{session.user_id}}"
}
},
{
"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": "[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"
}
]
}
}
]
}
Test
- Browse to https://<phenix_server>:<phenix_server_http_port>/signapp/
- You should be redirected to the external IdP
- Authenticate on the external IdP
- You should now be redirected back and logged in to the PhenixID Document Signing Web application
- Upload a pdf document and click Sign
- Verify that a signed pdf document was sent to your mail box
- Download the signed pdf document
- Upload the signed pdf document and click Verify.
- 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.