SCA and Credential Management UI: Keycloakify or External Frontend? #54611

Batev · 2026-11-03T21:33:40Z

Batev
Nov 3, 2026

Hi everyone,

We are integrating our existing SCA services with Keycloak and deciding how to build the following screens:

SCA: Challenge verification and enrollment, including SMS/TOTP and custom scenarios.
Credential management: Setting, changing, resetting, and removing credentials or authentication methods.

Login will remain hosted by Keycloak. We expect to use built-in authenticators for standard login and custom authenticators for SCA, with our backend services handling SCA challenge creation and verification.

Approaches under consideration

Keycloakify: A dedicated Keycloakify project covering login, SCA, and credential-management screens, all hosted by Keycloak.
External frontend: A separate frontend covering SCA and credential management, while login remains within Keycloak.

Potential benefits of the external frontend

Independent deployment: Release changes without updating a Keycloak theme.
Reuse: Use the same screens in other applications or initiatives.
Standalone UI lifecycle: Develop and maintain these screens independently of Keycloak's theme structure.

Keycloakify would keep all screens, including login, in one project with shared styling and fewer cross-application redirects. An external frontend would require maintaining the Keycloak login theme separately.

Questions for the community

Which approach would you recommend for this use case, considering security, integration complexity, and long-term maintenance?

Are there limitations around external SCA or credential-management screens that would make Keycloakify the better choice?

Thanks!

Dv2Corn · 2026-11-03T23:34:32Z

Dv2Corn
Nov 3, 2026

I'd split it by what each screen does, not by which project it lives in. The pages that create, verify, change or remove a credential should run inside Keycloak, as authenticators and required actions. An external frontend works fine as the "security settings" page that lists credentials and starts those flows. So the choice isn't Keycloakify vs. external. Keycloakify (or plain FreeMarker/React themes) is just how you style the in-Keycloak pages.

Why credential operations should stay in Keycloak:

An external app has no user-level API to create or verify a credential. The Account REST API (/realms/{realm}/account/credentials) only lists credential types and the user's credentials, and edits labels. Removal through it is deprecated in favor of an action (AccountCredentialResource.java#L296-L308). The only other way is the Admin REST API with a service account that has manage-users. Your frontend/BFF then becomes the security boundary for every user's credentials.
When the same operation runs as an Application Initiated Action (AIA), Keycloak adds the protections for you:
- Re-authentication if the last login is older than the action's max age (5 minutes by default).
- Step-up: adding or deleting a 2nd-factor credential requires authenticating with an existing credential of that level.
- Events: UPDATE_CREDENTIAL, REMOVE_CREDENTIAL and so on.
See Application initiated actions. The same page says: "relying on the Account Console is best instead of managing credentials from your own applications" (L73-L75).

How the external frontend fits in:

List what the user has: GET /realms/{realm}/account/credentials with the user's access token (needs manage-account or view-profile). Each type comes with its createAction/updateAction and removeable flag.
For any change, redirect to the normal authorization endpoint with kc_action:

GET /realms/{realm}/protocol/openid-connect/auth
    ?client_id=security-portal&response_type=code&scope=openid
    &redirect_uri=https://portal.example.com/security/callback
    &code_challenge=...&code_challenge_method=S256
    &kc_action=CONFIGURE_TOTP          # or UPDATE_PASSWORD, webauthn-register,
                                       # delete_credential:<credentialId>,
                                       # <your-custom-required-action-id>

