SAMLSP

Configuration reference for the SAMLSP authenticator.

Introduction

The SAMLSP authenticator lets a Fortified ID web application act as a SAML 2.0 Service Provider (SP).

Supported features

HTTP POST binding for authentication requests and responses
Unsigned authentication requests
Signed SP metadata and logout requests
SP-initiated and IdP-initiated single logout over HTTP POST
A single trusted IdP through metadata, or multiple trusted IdPs through trust_settings
SAML discovery when more than one trusted IdP is available

Configuration

Configure SAMLSP in the authenticators list of an AuthN module. The application and authenticator must use the same HTTP listener and URI authority (host and port) so that they share the authentication session.

Properties
Example

Name	Description	Default	Mandatory
`context_path`	Assertion Consumer Service route. Metadata and logout endpoints are exposed below this path.	`""`	true
`success_location`	Redirect target after successful authentication when no completion location or return URL is available.	`""`	false
`failure_location`	Redirect target after failed authentication.	`""`	false
`metadata_file_path`	Path to the SP metadata template. Expressions in the `globals` scope are expanded before parsing.	`""`	true
`metadata_output_directory`	Directory where generated SP metadata is written as `<authenticator id>.xml` at startup.	`"."`	false
`entity_id`	SP entity ID. Overrides the entity ID in the metadata template.	Value from template	false
`sign_ref`	Signing-key configurations used for SP metadata and logout requests.	`[]`	true
`metadata`	Single-IdP metadata source. Configure either `metadata.path` or `metadata.url`.	`{}`	false
`trust_settings`	Multi-IdP trust configuration. Use instead of `metadata`.	`{}`	false
`metadata_cache`	Directory used to cache IdP metadata loaded through `metadata.url`.	`"."`	false
`internal_http_destination`	Internal HTTP client destination used to retrieve `metadata.url`.	`"default"`	false
`logout_location`	Fallback post-logout destination when the application has not stored a destination in the session.	`""`	false
`force_authn`	Adds `ForceAuthn="true"` to generated authentication requests.	`false`	false
`validate_in_response_to`	Requires the response `InResponseTo` value to match the pending request ID.	`false`	false
`validate_audience_restrictions`	Requires the SP entity ID to appear in the assertion's audience restrictions.	`false`	false
`validate_destination`	Requires the response destination to match an Assertion Consumer Service in the SP metadata.	`false`	false
`validate_authn_instant`	Validates assertion `AuthnInstant` values.	`false`	false
`validate_session_timestamp`	Validates assertion `SessionNotOnOrAfter` values.	`false`	false
`require_authn_context`	Requires an `AuthnContextClassRef` and validates it against `allowed_authn_context_class_ref`.	`false`	false
`allowed_authn_context_class_ref`	Accepted `AuthnContextClassRef` URIs. Also adds `RequestedAuthnContext` to authentication requests.	`[]`	false
`authn_context_comparison`	Requested authentication-context comparison: `exact`, `minimum`, `maximum`, or `better`.	`"exact"`	false
`skew_time_seconds`	Allowed clock skew for timestamp validation, in seconds.	`60`	false

{
    "id": "sp",
    "type": "SAMLSP",
    "config": {
        "context_path": "/portal/authn/login",
        "success_location": "/portal/",
        "failure_location": "/portal/authn/failed",
        "metadata_file_path": "<installation path>/config/sp-metadata.xml",
        "metadata_output_directory": "<installation path>/metadata",
        "metadata": {
            "url": "https://idp.example.org/saml/metadata"
        },
        "metadata_cache": "<installation path>/cache",
        "entity_id": "https://portal.example.org/saml/sp",
        "sign_ref": [
            {
                "keystore": {
                    "path": "<installation path>/keys/sp.p12",
                    "password": "<keystore password>",
                    "alias": "sp",
                    "key_password": "<private-key password>"
                }
            }
        ]
    }
}

Configure exactly one source of trusted IdP metadata: metadata.path, metadata.url, or a non-empty trust_settings object.

Signing keys

At least one entry in sign_ref is required. SAMLSP uses a successfully loaded credential to sign generated SP metadata and logout requests.

Properties
Example

Name	Description	Default	Mandatory
`keystore.path`	Path to a PKCS#12 keystore. Use either `path` or `data`.	`""`	false
`keystore.data`	Base64-encoded PKCS#12 data. Use either `data` or `path`.	`""`	false
`keystore.password`	Keystore password.	`""`	true
`keystore.alias`	Alias of the signing key. If omitted, the first keystore alias is used.	First alias	false
`keystore.key_password`	Private-key password.	Value of `password`	false

