Migrating the SAML IDP from the JSP-Loginapp to the Loginapp REST API/Loginapp REST UI

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

Migrating a SAML IDP 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 IDP.

Be aware of the limitations described in Limitations of SAML in the Loginapp REST API. In particular, a SAML IDP in the new loginapp cannot be used in conjunction with a SAML SP in the JSP-Loginapp.

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 IDP URLs gives an overview of the endpoint URLs.

To be backward-compatible for existing SPs and to reduce changes in existing IDP metadata files (idp.xml, idp-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 SPs when migrating to the Loginapp REST UI.

General migration instructions

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

  1. Unconnect the JSP-Loginapp SAML IDP configuration: Loginapp >> SAML Settings >> SAML IdP Settings (JSP Loginapp) and unconnect all target applications referring to the SAML IDP (plugins of type Target Application using SAML 2.0).
  2. Create the IDP configuration as described in SAML IDP 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 idp-extended.xml as described below.
  3. For every Target Application using SAML 2.0 defined in the JSP-Loginapp's Application Settings, create a corresponding SP configuration as described in Adding SAML SPs to the IDP configuration for the Loginapp REST API . Consider the following points:
    • Refer to the existing SAML metadata files and the sp-extended.xml as described below.
  4. Remove the JSP-Loginapp SAML IDP configuration: Loginapp >> SAML Settings >> SAML IdP Settings (JSP Loginapp).
  5. In the federation settings Loginapp >> SAML Settings >> SAML Federation Settings, change the Error Page URL to ui/app/error/message.

The SAML IDP 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).

Adapt the extended IDP metadata file (idp-extended.xml) as follows:

  • Remove the attribute tag with the name AuthUrl. It is no longer needed.
  • 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.
  • Remove the three attribute tags with the following names. (they may still be configured in Loginapp >> SAML Settings >> SAML Federation Settings if custom mapper plugins have been used).
    • <Attribute name="idpAuthncontextMapper">...</Attribute>
    • <Attribute name="idpAccountMapper">...</Attribute>
    • <Attribute name="idpAttributeMapper">...</Attribute>

Adapt the extended SP metadata files (e.g. sp1-extended.xml) as follows:

  1. 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.

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.

To migrate the attribute map settings, proceed as follows:

  1. Go through all SP target applications of the JSP-Loginapp (Loginapp >> Application Settings >> Target Applications (or Default Target Application).
  2. 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.
  3. 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.
  4. 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.

The JSP-Loginapp SAML IDP allowed using special identifiers such as USER_ID and GRANTED_ROLES. The following hints help to get the same result in the new SAML IDP,

Identifier (JSP-Loginapp)

Attribute Plugin (Loginapp REST API/UI)

USER_ID

Username SAML 2.0 Attribute

GRANTED_ROLES

Use the Roles SAML 2.0 Attribute plugin with a combination of All User Roles (user's roles in the database) and Tag-based Role Provider (acquired roles) as role providers. To filter and/or transform roles, additionally use the Transforming Role Provider.

AUDIT_TOKEN

Audit-Token SAML 2.0 Attribute

Host

IP SAML 2.0 Attribute

authMethod

AuthnContextClassRef URI SAML 2.0 Attribute
See Authentication context classes in the SAML IDP for further information.

LANG

Display Language SAML 2.0 Attribute

AUTH_TOKEN_ID

Auth Token ID SAML 2.0 Attribute

Configuration hints

Activate the configuration to make the changes effective.

Make sure to use an up-to-date Airlock Gateway mapping template file (7.6 or newer) and activate the SAML allow rule.

If any of the SAML metadata files are changed, a restart of the IAM instance may be necessary.