ID provider flows and multi-provider autoLogin (XP 8.2.0)

docs/menu.json

@@ -335,6 +335,10 @@
         {
           "title": "XP 8.0 to 8.1",
           "document": "upgrade/8-1"
+        },
+        {
+          "title": "XP 8.1 to 8.2",
+          "document": "upgrade/8-2"
         }
       ]
     }

docs/upgrade/8-1.adoc

@@ -4,7 +4,7 @@
 
 XP 8.1 makes no breaking changes to application code: an app built for 8.0 runs on 8.1 as it is. The upgrade is a version bump, followed by the clean-ups below. Every API deprecated in 8.1 still works, and every replacement ships with 8.1.0, so the clean-ups can be done one at a time.
 
-Coming from XP 7? Do <<../upgrade#, Upgrading Enonic apps from XP 7 to XP 8>> first — this page picks up where that one ends.
+Coming from XP 7? Do <<../upgrade#, Upgrading Enonic apps from XP 7 to XP 8>> first — this page picks up where that one ends. Already on XP 8.1? See <<8-2#, Upgrading Enonic apps from XP 8.1 to 8.2>>.
 
 == Version bump
 

docs/upgrade/8-2.adoc

@@ -0,0 +1,42 @@
+= Upgrading Enonic apps from XP 8.1 to 8.2
+:toc: right
+:imagesdir: ../images
+
+XP 8.2 makes no breaking changes to application code: an app built for 8.1 runs on 8.2 as it is. The upgrade is a version bump; the rest of this page concerns ID provider implementations.
+
+Coming from XP 8.0? Do <<8-1#, Upgrading Enonic apps from XP 8.0 to 8.1>> first — this page picks up where that one ends.
+
+== Version bump
+
+Set the platform version in _gradle.properties_:
+
+[source,properties]
+----
+xpVersion = 8.2.0
+----
+
+TypeScript projects also need the matching type definitions, or the properties added in 8.2 will not type-check:
+
+.package.json
+[source,json]
+----
+{
+  "devDependencies": {
+    "@enonic-types/global": "^8.2.0"
+  }
+}
+----
+
+Then rebuild and deploy:
+
+  enonic project deploy
+
+== autoLogin may run where it did not before
+
+`autoLogin` now runs for every ID provider enabled on the request's virtual host — the `default` provider first — until one of them authenticates the request or returns a response. Previously only the `default` provider's `autoLogin` ran, so a provider configured as `enabled` will now have its `autoLogin` called on requests where it never ran before. Implementations that quietly return when they find no credentials to act on — the common shape — need no change.
+
+== Worth adopting: flow gating
+
+A vhost may now restrict the flows an ID provider serves. XP enforces `login`, `autologin` and `logout` itself, and hands the configured list to the implementation as `request.idProviderFlows` — absent when no restriction applies. An ID provider with custom `GET`/`POST` endpoints can gate additional flows of its own on it, letting administrators enable or disable those endpoints per vhost — the Standard ID Provider gates its (deprecated) basic authentication on the additional `basic` flow this way. See <<../web/id-providers#flows, Flows>>.
+
+For code reaching the `VirtualHost` Java API through the <<../fundamentals/java-bridge#, Java bridge>>: `getIdProviderKeys()` is deprecated in favor of `getIdProviders()` — a map of the enabled ID providers to their per-vhost configuration (flow lists today), the default provider first.

docs/web/id-providers.adoc

@@ -43,7 +43,7 @@ Rather than hardcoding these paths, generate them with the portal library helper
 
 [NOTE]
 ====
-The endpoint is *mounted* everywhere, but an ID provider only *activates* for a request when it is bound to the request's virtual host. The vhost mapping declares which ID provider(s) apply, and the one marked `default` is the provider whose `autoLogin` filter runs. See the https://developer.enonic.com/docs/platform/xp8/config/vhosts[vhost configuration] for the binding rules.
+The endpoint is *mounted* everywhere, but an ID provider only *activates* for a request when it is bound to the request's virtual host. The vhost mapping declares which ID provider(s) apply and, optionally, <<#flows, which flows>> each of them serves. See the https://developer.enonic.com/docs/platform/xp8/config/vhosts[vhost configuration] for the binding rules.
 ====
 
 == Descriptor
@@ -127,7 +127,7 @@ If no user already exists in the context, the autoLogin filter is executed early
 
 [NOTE]
 ====
-`autoLogin` works only for identity providers that are configured as `default` in the virtual host mapping. Visit the https://developer.enonic.com/docs/platform/xp8/config/vhosts[vhost configuration] section for more details.
+image:xp-820.svg[XP 8.2.0,opts=inline] `autoLogin` runs for every ID provider on the request's virtual host that has the `autologin` <<#flows, flow>> enabled — the `default` provider first — until one of them authenticates the request or returns a response. In earlier versions only the `default` provider's `autoLogin` ran. Visit the https://developer.enonic.com/docs/platform/xp8/config/vhosts[vhost configuration] section for more details.
 ====
 
 
@@ -138,6 +138,32 @@ Communication with the implementation is handled via the ID provider endpoint.
 
 The URL to this endpoint can be generated using the <<../libraries/lib-portal#idproviderurl, idProviderUrl() function in the portal library>>
 
+[#flows]
+== Flows
+
+image:xp-820.svg[XP 8.2.0,opts=inline] A vhost mapping may restrict the flows an ID provider serves, with a flow list on its `enabled` value — e.g. `+default&enabled=login,autologin+`. XP itself enforces the three flows it manages:
+
+login:: `handle401` and the `login` function.
+autologin:: the `autoLogin` filter.
+logout:: the `logout` function.
+
+Any other name in the list addresses an *additional flow* of the ID provider application itself. XP dispatches the custom `GET`/`POST` functions regardless of the list, and instead hands the list to the implementation as `request.idProviderFlows` — a sorted array of the configured flow names. The property is absent when the vhost applies no flow restriction (and on XP versions before 8.2.0), so an absent list means every flow is enabled.
+
+Use it to serve an endpoint only where its flow is listed. For example, an ID provider offering a device authorization flow can gate it on the name `device`:
+
+[source,typescript]
+----
+export function POST(request: Request) {
+    const flows = request.idProviderFlows;
+    if (flows && flows.indexOf('device') < 0) {
+        return { status: 403 };
+    }
+    // serve the device authorization endpoint
+}
+----
+
+An administrator then enables the endpoint per vhost by listing the flow — `+enabled=autologin,device+` — and disables it by leaving it out. Document the additional flows your ID provider supports, so administrators know what the names mean.
+
 == Sample
 The code below demonstrates how an ID provider may be implemented