Configuring SAML 2.0 Authentication for Web Login

When configuring web login, you can configure authentication through an external SAML Identity Provider.

To set up the SAML 2.0 authentication for web login:

  1. In Workbench in Project Explorer, expand your project > Security > Global Settings and go to the Web Login tab.

  2. In the Authentication section in Type, select SAML 2.0, and then complete the additional settings specific to this type.

    Setting

    Description

    Assertion Consumer Service (ACS)

    Informational only; the value may be required when setting up the external SAML Identity Provider.

    SP metadata URL

    Informational only. You can download a SAML metadata document from this URL after enabling web login and saving the Global Settings changes. This document will very likely be required when setting up the external SAML Identity Provider.
    You can change the URL that Security listens on in the Platform Services Configuration dialog, Learn more

    SP Entity ID

    The value is required when setting up the setting up the external SAML Identity Provider. It can be found from the SAML Identity Provider.

    IdP metadata document

    Saves the metadata XML from the external IdP. Click one of the links on the left to download the document from a URL or load it from a file.
    Security currently does not support loading the metadata from a URL dynamically.
    The metadata XML file can be one of the following:
    - Empty—The SAML login will not work, but the SAML protocol in the server will be partially set up to at least produce the SP metadata document on the SP metadata URL above.
    - A SAML document with a single Identity Provider specified (most common)—The metadata XML contains an <EntityDescriptor> element at the root level.
    - A Federated SAML document that contains a single Identity Provider—The metadata XML contains an <EntitiesDescriptor> element at the root level, which contains a single child <EntityDescriptor> element.

    Force authentication

    (Optional) Instructs the SAML Identity Provider to re-prompt the user for some information.

    Include the WantAssertionsSigned attribute in metadata

    Adds a WantAssertionsSigned="true" attribute to the SPSSO Descriptor element of the metadata that GENESIS Security generates. This advertises to the IdP that GENESIS wants the assertions it returns to be signed.
    This setting has no effect on the actual signature checking logic. GENESIS Security checks the signature of the IdP response that contains the assertions; only if no signature is present at that level does it then check the signature of each individual assertion. This logic is followed regardless of this setting.

    Support SAML Authentication Request Signing / Decrypting Assertion

    When selected, enables the Select certificate by and Certificate identifier fields below, and uses the specified certificate to digitally sign outgoing SAML authentication requests and to decrypt inbound SAML assertions.
    Authentication requests are signed only when the IdP requests it—that is, when the IdP's metadata contains WantAuthnRequestsSigned="true".
    Signing and decryption are also necessary to participate in SAML Single Logout.

    Select certificate by

    Specifies how to find the signing/decryption certificate in the Windows Certificate Store or in the file system.
    If multiple valid certificates in the Windows Certificate Store match the criteria, only the oldest certificate (with the earliest Not After or Valid To property) is used to sign authentication requests, but any of the certificates are used for decryption. This behavior can be used for certificate rollover.
    When using the file system, an exact file path is specified, and only one certificate can match.

    Certificate identifier

    Enter the value of the parameter specified in Select certificate by (Subject Distinguished Name, Thumbprint, or file path) that identifies the desired certificate(s).
    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 you restart the FrameWorX server or re-apply the Global Settings dialog.

    Certificate password

    (Optional) Click to select the stored certificate password.

  3. Complete the settings in the SAML Authentication User Mapping section, and then click Apply.

    • Use this SAML claim—Specifies what information from the SAML token to use when mapping to an existing user. These rules apply when Security extracts information from the SAML token and assigns them to individual claims:

      • The <Subject> → <NameID> element gets mapped to claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier

      • Each value of an <Attribute> element gets mapped to a claim with the same name 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—Select the parameter of the GENESIS user settings to which the claim should be mapped. Learn more