> For the complete documentation index, see [llms.txt](https://docs.fortifiedid.se/access/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fortifiedid.se/access/key-components/modules/saml/saml-application.md). # SAML application This section explains how to manage a SAML trusted 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](/access/key-components/modules/saml/saml-profile.md). {% hint style="info" %} 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. {% endhint %} 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](/access/key-components/authenticators/protocol-managers/saml/saml-idp.md) for the IdP-side settings. *** Below are the properties that can be configured for a SAML application. {% tabs %} {% tab title="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 | | {% endtab %} | | | | {% tab title="Example (native)" %} ```json { "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" } ] } } ``` {% endtab %} {% tab title="Example (using profile)" %} ```json { "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" } ``` {% endtab %} {% endtabs %} ## 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 {% tabs %} {% tab title="Properties" %}
NameDescriptionMandatory
pipe_idPipe 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_locationFallback redirect target used when authorization fails and no failed_redirect entry matches the failure message.false
failed_redirectArray of pattern-based redirects. Each entry contains pattern and target. The first matching pattern is used.false
{% endtab %} {% tab title="Example" %} ```json "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" } ] } ``` {% endtab %} {% endtabs %} {% hint style="info" %} For metadata including multiple entities, all included entities will have the same setting. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.fortifiedid.se/access/key-components/modules/saml/saml-application.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.