Proposal: atomic, idempotent import of authentication flows through the admin API #53784

xgp · 2026-10-09T08:34:05Z

xgp
Oct 9, 2026

Status (updated 2026-10-21): The design below reflects the discussion so far with @ahus1. We are waiting on feedback from the maintainers who own authentication before opening a PR against Keycloak. A working implementation is in p2-inc/keycloak-atomic-auth-flows#7. The original proposal is collapsed at the bottom.

The problem

Authentication flows are the highest-stakes configuration in a realm: if a flow is wrong, nobody logs in. Both the admin console and the admin REST API change flows incrementally. Adding an execution, setting its requirement, creating a subflow and moving executions into it are all separate requests. Each one commits on its own, against a flow that is already bound and serving logins. Between those commits the realm runs a flow nobody designed: an empty subflow, a REQUIRED OTP step whose config does not exist yet, or an ALTERNATIVE removed before its replacement was added.

Terraform, keycloak-config-cli and scripts make the same incremental calls, only faster. Partial import does not cover authentication flows, and a full realm import is far too blunt for a flow change.

What is missing is a single admin API request that takes a flow tree and its authenticator configs, validates all of it, and applies it in one transaction or not at all.

Proposed first step for core

Keep it as small as possible: create or replace one or more top-level flows, with validation, and no bindings.

Payload. Top-level flows, their subflows, and the authenticator configs they reference. It uses the existing AuthenticationFlowRepresentation and AuthenticatorConfigRepresentation from realm export JSON. Subflows are referenced by flowAlias and configs by alias. The payload carries no ids. See the example below.
Create or replace by alias. A top-level flow that doesn't exist is created. A flow that exists is replaced in place: it keeps its id, so realm, client and IdP bindings keep pointing at it. Its executions and subflows are rebuilt from the payload. Subflows that drop out are deleted, and configs are upserted by alias.
Logins in progress restart. Replaced executions get new ids. A login part way through the old flow can't find its step, so it restarts on the new flow. If an admin replaces a flow to require a second factor, a login that started before the change can't finish without it.
Identical re-post is a no-op. Each flow and config in the payload is compared with what the realm has now, and only missing or different ones are written. Nothing is stored about previous imports. An identical re-post rewrites nothing, so ids stay the same and logins in progress are not disturbed. A flow that matches keeps its executions even when other flows in the same payload change. A flow edited in the console since the last import is detected and rewritten.
Scope. Only the flows named in the payload are touched. Nothing is pruned.
Built-in flows are rejected, matching the admin console.
Validation before any write. Any of the following returns 400 and writes nothing:
- an unknown flow type (providerId);
- an authenticator that isn't deployed, looked up in the SPI the parent flow type uses;
- a dangling subflow or config reference;
- a subflow structure that isn't a tree: a top-level flow used as a subflow, a subflow with two parents, or an orphaned or cyclic subflow;
- a flow switching between top-level and subflow;
- a subflow that a flow outside the payload also uses.
One transaction. All of it commits together or not at all.

Example on the wire

This replaces (or creates) the top-level flow browser with otp. Its forms subflow requires OTP after the password:

POST /admin/realms/{realm}/authentication/...   (endpoint location: see open questions)
Content-Type: application/json

{
  "authenticationFlows": [
    {
      "alias": "browser with otp",
      "description": "Cookie, IdP redirect, or username/password followed by OTP",
      "providerId": "basic-flow",
      "topLevel": true,
      "authenticationExecutions": [
        { "authenticator": "auth-cookie", "requirement": "ALTERNATIVE", "priority": 10 },
        {
          "authenticator": "identity-provider-redirector",
          "authenticatorConfig": "redirect to corporate idp",
          "requirement": "ALTERNATIVE",
          "priority": 20
        },
        {
          "authenticatorFlow": true,
          "flowAlias": "browser with otp forms",
          "requirement": "ALTERNATIVE",
          "priority": 30
        }
      ]
    },
    {
      "alias": "browser with otp forms",
      "providerId": "basic-flow",
      "topLevel": false,
      "authenticationExecutions": [
        { "authenticator": "auth-username-password-form", "requirement": "REQUIRED", "priority": 10 },
        { "authenticator": "auth-otp-form", "requirement": "REQUIRED", "priority": 20 }
      ]
    }
  ],
  "authenticatorConfig": [
    {
      "alias": "redirect to corporate idp",
      "config": { "defaultProvider": "corporate-oidc" }
    }
  ]
}

This exact payload was posted to Keycloak 26.8 running the extension:

The first post creates both flows.
Posting it again is a no-op.

The extension's test suite covers replacing a changed payload in place under the same flow id.