Keycloak returns to redirect_uri with kc_action=<alias>&kc_action_status=success|cancelled|error (OIDCLoginProtocol.java#L277-L284). Don't treat that as proof: the docs warn the user can strip kc_action. Re-read the credential list, or check acr, before relying on it.

For your custom SCA methods (SMS, your backend's challenges):

Implement a CredentialProvider whose getCredentialTypeMetadata() sets createAction to your own RequiredActionProvider (the enrollment page; mark it CredentialRegistrator).
Add an Authenticator for the challenge step during login/step-up.

The docs' secret-question example shows the wiring (auth-spi.adoc#L650-L671). Your required action then shows up in the Account Console's "Set up" button automatically, and works as kc_action=<id> from your own frontend. Its templates are login-theme pages, so they're styled together with login (Keycloakify handles that well).

On your listed benefits:

Independent deployment and reuse: the list/overview page can still be your own app.
Independent release cycle without a separate login project: build a custom Account Console with @keycloak/keycloak-account-ui / create-keycloak-theme (guide). It already handles listing, AIA redirects and deletion against the Account REST API.
The cost of the external option is only the extra redirect per action. You'd need that hop anyway to get re-authentication and step-up for credential changes.

2 replies

Batev Nov 5, 2026
Author

Thanks for the detailed explanation and references! The distinction between credential-management overview screens and the actual credential operations makes sense.

One thing we'd still like to clarify is the SCA challenge verification UI.

We already have external SCA backend services responsible for challenge creation and verification, which our custom Keycloak authenticators would integrate with.

Would it be reasonable for a custom Authenticator to redirect the user to an external frontend to complete the SCA challenge, then return to Keycloak to resume the authentication flow? Or would you still strongly recommend rendering these screens within Keycloak using a theme/Keycloakify?

We're particularly interested in whether such external redirects can be implemented safely using supported Keycloak extension points, without relying on internal authentication-session APIs.

Thanks again!

Dv2Corn Nov 5, 2026

Yes, that works, and Keycloak's own quickstarts include an example of it. authenticate() can pass any JAX-RS Response to context.challenge(), including a 302 to your frontend. The action-token-authenticator quickstart works like this:

The authenticator creates an action token tied to the current authentication session and redirects to the external app. The return URL goes along with the redirect.
When it is done, the app sends the browser back to Keycloak's action-token endpoint with its own HMAC-signed token.
The handler checks that token, sets an auth note and resumes the browser flow, and action() then calls context.success().

https://github.com/keycloak/keycloak-quickstarts/tree/c598d34d3b2dd85976ac96614176df351ee1a4d5/extension/action-token-authenticator
Redirect: https://github.com/keycloak/keycloak-quickstarts/blob/c598d34d3b2dd85976ac96614176df351ee1a4d5/extension/action-token-authenticator/src/main/java/org/keycloak/quickstart/actiontoken/authenticator/ExternalAppAuthenticator.java#L77-L104
Return: https://github.com/keycloak/keycloak-quickstarts/blob/c598d34d3b2dd85976ac96614176df351ee1a4d5/extension/action-token-authenticator/src/main/java/org/keycloak/quickstart/actiontoken/token/ExternalApplicationNotificationActionTokenHandler.java#L62-L91

On "supported extension points": there is no fully public path here. The Authentication SPI and Action Token SPI pages both carry the internal-SPI note ("any new release ... can change it without prior notice"):
https://github.com/keycloak/keycloak/blob/30cf683465a1ddf7151462d7f480d6d17f986844/docs/documentation/server_development/topics/partial-private-spi.adoc
The quickstart also uses org.keycloak.services.Urls and LoginActionsService.AUTHENTICATE_PATH. A Keycloak-rendered SCA form is built on the same Authenticator SPI; the redirect version adds the action-token handler and those service classes on top, so re-check them on each upgrade.

If you take the redirect route:

Don't treat the browser coming back as proof that the challenge passed. Either have action() ask your SCA backend server-to-server whether the challenge id you stored in an auth note was verified for this user, or bind the returned token to this session (challenge or session id, short expiry, single use). The quickstart only checks the HMAC signature, not that the token belongs to the current session or user. That is fine for a demo, not for SCA.
If you copy action(): the catch block calls context.failure(...) and then falls through to context.success() (ExternalAppAuthenticator.java L136-L143). Add a return there.
Have the external app redirect only to your Keycloak URL, so the return parameter can't be used as an open redirect.

If your backend already creates and verifies the challenges and the UI is only "enter the code" or "approve in the app", a form rendered by Keycloak is fewer moving parts: authenticate() creates the challenge through your backend, keeps its id in an auth note and renders the page (Keycloakify can style it); action() sends the code to the backend and calls success() or failureChallenge(). The redirect is worth it when the external UI does something a login-theme page can't, for example an existing SCA web app you have to reuse.

Navigation Menu

Repository navigation

SCA and Credential Management UI: Keycloakify or External Frontend? #54611

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment 2 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

SCA and Credential Management UI: Keycloakify or External Frontend? #54611

Uh oh!

Batev Nov 3, 2026

Approaches under consideration

Potential benefits of the external frontend

Questions for the community

Replies: 1 comment · 2 replies

Uh oh!

Dv2Corn Nov 3, 2026

Uh oh!

Batev Nov 5, 2026 Author

Uh oh!

Dv2Corn Nov 5, 2026

Batev
Nov 3, 2026

Replies: 1 comment 2 replies

Dv2Corn
Nov 3, 2026

Batev Nov 5, 2026
Author