SAMLModule

Required when operating under SAML context as SP or IDP.

Introduction

Responsible for

• loading, maintaining & generating metadata.

• generating outbound SAML messages (assertions, authentication & logout requests )

• consuming and validating incoming SAML requests.

When deployed the module opens http port 8080 to enable saml meta data generation.

Configuration

Module name: SAML

Properties

Name	Description	Default value	Mandatory
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.	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

Full example

{
    "name": "SAML",
    "config": {
        "metadata_cache": "/opt/fortifiedid/integrity/cache",
        "http_port": 8081,
        "metadata_template": [
            {
                "id": "myidp",
                "metadata_file_path": "/opt/fortifiedid/integrity/custom/idptemplate.xml",
                "sign_metadata_keystore": {
                    "path": "/opt/fortifiedid/integrity/custom/fortifiedid.p12",
                    "password": "secretpassword",
                    "alias": "fortifiedid",
                    "key_password": "keypassword"
                }
            }
        ],
        "metadata": [
            {
                "url": "https://samltest.id/saml/providers"
            },
            {
                "path": "/opt/fortifiedid/integrity/custom/idpdata.xml"
            }
        ]
    }
}

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 meta data, injecting certificates used and adding of SLO url is handled by the module.

Properties

Name	Description	Default value	Mandatory
id	Id to be used in URL when getting meta data. Id is used to reference the meta data.	N/A
metadata_file_path	Location of the template used.	N/A
sign_metadata_keystore	Object for signing the meta data when exposed to clients.

Example

"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 meta data key store

A single object used for signing the meta data

Properties

Name	Description	Default value	Mandatory
path	Location of the p12 key store	N/A
password	password of the key store	N/A
alias	alias used to reference in the store.	N/A - Mandatory if multiple entries are located in the store.
key_password	Password to the private key.	N/A

Second Tab

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

Properties

Name	Description	Default value	Mandatory
path	Location of the p12 key store	N/A
password	password of the key store	N/A
alias	alias used to reference in the store.	N/A - Mandatory if multiple entries are located in the store.
key_password	Password to the private key.	N/A

Example

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

Properties

See sign ref properties.

Second Tab

"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 meta data. This can be done by either a file or using an url.

Properties

Name	Description	Default value	Mandatory
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.

Example

"metadata": [  
          {
            "url": "https://samltest.id/saml/providers"
          },
          {
            "url":"https://remotelocation/metadata/mdx/role/sp.xml"
          },
          {
            "path": "sp_meta.xml"
          },
          {
            "path": "localsp_meta.xml"
          }
        ]

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.

Properties

Name	Description	Defalut value	Mandatory
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

Example

"keystore_hsm": {
                  "provider_path": "<path_to_providerfile>",
                  "pin": "the_pin",
                  "alias": "my_key_alias",
                  "key_password": "tha_password"
                }

Thales Luna HSM

It is possible integrating with Thales Luna HSM in using the JSP provider from Thales. This can be an option if for some reason generic PKCS#11 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.

Properties

Name	Description	Defalut value	Mandatory
slot	HSM slot	N/A
pin	HSM pin.	N/A
alias	Alias handle.	N/A

Example

"keystore_thales_hsm": {
        "pin": "fluffy",
        "slot": "0",
        "alias": "<alias_of_key>"
    }

Tested and verified with Thales Luna A7x series

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.