{
    "sign_ref": [
        {
            "keystore": {
                "path": "<installation path>/keys/sp.p12",
                "password": "<keystore password>",
                "key_password": "<private-key password>"
            }
        }
    ]
}

Metadata generation

At startup, SAMLSP reads the template from metadata_file_path, expands expressions from the globals scope, applies the configured entity_id, adds signing and logout information, and signs the resulting metadata. It writes the generated metadata to <metadata_output_directory>/<authenticator id>.xml.

The same metadata is available over HTTP at <context_path>/metadata. For example, a context_path of /portal/authn/login exposes metadata at /portal/authn/login/metadata.

Restart the module after changing the metadata template.

IdP metadata and trust

One IdP

Use metadata.path to load an IdP EntityDescriptor from a local file, or metadata.url to retrieve it over HTTP. Metadata retrieved over HTTP is stored in metadata_cache. If a later retrieval fails, SAMLSP attempts to use the cached copy.

Multiple IdPs

Use trust_settings to load and filter metadata for multiple IdPs. Add one or more local metadata files to trust_settings.path; each file can contain either an EntityDescriptor or an EntitiesDescriptor.

Properties
Example

Name	Description	Default	Mandatory
`path`	List of local metadata files to load.	`[]`	true
`discovery_url`	SAML IdP Discovery Service URL used when more than one trusted IdP remains.	`""`	false
`allow_only_entityid`	Case-insensitive allowlist of IdP entity IDs. When non-empty, only listed IdPs are trusted.	`[]`	false
`reject_entityid`	Case-insensitive denylist of IdP entity IDs. Rejection takes precedence over the allowlist.	`[]`	false
`idp_export`	Static session and global-state values selected by source IdP.	`[]`	false

{
    "trust_settings": {
        "path": [
            "<installation path>/metadata/idp-group.xml"
        ],
        "discovery_url": "https://discovery.example.org/select",
        "allow_only_entityid": [
            "https://idp-a.example.org",
            "https://idp-b.example.org"
        ],
        "reject_entityid": [],
        "idp_export": [
            {
                "entityid": "https://idp-a.example.org",
                "export": [
                    {
                        "name": "idp_group",
                        "value": "group-a"
                    }
                ]
            }
        ]
    }
}

When discovery is used, the SP metadata template must contain an IdP Discovery DiscoveryResponse extension. SAMLSP sends the extension's location to the discovery service as the return URL. The discovery service returns the selected IdP entity ID in the providerid query parameter.

SAML response validation

The following checks are always performed:

The response issuer is present in the configured trust registry.
The response or at least one assertion has a valid signature.
The response status is successful.
The response IssueInstant is valid within skew_time_seconds.
Assertion NotBefore and NotOnOrAfter timestamps are valid within skew_time_seconds.
The assertion issuer is present.

Use the optional validation properties to enable checks for InResponseTo, destination, audience restrictions, AuthnInstant, SessionNotOnOrAfter, and authentication context.

Authentication context

When allowed_authn_context_class_ref contains one or more values, generated authentication requests include RequestedAuthnContext. Returned AuthnContextClassRef values are compared with this list without regard to case.

Set require_authn_context to true to reject responses that do not contain an AuthnContextClassRef. Configure at least one allowed value when enabling this requirement.

{
    "require_authn_context": true,
    "allowed_authn_context_class_ref": [
        "urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
        "urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI"
    ],
    "authn_context_comparison": "minimum"
}

Session data

After successful validation, every SAML assertion attribute is copied to the session. FriendlyName is used as the property name when present; otherwise, Name is used. An attribute with one value is stored as a string, while an attribute with multiple values is stored as an array. The assertion issuer is stored in source_idp.

Entries in trust_settings.idp_export add configured static values to both the session and the global authenticator state when source_idp matches the entry's entityid.

Single logout

The logout route is <context_path>/logout. If the selected IdP metadata contains a Single Logout Service, SAMLSP sends a signed logout request to the IdP. It also accepts IdP-initiated logout requests over HTTP POST.

After logout, an application destination stored in the session takes precedence over logout_location. During local logout without an IdP Single Logout Service, the optional next query parameter is accepted only if its value starts with /.

Metadata template

Use the attached file as a minimal SP metadata template.

spmeta_template.xml