Fields left out (builtIn, userSetupAllowed, authenticatorFlow: false) take their usual defaults. The extension responds with 200, echoes the payload, and adds X-Import-Result: applied or unchanged. The response shape for core is open for discussion.

Follow-ups (separate PRs, not in the first cut)

Dry run. dryRun=true runs the whole request, including validation, then rolls it back and returns the same result and errors. Useful as a CI check. Already in the extension.
Export. Return one or more top-level flows in the same format, so a flow edited in the console can be exported into config-as-code and posted back unchanged. The admin console could use the same API for export and import. Already in the extension.
Bindings. Bind the imported flows in the same transaction: realm browser, registration, direct grant, reset credentials, client authentication, docker auth and first broker login; IdP first and post broker login; and client browser and direct grant overrides. The extension covers a subset of these.
Whole-set import with pruning, if there is a consistency or business need.
Built-in flows, which needs a separate discussion.

Open questions

Where it lives. A new endpoint under /admin/realms/{realm}/authentication/ (for example .../authentication/flows/import), or authenticationFlows and authenticatorConfig support in partialImport? Partial import's OVERWRITE policy deletes and recreates, so it would need the replace-in-place behaviour above to keep flow ids stable.
Response. Should the response report what happened to each flow (created, replaced, unchanged), or just return 204?
Configs. Configs are upserted and never deleted, because other flows may share them. Should orphaned configs that were only used by a replaced flow be cleaned up?

Reference implementation

Extension: https://github.com/p2-inc/keycloak-atomic-auth-flows (in Gusto's production for about a year, in its original versioned mode)
Replace mode, validation, dry run, export, and tests including real browser logins that restart mid-flow: Add replace import mode: overwrite flows in place, idempotent, no history p2-inc/keycloak-atomic-auth-flows#7

We can contribute the PR, with tests ported to the Keycloak test framework and documentation, once the shape is agreed.

Original proposal

Context

At the Keyconf26 group discussion yesterday we presented an extension that Phase Two built with Gusto for applying authentication-flow changes as a single transactional request. Alexander Schwartz suggested a simplified version could be a candidate for Keycloak core, and asked that we open a discussion here before any PR. This is that discussion.

The extension is open source and has been running in Gusto's production environment for about a year:

Repository: https://github.com/p2-inc/keycloak-atomic-auth-flows
Config-as-code worked example (builder, validator, update script): https://github.com/p2-inc/keycloak-atomic-auth-flows/tree/main/examples
Raw example payloads: https://github.com/p2-inc/keycloak-atomic-auth-flows/tree/main/src/test/resources/json
Integration tests (Testcontainers against a real Keycloak): https://github.com/p2-inc/keycloak-atomic-auth-flows/blob/main/src/test/java/io/phasetwo/keycloak/rest/AuthenticationFlowsResourceApiTest.java

The problem

Authentication flows are the highest-stakes configuration in a realm: if a flow is wrong, nobody logs in. They are also the configuration Keycloak gives the least protection while changing.

Both the admin console and the admin REST API mutate flows incrementally. Adding an execution is one request, setting its requirement is another, creating a subflow and moving executions into it is several more, and each request commits on its own against a flow that is already bound and serving live logins. Between those commits the realm is running a flow nobody designed: an empty subflow, a REQUIRED OTP step whose config does not exist yet, an ALTERNATIVE removed before its replacement was added.

The usual workarounds do not close that window:

Copy the built-in flow, edit the copy, re-bind. This is what careful operators do by hand. It works, but it is a manual, multi-step process in the console and nothing about it is repeatable from a pipeline.
Terraform / keycloak-config-cli / scripts against the REST API. These still issue the same sequence of incremental requests, so the intermediate states are the same. They are just faster.
Partial import does not cover authentication flows or authenticator configs.
Full realm export/import is far too blunt for a flow change.

What is missing is a single admin API request that takes the whole set of flows, their authenticator configs, and the bindings that make them live, validates all of it, and applies it in one transaction or not at all.

What the extension does today

It registers a realm admin resource:

POST /admin/realms/{realm}/authentication-flow/import[?force=true]

The payload carries everything needed for a complete change:

Field	What it sets
`authenticationFlows`	`AuthenticationFlowRepresentation[]`, including executions and subflows
`authenticatorConfig`	`AuthenticatorConfigRepresentation[]` referenced by alias from the executions
`browserFlowBinding`	Flow alias to bind as the realm browser flow
`idpFlowBindings[]`	Per identity provider: first broker login and post broker login flow
`clientFlowBinding`	Per client: browser and direct grant flow overrides

