SAML application

When a SAML SP is added to Fortified ID Access, it is represented as a SAML trusted application. On the SAML application object, you specify where the metadata is located, what assertion data to needed, whether a profile should be used, etc.

A SAML application relies on metadata configuration to establish trust. Valid metadata is the minimum requirement. Each metadata element may also specify custom settings to enable tailored behaviour.

When signed AuthnRequests are required, the SP metadata must contain a usable signing certificate. If a signed request cannot be validated because the certificate is missing from metadata, Access reports this as a configuration error.

Using configuration, the SAML application object can control:

• Metadata (names, description, URL, IdP affiliation).
• Cryptography (signing and digest algorithms, encryption of assertions).
• Session handling (timeouts, session information, client IP address).
• NameID handling (format, source parameters, qualifiers).
• Attributes (which attributes are returned, their format, requirements, and types).
• App-specific authorization before the SAML response is issued.

This allows each application to precisely define how its SAML Response is constructed and returned.

Note. If you have several SAML applications that should have similar configuration, you can use SAML profiles. Click the following link for more information about SAML Profiles.

Note

Settings for a SAML application can come from settings on the SAML application itself, or from a SAML profile, or from the IdP object.
1. If a profile is configured, the properties of the profile object will override everything else.
2. If a profile is not configured, the application settings will apply.
3. If nothing is configured on the application, the IdP settings will be used.
Important! Settings are not merged but applied as a single source of truth.

The assertion_config object can be configured directly on the SAML application/trust or on a SAML profile. When a profile is configured on the application, the profile version of assertion_config becomes the active configuration.

Set assertion_config.force_re_auth to true when the application must always start a new authentication instead of reusing the current authentication state. If the application uses a SAML profile, the profile value becomes the active application-level value.

Re-authentication is required when any active source requires it: the incoming AuthnRequest contains ForceAuthn=true, the SAML IdP has global force_re_auth=true, the matching IdP assertion configuration requires it, or the active SAML application/profile requires it. These sources use OR semantics, so false in an application or profile cannot disable a requirement from the AuthnRequest or IdP. See SAML IdP for the IdP-side settings.

---

Below are the properties that can be configured for a SAML application.

Properties

SAML application properties

Name	Description	Default value	Mandatory
url	URL location of metadata.	N/A	false
path	File path to metadata.	N/A	false
enabled	Flag controlling if this metadata entry is enabled. Disabled metadata entries are ignored and no metadata is loaded from them.	true	false
assertion_pre_pipe	Overrides IdP default pre-pipe. An empty value means no pipe; the IdP pipe is not used as fallback.	N/A	false
authorization	Optional app-specific authorization configuration. Use this to run an authorization pipe before the SAML response is issued. See the App-specific authorization section below for details.	N/A	false
belongs_to_idp	Entity ID of the allowed IdP. Only use if configuring multiple IdPs.	N/A	false
require_signed_auth_requests	If set, only signed auth requests are accepted.	false	false
signature_algorithm	Algorithm used for signing.	http://www.w3.org/2001/04/xmldsig-more#rsa-sha256	false
digest_algorithm	Algorithm used for digest calculation.	http://www.w3.org/2001/04/xmlenc#sha256	false
static_audience	Overrides SP audience.	N/A	false
include_entity_id	If multiple entities are in metadata, array of entity IDs to trust.	N/A	false
exclude_entity_id	If multiple entities are in metadata, array of entity IDs to filter out. This overrides include_entity_id.	N/A	false
profile	Name of a SAML application profile. Setting this makes local application settings inactive.	N/A	false
app_tag	JSON array containing strings used for filtering and similar operations.	N/A	false
assertion_config	Parent holder for assertion configuration.	{}	false

assertion_config properties

Name	Description	Default value	Mandatory
force_re_auth	Require a new authentication for this SAML application. This value cannot disable an incoming ForceAuthn=true or a global/SP-specific IdP requirement.	false	false
encrypt	Whether the assertion should be encrypted. Requires an encryption certificate in SP metadata.	false	false
encryption_algorithm	Optional XML Encryption data encryption algorithm for encrypted assertions. If omitted, Access first uses a compatible EncryptionMethod from SP metadata when present, otherwise the built-in default is used. Use http://www.w3.org/2001/04/xmlenc#aes256-cbc when an SP requires AES-256-CBC.	N/A	false
include_session_information	Include session information in the assertion (trace ID).	true	false
include_session_not_on_or_after	Include the SessionNotOnOrAfter attribute.	false	false
include_remote_address	Include the client's IP address.	false	false
include_attribute_value_type	Include explicit XML Schema typing (xsi:type) on SAML AttributeValue elements. Set to false for service providers that require untyped attribute values.	true	false
sign_assertion	Whether the assertion itself should be signed.	true	false
sign_response	Whether the full response should be signed.	true	false
session_not_on_or_after_minutes	Session expiration time in minutes.	60	false
assertion_valid_for_no_of_minutes	Assertion validity period in minutes.	2	false
name_id	Configuration of the NameID element.	{}	false
attributes	Each entry in attributes describes one attribute in the assertion.	N/A	false

