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

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_ref": [{
				"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

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

File for SAML IDP metadata template can be downloaded here:

463B

meta_template.xml

Loading of remote meta data

When defining metadata to be consumed using HTTP/HTTPS first time it is required the data is available. If not the server will stop. Once the data has been fetched it is cached and is used in subsequent reboots if remote resource is unavailable. Once online the cache is updated.

Meta data loaded remotely is reloaded based on the ValidUntil value. If valid until is missing, data is reloaded every 4 hours.

Reloader sequence is executed every 5 minutes checking is any meta data needs reloading.