Migrating the SAML SP from the JSP-Loginapp to the Loginapp REST API and UI

The following information helps to migrate an existing SAML SP configuration from the JSP-Loginapp to the Loginapp REST API and Loginapp REST UI.

Migrating a SAML SP from the JSP-Loginapp to the Loginapp REST API/Loginapp REST UI is a manual process not covered by the automatic config migration. The following guide helps with such a migration.

You should plan the migration in advance in order to ensure adequate testing. We strongly advise you to test your various SAML use cases after the migration of the SP.

Be aware of the limitations described in Limitations of SAML in the Loginapp REST API

Use legacy SAML endpoint URLs

The SAML implementation comes with new SAML endpoints (URLs) but still supports the SAML endpoint URLs (legacy URLs) of the JSP-Loginapp.

SAML SP URLs gives an overview of the endpoint URLs.

To be backward-compatible for existing IDPs and to reduce changes in existing SP metadata files (sp.xml, sp-extended.xml) to a minimum, use the legacy URLs.

As long as the domain name and base URL do not change, there is no need to inform existing remote IDPs when migrating to the Loginapp REST UI.

General migration instructions

To migrate the SP configuration from the JSP-Loginapp to the Loginapp REST API and Loginapp REST UI, proceed as follows:

  1. Unconnect the JSP-Loginapp SAML SP configuration: Loginapp >> SAML Settings >> SAML SP Settings (JSP Loginapp) and unconnect all target applications referring to the SAML SP (plugins of type Target Application using identity propagator).
  2. Create the SP configuration as described SAML SP configuration for the Loginapp REST API considering the following points:
    • Refer to existing key store files instead of creating new ones.
    • Refer to existing SAML metadata files and the sp-extended.xml as described below.
  3. Remove the JSP-Loginapp SAML IDP configuration: Loginapp >> SAML Settings >> SAML IdP Settings (JSP Loginapp).
  4. Create a new IDP configuration as described Adding SAML IDP to the SP configuration for the Loginapp REST API. Consider the following points:
    • Refer to the existing SAML metadata files and the idp-extended.xml as described below.
  5. In the federation settings Loginapp >> SAML Settings >> SAML Federation Settings, change the Error Page URL to ui/app/error/message.

The SAML SP implementations of JSP Loginapp and the Loginapp REST API cannot be used simultaneously. Not even using configuration contexts.

Adapt the extended metadata files

Some settings that were stored in the extended metadata files in the JSP-Loginapp were moved to the IAM configuration (Config Editor).

  1. Adapt the extended SP metadata files (e.g. sp1-extended.xml) as follows:
  2. If there is an attribute tag with the name attributeMap, remember its contents, remove it from the XML and follow the steps regarding attribute mapping further below.
  1. Adapt the extended IDP metadata file (idp-extended.xml) as follows:
  2. Remove the attribute tag with the name AuthUrl. It is no longer needed.
  3. If there is an attribute tag with the name attributeMap, remember its contents, remove it from the XML and follow the steps regarding attribute mapping further below.
  4. Remove the three attribute tags with the following names:
    • <Attribute name="idpAuthncontextMapper">...</Attribute>
    • <Attribute name="idpAccountMapper">...</Attribute>
    • <Attribute name="idpAttributeMapper">...</Attribute>

    Theses attribute tags may still be configured in Loginapp >> SAML Settings >> SAML Federation Settings if custom mapper plugins have been used the.

Attribute mapping

The IDP configuration defines what attributes are sent to the remote SPs in the SAML assertions. Attributes may include roles, user context data, and more.

  • In the JSP-Loginapp, attributes may be configured in the following places:
  • Extended SP metadata file (e.g. sp1-extended.xml)
  • Extended IDP metadata file (idp-extended.xml)
  • In the Target Application using SAML 2.0 plugin (Config Editor)

In the Loginapp REST API, attributes are only configured in the SP configuration:
Loginapp >> SAML Settings >> SAML IdP Settings (Flow Auth) >> SAML 2.0 Service Provider

  1. To migrate the attribute map settings, proceed as follows:
  2. Go through all SP target applications of the JSP-Loginapp (Loginapp >> Application Settings >> Target Applications (or Default Target Application).
  3. Look at the referenced extended SAML metadata file (e.g. sp1-extended.xml). If it contains an attributeMap attribute, configure all listed attributes in the new SP configuration.
  4. For all attributes found in the target application's Attributes property:
    • Add it to the new SP configuration.
    • If the attribute's name collides with an attribute from the extended SP metadata file: use the one from the IAM configuration and delete the one from the metadata file.
  5. If the extended IDP metadata file (idp-extended.xml) contains an attributeMap attribute: For all SAML target applications that do not specify attributes (neither in the metadata file nor in the target application configuration), add the attributes found in the extended IDP metadata file to the new SP configuration.