SAML module
Core module when Fortified ID Access should act as SAML Identity Provider (IdP) or SAML Broker for SAML Service Providers (SPs).
Overview
The SAML module is responsible for:
loading, maintaining & generating SAML metadata
generating outbound SAML messages (assertions, authentication & logout requests)
consuming and validating incoming SAML requests
Configuration
metadata_cache
Optional location to where remote metadata loaded, using HTTP, should be cached. The target directory folder must exist.
<server_root>
enable_http
Should metadata be available using HTTP.
true
internal_http_destination
Id of the internal HTTP module to handle HTTP-based metadata loading/consumption.
default
ignore_signature_validation
Disabled signature validation on incoming AuthnRequest & LogoutOutRequest.
false
reload_meta_intervall_millis
How often in milliseconds a reload should occur.
300000
reload_meta_start_delay_millis
How long after startup reloading of metadata should start reloading.
20000
{
"name": "SAML",
"display_name": "SAML module",
"description": "SAML module",
"config": {
"metadata_cache": "${system.customer_home}/cache",
"http_listener": "default",
"metadata_template": [
{
"id": "myidp",
"metadata_file_path": "${system.customer_home}/resources/idptemplate.xml",
"sign_metadata_keystore": {
"path": "${system.customer_home}/resources/fortifiedid.p12",
"password": "secretpassword",
"alias": "fortifiedid",
"key_password": "keypassword"
}
}
],
"metadata": [
{
"url": "https://samltest.id/saml/providers"
},
{
"path": "${system.customer_home}/resources/myidp_data.xml"
}
]
}
}In this example we have two SAML IdPs and we also use inclusion expression/include. With include, all SAML applications and SAML profiles will be in the respective locations. For more how inclusion expression/include works, click following LINK.
{
"name": "SAML",
"display_name": "SAML module",
"description": "SAML module",
"config": {
"metadata_cache": "${system.customer_home}/cache",
"http_listener": "default",
"enable_http": true,
"metadata_template": [
{
"id": "default",
"metadata_file_path": "${globals.default_saml_template}",
"sign_ref": [
{
"keystore": {
"key_password": "${globals.default_keystore_password}",
"password": "${globals.default_keystore_password}",
"path": "${globals.default_saml_keystore}"
}
}
]
},
{
"id": "samlidp_1",
"metadata_file_path": "${system.customer_home}/resources/samlidp_1_template_1.xml",
"sign_ref": [
{
"keystore": {
"path": "${system.customer_home}/resources/samlidp_1_keystore_1.p12",
"password": "ha2nrgJ7qjkPbz3n",
"key_password": "ha2nrgJ7qjkPbz3n"
}
}
]
}
],
"metadata": "@include:samltrust/",
"app_profile": "@include:samlprofile/"
}
}Metadata template
Metadata to be consumed by remote party is generated based of a template file. It is referenced using the parameter "config.metadata_template.metadata_file_path". Administration of this file is handled outside the system and must include the necessary information such as entity id, binding location etc.
Signing of metadata, injecting certificates used and adding of SLO url is handled by the module.
id
Id to be used in URL when getting meta data. Id is used to reference the meta data.
N/A
metadata_file_pathLocation of the template used.
N/A
sign_metadata_keystoreObject for signing the meta data when exposed to clients.
"metadata_template": [{
"id": "painkiller",
"metadata_file_path": "idptemplate.xml",
"sign_ref": [{
"keystore": {
"path": "fortifiedid.p12",
"password": "fortifiedid",
"alias": "fortifiedid",
"key_password": "fortifiedid"
}
}],
"encryption_ref": [{
"keystore": {
"path": "fortifiedid.p12",
"password": "fortifiedid",
"alias": "fortifiedid",
"key_password": "fortifiedid"
}
}]
}]Sign metadata key store
A single object used for signing the meta data
pathLocation of the p12 key store
N/A
passwordpassword of the key store
N/A
aliasalias used to reference in the store.
N/A - Mandatory if multiple entries are located in the store.
key_passwordPassword to the private key.
N/A
"sign_metadata_keystore": {
"path": "fortifiedid.p12",
"password": "fortifiedid",
"alias": "fortifiedid",
"key_password": "fortifiedid"
}
Sign ref - key store
Configuration, array, for key pairs used to sign SAML messages. Multiple key stores is supported. Each entity is placed in the sign_ref array. Key store must be in PKCS#12 format.
pathLocation of the p12 key store
N/A
passwordpassword of the key store
N/A
aliasalias used to reference in the store.
N/A - Mandatory if multiple entries are located in the store.
key_passwordPassword to the private key.
N/A
"sign_ref": [
{
"keystore": {
"path": "fortifiedid.p12",
"password": "fortifiedid",
"alias": "fortifiedid",
"key_password": "fortifiedid"
}
}
]Encryption ref - key store
Same as sign ref, sign_ref, but for encryption.
See sign ref properties.
"encryption_ref": [
{
"keystore": {
"path": "file.p12",
"password": "fortifiedid",
"alias": "fortifiedid",
"key_password": "fortifiedid"
}
}
]Meta data consumption
Setting up trust with an external party is done by consuming it's metadata. This can be done by either a file or using an url.
path
File path to the meta data
N/A
Either path or url.
url
HTTP url to the metadata.
N/A
Either path or url.
validation_pem_path
Path certificate used for metadata validation
N/A
No
"metadata": [
{
"url": "https://samltest.id/saml/providers"
},
{
"url":"https://remotelocation/metadata/mdx/role/sp.xml"
},
{
"path": "sp_meta.xml"
},
{
"path": "localsp_meta.xml"
}
]Validating metadata
Meta data validation can be done setting validation_pem_path. This will only work for data loaded over HTTP.
Setting validation_pem_path enforces mandatory validation. If the metadata lacks a signature, it will be omitted.
Generating metadata
In order to get metadata generated by the system point your browser to:
http://<host>:<port_if_any>/saml/metadata/<config.metaDataTemplate.id>
Integrating with a HSM
Integrity can use a HSM to sign and encrypt messages . It is done through JAVA PKCS#11 standard interface.
Configuration elements are to be located at same level as "keystore" property.
provider_path
File path to the HSM provider implementation file.
N/A
pin
HSM pin.
N/A
alias
Alias handle.
N/A
key_password
Private key password. Use same value as pin if missing.
N/A
certificate_pem_path
If present Integrity will read the certificate from file. Must be in PEM format. If missing, certificate is read from HSM.
N/A
"keystore_hsm": {
"provider_path": "<path_to_providerfile>",
"pin": "the_pin",
"alias": "my_key_alias",
"key_password": "tha_password"
}Thales Luna HSM
It’s possible to integrate with Thales Luna HSM using the Thales JSP provider. This can be a fallback option if the generic PKCS#11 integration fails.
For more info see Thales doc:
https://thalesdocs.com/gphsm/luna/7/docs/network/Content/sdk/java/jsp_overview_install.htm
Ensure adding LunaProvider.jar to java class path. Add knowledge to libLunaAPI.so/LunaAPI.dll "java.library.path". Typically setting -Djava.library.path pointing to directory where the file is located.
slot
HSM slot
N/A
pin
HSM pin.
N/A
alias
Alias handle.
N/A
"keystore_thales_hsm": {
"pin": "fluffy",
"slot": "0",
"alias": "<alias_of_key>"
}Loading of remote meta data
Failing to get meta data for the first time will result in retries every 20 seconds until meta data is loaded.
Meta data target is checked on set intervall (every 20 minutes by default) for information update. Meta data is reloaded based on valid until, if present. Otherwise every four hours.
Using expansion in meta data template
XML meta data template has some understanding of "expansion". It knows the concept of globals. By using globals it will allow for conffiguration like "<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="${globals.idp1.idp_entityid}"".
Note that only globals namespace is supported.