diff --git a/docs/upgrade.adoc b/docs/upgrade.adoc index 6f96dc45..800bc584 100644 --- a/docs/upgrade.adoc +++ b/docs/upgrade.adoc @@ -12,7 +12,7 @@ Set the platform version in _gradle.properties_ to the release you are targeting [source,properties] ---- -xpVersion = 8.1.0 +xpVersion = 8.2.0 ---- TypeScript projects also need the matching type definitions, or the parameters and functions added in the release will not type-check: @@ -22,8 +22,8 @@ TypeScript projects also need the matching type definitions, or the parameters a ---- { "devDependencies": { - "@enonic-types/global": "^8.1.0", - "@enonic-types/lib-content": "^8.1.0" + "@enonic-types/global": "^8.2.0", + "@enonic-types/lib-content": "^8.2.0" } } ---- @@ -34,6 +34,23 @@ Then rebuild and deploy: The app builds and runs. What follows is work that can be done at your own pace. +[#xp-8-2] +== XP 8.2 + +No breaking changes for application code. The rest of this section concerns ID provider implementations. + +=== 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 <>. + +=== Deprecations + +For code reaching the `VirtualHost` Java API through the <>: `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. + [#xp-8-1] == XP 8.1 diff --git a/docs/web/id-providers.adoc b/docs/web/id-providers.adoc index 6c43fc29..1742078c 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