[Breaking change] Drop `/api/security/v1/saml` route in favour of `/api/security/saml/callback`

[azasypkin]

Change description

Which release will ship the breaking change?

~8.0~ (Edit Joe 9/1/21: this is deprecated but we are not sure when we will get rid of it)

Describe the change. How will it manifest to users?

The /api/security/v1/saml route is no longer available, /api/security/saml/callback route must be used instead. This change should be reflected in Elasticsearch and Identity Provider SAML settings.

This change is external to Kibana and Kibana cannot know for sure if user needs to do anything. Kibana can only check if SAML is enabled in Kibana, but Elasticsearch can figure that out if it checks xpack.security.authc.realms.saml.{realm name}.sp.acs setting. Also some users may still use old route in server.xsrf.whitelist, we no longer need this setting, but if we notice that they still use it with the old route there will be a high chance they need to change their Elasticsearch and IdP configuration as well.

If users don't switch their configuration to /api/security/saml/callback they won't be able to log in with SAML (usually after login at the IdP users see just 404 generic error message).

How many users will be affected?

Everyone who uses SAML and still relies on the old route. I've seen a lot of such deployments in Cloud.

What can users do to address the change manually?

I'd suggest going through SAML Guide once again and pick up all the new changes we introduced for the past number of releases, including this one.

How could we make migration easier with the Upgrade Assistant?

If we can base our check on the current ES configuration (xpack.security.authc.realms.saml.{realm name}.sp.acs ) then we can pretty accurately say what needs to be changed on the ES side, and we should also ask users to double check if their IdP is configured to use the new route as well pointing them to the SAML Guide mentioned above.

Test Data

You can use Oktanaut to generate various SAML configurations for various versions and deployments (e.g. local or ESS). If you pick 7.8+ the config will use the new route, earlier versions will still rely on the old route.

Cross links

• Upgrade Assistant issue where we already discussed this.
• PR that implemented this change. (Edit Joe 9/1/21: this was reverted)

/cc @elastic/kibana-security

[elasticmachine]

Pinging @elastic/es-ui (Team:Elasticsearch UI)

[alisonelizabeth]

Hi @azasypkin! Can you clarify your comments under How could we make migration easier with the Upgrade Assistant? If I’m understanding correctly, it sounds like the best the Upgrade Assistant in Kibana could do is check if SAML is enabled and also if the server.xsrf.whitelist setting exists with the old route, and if so, warn the user that their Elasticsearch and IdP configuration may be change and point to the SAML docs. Does that sound right?

[azasypkin]

If I’m understanding correctly, it sounds like the best the Upgrade Assistant in Kibana could do is check if SAML is enabled and also if the server.xsrf.whitelist setting exists with the old route, and if so, warn the user that their Elasticsearch and IdP configuration may be change and point to the SAML docs. Does that sound right?

Hey @alisonelizabeth! Yep, with one caveat though: having old route in the server.xsrf.whitelist would make our guess much stronger, but this setting isn't required anymore and we ignore it. That means that users may still need to update their ES and IdP configuration even if server.xsrf.whitelist isn't used.

[alisonelizabeth]

I'm going to remove the Elasticsearch UI team label. Moving forward, this deprecation should be registered by the plugin owner via the core deprecations service (https://github.com/elastic/kibana/pull/94845). All registered deprecations will be displayed in the Upgrade Assistant (to be implemented via https://github.com/elastic/kibana/pull/97159). Feel free to reach out to myself or the core team with any questions!