SAML module

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

Note

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>	false
enable_http	Should metadata be available using HTTP.	true	false
internal_http_destination	Id of the internal HTTP module to handle HTTP-based metadata loading/consumption.	default	false
ignore_signature_validation	Disabled signature validation on incoming AuthnRequest & LogoutOutRequest.	false	false
reload_meta_intervall_millis	How often in milliseconds a reload should occur.	300000	false
reload_meta_start_delay_millis	How long after startup reloading of metadata should start reloading.	20000	false
metadata	Configuration for consuming metadata and SP settings	N/A	false
app_profile	Configuration of SAML application profiles	N/A	false
			false

Example 1

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

Example 2

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

Note

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	false
metadata_file_path	Location of the template used.	N/A	false
sign_metadata_keystore	Object for signing the meta data when exposed to clients.		true

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 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	true
password	password of the key store	N/A	true
alias	alias used to reference in the store.	N/A - Mandatory if multiple entries are located in the store.	true
key_password	Password to the private key.	N/A	true

Example

  "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	true
password	password of the key store	N/A	true
alias	alias used to reference in the store.	N/A - Mandatory if multiple entries are located in the store.	true
key_password	Password to the private key.	N/A	true

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.

Example

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

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

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

Properties

Name	Description	Defalut value	Mandatory
provider_path	File path to the HSM provider implementation file.	N/A	true
pin	HSM pin.	N/A	true
alias	Alias handle.	N/A	true
key_password	Private key password. Use same value as pin if missing.	N/A	true
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	false

Example

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

Access authenticates to the selected Thales Luna slot as Crypto User for routine signing and encryption operations. Configure pin with the Crypto User PIN; Crypto Officer credentials are not required. If Crypto User authentication fails, Access stops keystore initialization instead of attempting to load the keystore with another role.

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	true
pin	Crypto User PIN for the selected HSM slot.	N/A	true
alias	Alias handle.	N/A	true

Example

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

Note

Tested and verified with Thales Luna A7x series

Loading of remote metadata

Failing to get metadata for the first time will result in retries every 20 seconds until metadata is loaded.

The metadata target is checked at a set interval (every 20 minutes by default) for information updates. Metadata is reloaded based on valid until, if present. Otherwise, it is reloaded every four hours.

Using expansion in metadata template

The XML metadata template has some understanding of "expansion". It knows the concept of globals. By using globals, it will allow configuration like "<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="${globals.idp1.idp_entityid}"".

Note that only the globals namespace is supported.