Trusted Central Signing Service - API - Transaction (XML) signing - Use external SAML Identity Provider
Warning
Please note, this document is using the legacy authenticators - in order to use the new protocol agnostic authenticators, you need to apply relevant modifications to the configuration examples outlined in this article.
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": "/xml_sign/authenticate/xml_sign_auth_01"Get the alias part of the value (after "authenticate/". In the above example the alias value is "xml_sign_auth_01"
Open Configuration Manager->Advanced->Authenticators-HTTP
Fetch the authenticator using the alias value from previous step
Example:
{ "alias": "xml_sign_auth_01", "name": "PostUidAndPassword", "displayName": "Username and password", "configuration": { "pipeID": "pipe_xml_sign_auth_01", "successURL": "/xml_sign/sign/api/sign" }, "id": "xml_sign_auth_01" }Change the alias value from "xml_sign_auth_01" to "xml_sign_auth_01_old"
Add new authenticator for signing
Add a new authenticator and additional SAML Service Provider, ex:
Once done, change the added SAMLServiceProviderAuthN authenticator configuration parameters.
{ "id": "samlsp", "alias": "xml_sign_auth_01", "name": "SAMLServiceProviderAuthN", "displayName": "External IdP", "configuration": { "successURL": "/xml_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>/xml_sign/authenticate/xml_sign_auth_01", "entityID": "<no change needed>" } }
Make sure you change the uri ("xml_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": "xml_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": "XML sign - Execute Sign",
"enabled": "true",
"id": "xml_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": "PropertyAddValve",
"enabled": "true",
"config": {
"name": "signerID",
"value": "{{session.user_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": "XAdESSignValve",
"enabled": "true",
"config": {
"keyStoreID": "{{item.keyStoreId}}",
"xmlSourceData": "{{item.temporary}}",
"xmlTarget": "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": "XADES"
}
]
}
}
]
}
Troubleshooting
Check server.log file, see Log settings and Events and Logging for more details.