Flows, configs, executions and every binding are applied inside one Keycloak transaction. Any failure (dangling subflow or config reference, unknown IdP alias, unknown client) rolls the whole import back. The caller needs manage-realm.

One design choice worth explaining up front, since the README does not motivate it well. The server hashes the flows and configs in the payload and prefixes every flow and config alias with that hash. An import never edits a flow that exists; it creates a new, independently bindable set and moves the bindings onto it. Re-posting an identical payload is detected and rejected with 409, and force=true re-applies the bindings over the already-imported set.

That was a Gusto requirement for rollback and compliance: the flow that was serving traffic a moment ago is still in the realm, intact, and rolling back is re-posting the previous payload with force=true. It also means in-flight authentication sessions keep running against the executions they started on, because nothing they reference is deleted.

The cost is the one Alexander raised on Slack: it is not idempotent in the Terraform sense. Each edit adds a new set of flows, the realm accumulates old versions, and somebody has to clean them up. For a core feature that is the wrong default.

What we would propose for core: start simple

A single idempotent request with replace-by-alias semantics and no history:

Payload: flows (with executions and subflows), authenticator configs, and bindings, essentially the table above.
Semantics: for every top-level flow alias in the payload, the realm ends up matching the payload. Missing flows are created, existing flows have their executions, subflows and configs replaced. Running the same request twice is a no-op with the same success response.
Validation before any write: unknown authenticator provider ids, dangling subflow or config references, unknown IdP alias or client id all return 400 and nothing is applied.
One transaction: the whole payload, bindings included, commits together or not at all.

The versioned-history behaviour could come later as an opt-in (keep the previous N versions, keep forever), if there is interest. It should not be in the first cut.

Discussion points

Where it lives. A new endpoint under /admin/realms/{realm}/authentication/...? An extension of partialImport with authenticationFlows and authenticatorConfig sections honouring the existing OVERWRITE / SKIP / FAIL policy? Something else that better matches admin API conventions?
Replace in place or recreate. Replacing executions inside an existing flow keeps the flow id stable, so existing bindings (realm, client override, IdP) that reference the id keep working. Delete-and-recreate is simpler but changes ids. In-place replacement also has to answer what happens to an authentication session that is mid-flow when its executions are swapped. Today any flow edit has that problem, but a bulk replace makes it more visible.
Scope of the payload. Only the aliases named in the payload are touched (partial update), or the payload is the declarative set of all non-built-in flows and anything else is pruned? A prune flag could support both.
Built-in flows. Should the import be allowed to replace the contents of a built-in flow, or only create and replace custom ones?
Bindings coverage. The extension covers the realm browser flow, IdP first/post broker login, and client browser/direct grant overrides because that is what Gusto needed. Core should probably cover every realm binding (browser, registration, direct grant, reset credentials, client authentication, docker auth, first broker login) plus the IdP and client ones.
Dry run. A dryRun=true that runs full validation and returns the errors without writing would make this very useful from CI.
Admin console. We have a prototype export/import UI for the flow tree in the console. Worth bringing into the same discussion, or keep the API first?

What we can contribute

A PR with the endpoint and representation, the validation, tests ported from the extension's Testcontainers suite to the Keycloak test framework, and documentation. Happy to adjust the shape to whatever the maintainers prefer. Feedback on the points above would help us land on the right design before writing code.

ahus1 · 2026-10-14T19:54:15Z

ahus1
Oct 14, 2026
Collaborator

@xgp - thanks for summarizing this. I think the discussion at KeyConf26 and also discussions at other events show that there is a high interest in atomic import of authentication flows.

Let's try to start as simple as possible.

Replace in place or recreate. Replacing executions inside an existing flow keeps the flow id stable, so existing bindings (realm, client override, IdP) that reference the id keep working. Delete-and-recreate is simpler but changes ids.

I'd vote for a replace in-place - see below.

In-place replacement also has to answer what happens to an authentication session that is mid-flow when its executions are swapped. Today any flow edit has that problem, but a bulk replace makes it more visible.

When I as an admin make a change to for example enforce a second factor, why should anyone who started an authentication flow be allowed to continue without it without a 2FA? With that security hat on, replacing vs. duplicated flow is no longer a question: If a (significant) change in the logic of the flow is detected, the authentication should restart.

Scope of the payload. Only the aliases named in the payload are touched (partial update), or the payload is the declarative set of all non-built-in flows and anything else is pruned? A prune flag could support both.

Is there a need to consistently change all flows at the same time? Could this be a replacement by flow to start with? I could still see the point of replacing all flows together, and pruning, but that could be a second step if there is a consistency/business need.

Built-in flows. Should the import be allowed to replace the contents of a built-in flow, or only create and replace custom ones?

