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

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/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
metadata	Configuration for consuming metadata and SP settings	N/A
app_profile	Configuration of SAML application profiles	N/A

Example 1

Example 2

Entries in metadata and app_profile can also include app-specific authorization. See SAML application and SAML profile.

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.

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

Sign metadata 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

Example

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

Encryption ref - key store

Same as sign ref, sign_ref, but for encryption.

Properties

See sign ref properties.

Example

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.

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.
validation_pem_path	Path certificate used for metadata validation	N/A	No

Example

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.

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

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.

Properties

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

Example

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.