PhenixID DocumentationPhenixID Signing ServicesPhenixID Signing ServiceConfiguration - External Identity ProviderTrusted Central Signing Service - API - Document (PDF) signing - Use external SAML Identity Provider

Trusted Central Signing Service - API - Document (PDF) signing - 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 signing

- Open Configuration Manager->Advanced->Modules

- Find the prism-fedsigning module

- Find the configuration param sign_auth_redirect_url. Example:
"sign_auth_redirect_url": "/pdf_sign/authenticate/pdf_sign_auth_01"

- Get the alias part of the value (after "authenticate/". In the above example the alias value is "pdf_sign_auth_01"

- Open Configuration Manager->Advanced->Authenticators-HTTP

- Fetch the authenticator using the alias value from previous step

- Example:

{
		"alias": "pdf_sign_auth_01",
		"name": "PostUidAndPassword",
		"displayName": "Username and password",
		"configuration": {
         "pipeID": "pipe_pdf_sign_auth_01",
			"successURL": "/pdf_sign/sign/api/sign"
		},
		"id": "pdf_sign_auth_01"
	}

- Change the alias value from "pdf_sign_auth_01" to "pdf_sign_auth_01_old"

 

Add new authenticator for signing

- 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": "pdf_sign_auth_01",
		"name": "SAMLServiceProviderAuthN",
		"displayName": "External IdP",
		"configuration": {
			"successURL": "/pdf_sign/sign/api/sign",
			"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>/pdf_sign/authenticate/pdf_sign_auth_01",
			"entityID": "<no change needed>"
		}
	}

 Make sure you change the uri ("pdf_sign" above) to suite your environment if needed.

Change signing pipe

- Configuration manager -> Advanced -> Modules

- Fetch the prism-fedsigning module

- Fetch the sign_pipe value. Example:

"sign_pipe": "pdf_sign_sign_pipe_01"

- Configuration manager -> Advanced -> Pipes

- Find the pipe with the sign_pipe 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 presented below.

In this example, 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.

 

{
		"name": "Pdf sign - Execute Sign",
		"enabled": "true",
		"id": "pdf_sign_sign_pipe_01",
		"valves": [
			{
				"name": "SessionLoadValve",
				"enabled": "true",
				"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": "SessionLoadValve",
				"enabled": "true",
				"config": {
					"id": "{{request.file_id}}",
					"require_session": "true",
					"require_auth_session": "false"
				}
			},
			{
				"name": "PropertyAddValve",
				"enabled": "true",
				"config": {
					"name": "content",
					"value": "{{session.content}}"
				}
			},
			{
				"name": "PropertyBase64DecoderValve",
				"config": {
					"source": "content",
					"dest": "temporary"
				}
			},
			{
				"name": "CreateShortTermKeyStoreValve",
				"enabled": "true",
				"config": {
					"subjectKeyParamater": "CN={{item.displayName}} ({{item.mail}}) ({{item.auth_method}}),O=PhenixID",
					"caTemplateKeyParamater": "customsignca",
					"keyUsage": [
						"true",
						"true"
					]
				}
			},
			{
				"name": "AddImageToPDFValve",
				"enabled": "true",
				"config": {
					"pathToImage": "D:/Program Files/PhenixID/Server/sign_image/PhenixID-overlay.png",
					"pdfSource": "{{item.temporary}}",
					"imagelocation": "northwest"
				}
			},
			{
				"name": "PADESSignValve",
				"enabled": "true",
				"config": {
					"keyStoreID": "{{item.keyStoreId}}",
					"pdfSourceData": "{{item.pdfupdated}}",
					"pdfTarget": "documentNotEncoded"
				}
			},
			{
				"name": "PropertyStringBase64EncoderValve",
				"enabled": "true",
				"config": {
					"source": "documentNotEncoded",
					"dest": "document"
				}
			},
			{
				"name": "SessionPropertyReplaceValve",
				"enabled": "true",
				"config": {
					"name": "content",
					"value": "{{item.document}}"
				}
			},
			{
				"name": "SessionPropertyReplaceValve",
				"enabled": "true",
				"config": {
					"name": "modified",
					"value": "{{now}}"
				}
			},
			{
				"name": "SessionPersistValve",
				"enabled": "true",
				"config": {}
			},
    {  
         "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"
               }
            ]
         }
      }
		]
	}

 

Troubleshooting

Check server.log file.