Today you can't change built-in flows in the UI. Allowing that via the API would spin off a longer discussion. Let's postpone any update of built-in flows.

Bindings coverage. The extension covers the realm browser flow, IdP first/post broker login, and client browser/direct grant overrides because that is what Gusto needed. Core should probably cover every realm binding (browser, registration, direct grant, reset credentials, client authentication, docker auth, first broker login) plus the IdP and client ones.

We need to start somewhere. Would it make sense to start with flows without the binding, assuming that this is doing only create or replace?

Dry run. A dryRun=true that runs full validation and returns the errors without writing would make this very useful from CI.

Sounds like a great addition. Could still be a follow-up. Having a validation when updating a flow (with or without a dry run) sounds like a great improvement.

Admin console. We have a prototype export/import UI for the flow tree in the console. Worth bringing into the same discussion, or keep the API first?

I've seen myself changing a client in the UI, and then exporting it as JSON to include it in some configuration-as-code. I might want to do the same in the Admin UI. Export and import could also be a manual staging process, or a backup-restore process.
Definitely useful, but I'd starte with the API. Maybe the same API can be used from the UI.

0 replies

xgp · 2026-10-16T11:53:44Z

xgp
Oct 16, 2026
Author

Thanks @ahus1, agreed on all points. We have a PR in the extension (p2-inc/keycloak-atomic-auth-flows#7) so there's something concrete to look at:

Replace in place. Flows keep their alias and id, so existing realm, client and IdP bindings keep resolving. An identical re-post is a no-op.
Logins in progress. All executions get new ids on replace, so a login part way through the old flow can't find its step and restarts on the new flow. A newly required 2FA therefore applies immediately. A no-op re-post doesn't affect anyone. This is tested with real browser logins.
Scope. Only the flows named in the payload are touched, with no pruning. Built-in flows are rejected.
Validation before any write. Unknown authenticator or flow types, dangling references, and a subflow tree that isn't a tree (shared, orphaned or cyclic subflows) are all rejected. So is replacing a flow that a flow outside the payload uses as a subflow.
Dry run. ?dryRun=true runs everything and rolls back, returning the same result and errors.
Export. GET .../export?alias=... returns a flow tree in the import format, which covers the export-from-the-UI case and could back a console feature later.

For core, we'd propose the smallest version first: replace-by-flow with validation and no bindings. Dry run and export would follow as separate PRs. Does that work? And would you rather see this as a new endpoint under /admin/realms/{realm}/authentication/, or as authenticationFlows support in partialImport?

0 replies

ahus1 · 2026-10-16T17:26:56Z

ahus1
Oct 16, 2026
Collaborator

Good to see we're aligned. I left a comment in the PR.

Now I would need to get other maintainers on board / the team that owns the authentication parts. Let's wait for some feedback from them before creating the PR to the main repo. We're pretty busy until end of October, but I hope there will be feedback in November the latest.

To advocate for a solution, maybe update the description at the top with the current state of the discussion, plus an example JSON of a flow as it appears on the wire.

0 replies

xgp · 2026-10-21T12:26:52Z

xgp
Oct 21, 2026
Author

Following the contribution guidelines, I opened an issue for this: #54229.

I've also updated p2-inc/keycloak-atomic-auth-flows#7 per @ahus1's review. The stored payload hash in the realm attribute is gone. Each flow and config in the payload is now compared with the realm as it is now, and only missing or different ones are written. As a result, a flow edited in the console since the last import is detected and rewritten. A flow that matches keeps its execution ids even when other flows in the payload change. The description above reflects this.

0 replies

Navigation Menu

Repository navigation

Proposal: atomic, idempotent import of authentication flows through the admin API #53784

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Context

The problem

What the extension does today

What we would propose for core: start simple

Discussion points

What we can contribute

Replies: 4 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Proposal: atomic, idempotent import of authentication flows through the admin API #53784

Uh oh!

Uh oh!

xgp Oct 9, 2026

The problem

Proposed first step for core

Example on the wire

Follow-ups (separate PRs, not in the first cut)

Open questions

Reference implementation

Context

The problem

What the extension does today

What we would propose for core: start simple

Discussion points

What we can contribute

Replies: 4 comments

Uh oh!

ahus1 Oct 14, 2026 Collaborator

Uh oh!

Uh oh!

xgp Oct 16, 2026 Author

Uh oh!

ahus1 Oct 16, 2026 Collaborator

Uh oh!

xgp Oct 21, 2026 Author

xgp
Oct 9, 2026

ahus1
Oct 14, 2026
Collaborator

xgp
Oct 16, 2026
Author

ahus1
Oct 16, 2026
Collaborator

xgp
Oct 21, 2026
Author