SAML 2.0 Configuration Settings

SAML 2.0 is an XML-based protocol that relies on security tokens containing assertions to exchange encoded messages from identity providers (IdPs) that convey user ID and other credentials to ICONICS security. These assertions allow ICONICS security to control access rights to GENESIS64™ applications. Additionally, ICONICS security supports both an SP-initiated and external IdP-initiated single log out (SLO).

Before configuring SAML 2.0 IdPs, you need to:

Access the SAML 2.0 configuration settings for security authorization in the Global Settings Web Login tab (accessed through the Security node in Workbench).

SAML Authentication and User Mapping

The Authentication and User Mapping sections are required for configuring the access gateway between ICONICS security and the external IdP.

Authentication

Authentication Property

Description

Type

Select SAML 2.0 to show all required SAML authentication information.

Assertion Consumer Service (ACS)

If required, the ACS is used for setting up the external SAML IdP.
This is information only. It may be required when setting up the external SAML IdP. The base URL address can be changed through Platform Services Configuration dialog (accessed from the Workbench Tools tab).

SP metadata URL

The SP metadata URL is used when setting up the external SAML IdP.
This is information only. The base URL address can be changed through Platform Services Configuration dialog (accessed from the Workbench Tools tab).

SP Entity ID

This is similar to the OIDC Client Identifier. Enter the ID (any value will work). Recommend using a globally unique value in the form of a URL. The value entered may be required when setting up the external SAML IdP.

IdP metadata document

Add the external IdP's metadata XML file to the text box.
For a specified single IdP, the metadata XML contains an <EntityDescriptor> element at the root level. For a Federated SAML document that includes a single IdP, the metadata XML contains a <EntitiesDescriptor> element at the root level, which contains a single child <EntityDescriptor> element.
Use the links to either Download from the web or Load from a file. Recommend selecting Apply to save information.

If the text box is left empty, the SAML login will not work. However, the SAML 2.0 protocol is partially set up on the server to at least produce the SP metadata document. Download the document from the URL shown in SP metadata URL. It's necessary to cut and paste the URL into the web browser.

Force Authentication

Select this checkbox to set a flag (ForceAuthn = "true"), indicating that the IdP performs a new authentication instead of reusing an existing session. Different IdPs may react differently to this setting.

Include the WantAssertionsSigned attribute in metadata

Select this checkbox to make the metadata generated by GENESIS64 security for SAML integration include a WantAssertionsSigned="true" attribute in the SPSSODescriptor element.
There is no effect on the actual signature-checking logic—logic occurs regardless of the setting. GENESIS64 security checks the IdP response signature which contains the assertions. If no signature is present at this level, it only checks the signature for every single assertion contained within the IdP response.

Support SAML Authentication Request Signing /Decrypting Assertions

Select the checkbox when the IdP requires signed authorization requests (the IdP's metadata contains WantAuthnRequestsSigned="true").
GENESIS64 security then digitally signs the outgoing authorization requests using the selected certificate (defined below). The enabled selection also allows GENESIS64 security to decrypt inbound SAML assertions and is necessary for a single logout (SLO).

Select certificate by / Certificate identifier

Specifies how to find the signing / decryption certificate in the Windows Certificate Store. Multiple certificates can match these criteria.
If the certificate(s) that match the criteria specified by Select certificate by and Certificate identifier change, the new certificate(s) will not get reloaded until a FrameWorX server restarts or until you select Apply to save the changes.
When multiple valid certificates match the criteria, all get used. Only the oldest certificate (with the earliest "NotAfter" or "Valid To" property) is used to sign Authentication Requests. Whereas, any of the other certificates will be used for decryption. This behavior can be used for certificate rollover.

SAML Authentication User Mapping

User Mapping Property

Description

Use this SAML claim

Information about the user (claim) that gets extracted from the SAML XML tokens when mapping users from the external IdP.
The following rules apply when security extracts information from the SAML token and assigns them to individual claims:

  • The <Subject> → <NameID> element gets mapped to a claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier.
  • Each value of an <Attribute> element gets mapped to a claim named the same as the <Attribute> (using the Name attribute of the <Attribute> element). If there are multiple values in the <Attribute> element, only the first one is used.

Find existing user by

The selected claim can be mapped to one of a fixed list of user attributes:

  • Display name
  • Unique name (for Active Directory, this is the user's GUID in string form.)
  • Active Directory SID (can only be used if users come from Active Directory.)
  • User Lookup Identifier (a text field in Workbench that can be filled with an arbitrary unique value.)

Show list of claims

The Show list of claims hyperlink opens a web page that redirects to the external IdP and then lists all the claims that it extracted from the token. To use this link, you need to click Apply and wait a second for the server to notice the changes and reconfigure.