assertion_config.name_id properties

Name	Description	Default value	Mandatory
format	NameID format.	urn:oasis:names:tc:SAML:1.1:nameid-format:transient	false
from_parameter	State parameter containing the NameID value.	nameID	false
include_sp_name_qualifier	Whether to include SPNameQualifier.	false	false
include_name_qualifier	Whether to include NameQualifier.	false	false

assertion_config.attributes properties

Name	Description	Default value	Mandatory
name	Attribute name (URN or custom identifier).	N/A	true
value	Name of the state attribute holding the value.	N/A	true
name_format	Attribute name format, usually unspecified.	urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified	false
friendly_name	Human-readable friendlyName alias.	N/A	false
required	Indicates if the attribute is required. If true, the value may be empty.	false	false
include_if_empty	Include the attribute even if the source value is missing.	false	false

Example (native)

{
    "id": "saml_trust_1",
    "display_name": "Example SAML Application",
    "description": "Sample configuration for returning a SAML response",
    "url": "https://sp.example.com/sso",
    "assertion_pre_pipe": "validateUserAttributes",
    "belongs_to_idp": "https://idp.example.com",
    "signature_algorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
    "digest_algorithm": "http://www.w3.org/2001/04/xmlenc#sha256",
    "static_audience": "https://audience.example.com",
    "app_tag":["tag1","tag2"],
    "include_entity_id": [
        "https://trusted-sp-1.com",
        "https://trusted-sp-2.com"
    ],
    "exclude_entity_id": [
        "https://untrusted-sp.com"
    ],
    "assertion_config": {
        "force_re_auth": true,
        "encrypt": true,
        "encryption_algorithm": "http://www.w3.org/2001/04/xmlenc#aes256-cbc",
        "name_id": {
            "format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
            "from_parameter": "userPrincipalName",
            "include_sp_name_qualifier": true,
            "include_name_qualifier": false
        },
        "include_session_information": true,
        "include_session_not_on_or_after": true,
        "include_remote_address": false,
        "include_attribute_value_type": true,
        "sign_assertion": true,
        "sign_response": true,
        "session_not_on_or_after_minutes": 120,
        "assertion_valid_for_no_of_minutes": 5,
        "attributes": [
            {
                "name": "givenName",
                "value": "firstName",
                "name_format": "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified",
                "friendly_name": "First Name",
                "required": false

            },
            {
                "name": "sn",
                "value": "surName",
                "name_format": "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified",
                "friendly_name": "Last Name",
                "required": true

            },
            {
                "name": "mail",
                "value": "e-mail",
                "name_format": "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified",
                "friendly_name": "Email"
            }
        ]
    }
}

Example (using profile)

{
    "id": "saml_trust_2",
    "display_name": "Fortified ID Portal SAML SP",
    "description": "SAML SP configuration for Fortified ID Portal",
    "url": "https://localhost:8445/portal/authn/login/metadata",
    "profile": "saml_profile_generic"
}

App-specific authorization

You can configure app-specific authorization on the SAML application. This lets Fortified ID Access run an authorization pipe after the user has authenticated, but before the final SAML response is issued to the Service Provider.

If the authorization pipe succeeds, Access continues the flow as normal.

If the authorization pipe fails, Access can:

• redirect the user to a configured failure location
• redirect the user to a specific target based on the pipe failure message
• fall back to the standard SAML deny handling

Properties

Name	Description	Mandatory
pipe_id	Pipe used to evaluate whether the authenticated user is authorized for this SAML application. If the authorization object is present, this property is required.	true
fail_location	Fallback redirect target used when authorization fails and no failed_redirect entry matches the failure message.	false
failed_redirect	Array of pattern-based redirects. Each entry contains pattern and target. The first matching pattern is used.	false

Example

"authorization": {
    "pipe_id": "check_app_authorization",
    "fail_location": "/login/no-access",
    "failed_redirect": [
        {
            "pattern": ".*missing_role.*",
            "target": "/login/missing-role"
        },
        {
            "pattern": ".*expired_contract.*",
            "target": "/login/contact-admin"
        }
    ]
}

Note

For metadata including multiple entities, all included entities will have the same setting.