From 8162cb9715e39b11e05102cde53d309228883842 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 30 Aug 2026 15:25:31 +0000 Subject: [PATCH 1/4] Document id provider flows and multi-provider autoLogin (XP 8.2.0) A vhost may restrict the flows an id provider serves; XP enforces login/autologin/logout and hands the list to the implementation as request.idProviderFlows for gating additional flows. autoLogin now runs for every enabled id provider with the autologin flow, default first. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01YFqoY5nKdmhXqM7MAU9cqU --- docs/images/xp-820.svg | 1 + docs/web/id-providers.adoc | 30 ++++++++++++++++++++++++++++-- docs/web/images/xp-820.svg | 1 + 3 files changed, 30 insertions(+), 2 deletions(-) create mode 100644 docs/images/xp-820.svg create mode 100644 docs/web/images/xp-820.svg diff --git a/docs/images/xp-820.svg b/docs/images/xp-820.svg new file mode 100644 index 00000000..cf359793 --- /dev/null +++ b/docs/images/xp-820.svg @@ -0,0 +1 @@ +XPXP8.2.08.2.0 diff --git a/docs/web/id-providers.adoc b/docs/web/id-providers.adoc index 0a16fd8a..2a5ae29c 100644 --- a/docs/web/id-providers.adoc +++ b/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 diff --git a/docs/web/images/xp-820.svg b/docs/web/images/xp-820.svg new file mode 100644 index 00000000..cf359793 --- /dev/null +++ b/docs/web/images/xp-820.svg @@ -0,0 +1 @@ +XPXP8.2.08.2.0 From 26c92ba4ed0dd176f84b47ffcae1b884659ebf20 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 30 Aug 2026 15:40:40 +0000 Subject: [PATCH 2/4] App upgrade notes for XP 8.2 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01YFqoY5nKdmhXqM7MAU9cqU --- docs/menu.json | 4 ++++ docs/upgrade/8-1.adoc | 2 +- docs/upgrade/8-2.adoc | 42 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 47 insertions(+), 1 deletion(-) create mode 100644 docs/upgrade/8-2.adoc diff --git a/docs/menu.json b/docs/menu.json index b5c11531..408a40aa 100644 --- a/docs/menu.json +++ b/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" } ] } diff --git a/docs/upgrade/8-1.adoc b/docs/upgrade/8-1.adoc index 0d6103fd..26c05dc6 100644 --- a/docs/upgrade/8-1.adoc +++ b/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 diff --git a/docs/upgrade/8-2.adoc b/docs/upgrade/8-2.adoc new file mode 100644 index 00000000..9605116a --- /dev/null +++ b/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. See <<../web/id-providers#flows, Flows>>. + +For code reaching the `VirtualHost` Java API through the <<../fundamentals/java-bridge#, Java bridge>>: `getIdProviderKeys()` and `getDefaultIdProviderKey()` are deprecated in favor of `getIdProviders()` — a map of the enabled ID providers to their flow lists, the default provider first. From 0329fd05a36deaef5064526b0e01fc5463ba97aa Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 30 Aug 2026 19:37:25 +0000 Subject: [PATCH 3/4] Mention the Standard ID Provider's basic flow in 8.2 upgrade notes Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01YFqoY5nKdmhXqM7MAU9cqU --- docs/upgrade/8-2.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/upgrade/8-2.adoc b/docs/upgrade/8-2.adoc index 9605116a..39d08be2 100644 --- a/docs/upgrade/8-2.adoc +++ b/docs/upgrade/8-2.adoc @@ -37,6 +37,6 @@ Then rebuild and deploy: == 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. See <<../web/id-providers#flows, Flows>>. +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()` and `getDefaultIdProviderKey()` are deprecated in favor of `getIdProviders()` — a map of the enabled ID providers to their flow lists, the default provider first. From 6462f458aeb1489fbd07d51d3130d6e4a50bdc08 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 31 Aug 2026 05:42:15 +0000 Subject: [PATCH 4/4] getIdProviders returns per-vhost id provider configuration beans Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01YFqoY5nKdmhXqM7MAU9cqU --- docs/upgrade/8-2.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/upgrade/8-2.adoc b/docs/upgrade/8-2.adoc index 39d08be2..92b1030b 100644 --- a/docs/upgrade/8-2.adoc +++ b/docs/upgrade/8-2.adoc @@ -39,4 +39,4 @@ Then rebuild and deploy: 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()` and `getDefaultIdProviderKey()` are deprecated in favor of `getIdProviders()` — a map of the enabled ID providers to their flow lists, the default provider first. +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.