How NiFi signs users in through Keycloak over OpenID Connect
NiFi acts as an OpenID Connect client of a self-managed Keycloak realm, and every sign-in is then governed by NiFi's own policies. If your production NiFi still relies on the generated single-user login, this is the step that replaces shared credentials with named accounts from a directory you already operate. NiFi supports OpenID Connect as one of its login identity providers, alongside LDAP, SAML 2.0 and X.509 client certificates, as described in the NiFi System Administrator's Guide. Keycloak takes over the authentication part: it checks the password or second factor, then issues an identity token to NiFi that asserts who the user is. It does not decide what that user may do inside a flow. That division of work is the point to plan around. Keycloak issues identities, while NiFi's authorizer still decides which process groups, components, data and provenance each user can view or modify. A user who signs in successfully with no matching NiFi policy will reach the canvas with no useful rights. Before you configure anything, decide which Keycloak groups correspond to NiFi roles, such as platform administrators, flow developers and read-only auditors, and confirm with your team how those groups will map to NiFi policies. Ask Keycloak administrators which realm, client and claims they will provide, and confirm that the NiFi version you run supports the OpenID Connect settings you need by checking the current NiFi administration guide.
The integration also has limits you should state in the design. It does not replace the need for a recovery administrator, because if the identity provider is unreachable or misconfigured, you still need a documented way to reach NiFi and fix the configuration. Keep a break-glass path that is tested, audited and not used for daily work. It also does not make NiFi's own authorizer optional: a managed authorizer with explicit policies remains necessary for multi-tenant access. Plan for the sign-in path to be part of your production change process, since a faulty realm, client or claim setting can lock every user out at once. Test the flow in a non-production NiFi and Keycloak pair first, and record which identity claim and group claim each environment uses so that the same user maps to the same NiFi identity wherever it is deployed.
What you need before configuring the NiFi and Keycloak link
Single sign-on touches the NiFi runtime, the Keycloak server, the network path between them and a way back in if the login fails. Confirm each item below before anyone edits nifi.properties, so the OpenID Connect settings are tested against a stable foundation rather than a moving target.
NiFi 2.x on Java 21
Confirm the NiFi version you will run is in the 2.x line and that the host runs Java 21, the minimum runtime listed in the NiFi administration guide. Check the NiFi release notes for the exact version you plan to deploy, because OIDC settings and migration steps change between releases. If you are still on 1.x, plan the upgrade path first, since 1.28 is the last minor release of that series.
Keycloak release and version match
Confirm the exact Keycloak version you will run against, then compare it with the current release, 26.8.1 published October 13, 2026. Keycloak plans four minor releases a year, so pin a version and record the upgrade plan before wiring clients. Note whether your team uses the open source distribution or Red Hat build of Keycloak, since support terms and release timing can differ.
Production database and HTTPS endpoint
Confirm Keycloak runs on a supported production database, not the development file store, and that its public base URL uses HTTPS with a valid certificate. The discovery document, token issuer and redirect validation all depend on that hostname. Ask the platform team who owns database backups and failover, because a Keycloak outage stops every NiFi login.
Dedicated NiFi realm and client
Confirm a dedicated realm exists for NiFi, separate from realms used by other applications, so users, groups and client settings can change without affecting unrelated systems. Create the client with a clear owner and a documented list of redirect URIs for each NiFi node or load balancer address. Record who may change realm settings, since group membership in this realm will drive NiFi access policies.
DNS and trusted certificates
Confirm that every NiFi node name and the Keycloak hostname resolve in DNS, and that both sides trust the certificate authority that issued each certificate. The NiFi node must reach the Keycloak discovery URL over TLS, so test name resolution and certificate chains from the NiFi hosts, not from your laptop. Mismatched hostnames are a common cause of failed discovery during first setup.
Recovery admin path
Confirm you have a way to sign in if the OIDC login breaks, such as a separately managed administrator account or a documented break-glass procedure, and test it before enabling SSO. Keep the initial admin identity mapped in the authorizer so an operator can still change policies. Store the recovery credential outside the SSO system so a Keycloak outage does not lock out administrators.
Configuring the NiFi OIDC login in order
This sequence takes a NiFi cluster from an unconfigured login to Keycloak sign-in in which each user's identity and group memberships are known to NiFi's authorizer before production access is granted.
Create the Keycloak realm and confidential client
The Keycloak administrator creates or selects a realm for NiFi users, then registers a client for NiFi with client authentication enabled so it holds a client secret. The redirect URI must match the NiFi UI address exactly, including scheme, host, port and the callback path listed in the administration guide. Confirm the client's settings with your Keycloak administrator and record the client ID and secret in your secrets store, not in a shared document. The step is complete when the client exists, has a secret, and the redirect URI matches the NiFi hostname that users will type into their browser.
Confirm the discovery document loads
Before editing NiFi, request the realm's OpenID Connect discovery document from a host that will run NiFi, using the well-known configuration path for that realm. Keycloak's server administration guide describes the realm endpoints. Check that the response is reachable, that TLS validates against the trust store NiFi will use, and that the issuer value matches the URL you will configure. If the document fails to load here, NiFi will fail in the same way, so resolve network, certificate or hostname issues first.
Set the OIDC properties in nifi.properties
On each node, set the OpenID Connect discovery URL, client ID and client secret in nifi.properties, following the exact property keys in the NiFi System Administrator's Guide. Keep the secret out of version control by using your configuration management or environment-based injection, and make the values identical across nodes. Restart the node in a controlled order so the cluster does not lose quorum. The step is done when each node starts, logs no OIDC configuration errors, and shows the NiFi login page with an OpenID Connect option or redirect.
Enable PKCE and verify the authorization request
Enable Proof Key for Code Exchange in the NiFi OIDC settings if your NiFi version and the administration guide support it for your client configuration, and confirm the setting in the Keycloak client's advanced options so both sides agree. Start a login in a browser and inspect the authorization request: it should carry a code challenge and the expected scopes. Confirm the choice with your NiFi version notes, since PKCE behavior depends on the release you run. The step is complete when the authorization request includes the challenge and the code exchange succeeds.
Choose the identity claim and map it to NiFi
Decide which token claim NiFi should use as the user identity, such as a stable username or email claim, and configure the claim name and any identity mapping in NiFi as described in the administration guide. Make the choice before users and policies exist, because changing it later changes the identity string that policies are attached to. Ensure the claim is present in the ID or access token by checking the client's mapper settings in Keycloak. The step is complete when a test login produces an identity string in NiFi that matches the claim you intended.
Add group claims and configure the authorizer
Add a group membership mapper to the Keycloak client so the access token or ID token carries the groups you want NiFi to use, and confirm the claim name the NiFi documentation expects. Then configure the NiFi authorizer so those groups receive the intended policies, starting with a small administrator group. Check that group names are consistent between Keycloak and NiFi policies, and keep a recovery administrator path available in case the group mapping fails. The step is done when a user in the admin group sees the policies you expect and a user outside it does not.
Test login, logout and token refresh with a non-admin user
Sign in as a standard user who is not in any administrative group, and confirm that the user reaches only the process groups their policies allow. Check that logout ends the NiFi session and that the Keycloak session behaves as your security policy requires. Observe token refresh over a session longer than the token lifetime configured in Keycloak, and confirm that the refresh behavior described in the NiFi administration guide matches what you see in the logs. The step is complete when the non-admin login, denied actions, logout and refresh all behave as documented in your test plan.
Choosing the identity claim and group claim for NiFi policies
The identity claim is the value NiFi receives from Keycloak and uses to create or match a user. Three common candidates are the subject identifier (sub), the preferred username (preferred_username), and the email address (email). Each one answers a different question: whether the identity survives a rename, whether an administrator can recognize the user in the UI, and whether the value is unique across the realm. Keycloak's default sub value is an internal identifier that does not change when a person's name or mailbox changes, which makes it the safest key for long-lived policies. Usernames and emails are easier to read in audit logs and policy screens, but they can be reassigned or edited, which can silently orphan existing policies.
- Subject identifier: Stable and unique, but it appears as an opaque string in the NiFi user list, so administrators need a mapping to recognize people.
- Preferred username: Readable and common in policy screens, but it depends on how usernames are managed in Keycloak and on the realm's uniqueness rules.
- Email address: Familiar to auditors and useful for notifications, but addresses change during mergers, name changes, and domain moves.
- Mixed approach: Use the subject as the stable key and an identity mapping rule to display a readable name, so policies survive renames.
- Decision record: Write down the chosen claim, the reason, and who approves changes to it before the first production user signs in.
Confirm the exact claim names in the Keycloak client scope configuration in your running environment, because mappers can be customized per realm.
NiFi does not grant access because a user signed in. Access comes from policies attached to users and groups inside NiFi. A group claim from Keycloak can place a user into a NiFi group, but that group only matters once an administrator has attached it to the right global or component policies. Group claims therefore need two checks: the claim must arrive in the token with the expected name and values, and each resulting group must be mapped to the policies that define what its members may view or modify. The NiFi administration guide describes how the OpenID Connect provider and the authorizer work together, so confirm the current group handling behavior against that guide for your release.
- Claim delivery: Confirm that the group claim is included in the access or ID token for the NiFi client, not only in the Keycloak admin view.
- Group naming: Use stable, descriptive group paths, such as one group per team or role, so policy screens stay understandable.
- Policy mapping: Attach each group to explicit global or component policies, including the view and modify rights that the team needs.
- Unmapped users: A user with a valid login and no matching policy signs in but sees an empty canvas and no management options. Treat this as a configuration result, not a login failure.
- Recovery access: Keep a named administrator group with a tested path, so a broken group claim does not lock every operator out.
Test the claim with a sample user from each group before you rely on it for production access.
Identity mapping rules transform the raw claim value into the name NiFi stores and shows. They are useful when the stable subject identifier is the right key but administrators need a readable label. A mapping rule takes a pattern from the incoming identity and rewrites it, for example removing a domain suffix from an email address. Mapping changes the displayed name only if it is applied consistently; once a name is in use in policies, changing the rule later can create a new user and leave the old policies attached to an identity that no longer appears in the flow. Because mapping sits between the token and the authorizer, it must be tested with each identity source you expect to accept.
- Pattern design: Keep patterns simple and anchored, and test them against several real sample identities before deployment.
- Display versus key: Decide whether the mapped value is the policy key or only a label, and document the answer.
- Change control: Treat a change to a mapping rule as a change to access control, with review and a rollback plan.
- Duplicate names: Check that two different identities cannot map to the same display name, since that would merge their access.
- Migration: If you switch claims after users already have policies, plan how existing policies will be reassigned before cutover.
Confirm the mapping property names and their syntax in the NiFi administration guide for your version, and verify the result by reviewing the user list after a test login.
The core trade-off in this section is between a key that never changes and a value that people can read. A subject identifier is stable and unique within the realm, so policies survive name changes, but it is hard for administrators to review during an access review. A username or email is easy to scan but ties access to a value that the identity team may change. Security and compliance teams usually care about the stable key, because auditors test whether access follows the person rather than a mutable label. Platform teams care about readability because they must troubleshoot policies under time pressure. A design that serves both groups uses the stable key for authorization and a mapped label for display, with a documented lookup from one to the other.
- Lifecycle events: Map out what happens when someone changes their name, leaves the company, or returns under a new account.
- Shared accounts: Make sure claims identify individuals. Service or shared accounts should be separate, documented exceptions.
- Realm scope: If several realms or brokers feed the same NiFi, check that identifiers cannot collide across them.
- Audit evidence: Keep a record of which claim is the key, so provenance and audit entries can be traced back to a person.
- Ownership: Name who maintains the claim mapping in Keycloak and who maintains the matching policies in NiFi.
Ask the identity team to confirm how user lifecycle changes propagate from the directory into Keycloak before you commit to a key claim.
Mapping Keycloak claims and realm roles to NiFi identities and policies
This table pairs each Keycloak element with the NiFi setting that consumes it, the team that owns the value and the failure that follows a change. Read it before you choose a claim, add a group or remove a bootstrap admin, because several of these values are checked at login and tied to existing policies. Confirm every claim name in your own Keycloak realm and NiFi version before you configure anything.
| Keycloak element | NiFi counterpart | Owner of the value | What breaks if it changes |
|---|---|---|---|
| Username or subject claim (for example, preferred_username or sub, to be confirmed) | NiFi user identity used in the OIDC identity mapping and shown in the user list | Keycloak realm administrator, with the NiFi administrator agreeing the mapping | Existing users appear as new identities, and their policies no longer apply to them |
| Group claim included in the ID token or userinfo response (name to be confirmed in your realm) | Group membership used by the authorizer to match group-based policies | Keycloak administrator who maintains groups and the client mapper | Users lose access to process groups tied to that group, or gain access they should not have |
| Realm roles assigned to users | Policy assignments in NiFi only when a role claim is mapped to a NiFi group or user, which must be configured and tested | Keycloak administrator for role design, NiFi administrator for policy assignment | Renaming or removing a role silently removes policy access at the next login |
| Client roles on the NiFi client | Used only if your mapping reads them into NiFi groups, so treat them as an optional path to confirm | Keycloak administrator for the client, with the NiFi team validating claim output | Changes in client role scope can remove access for every user of the NiFi client at once |
| Client ID and client secret for the NiFi client | OIDC client credentials in the NiFi login configuration | Keycloak administrator issues the secret, NiFi operations stores it | Rotating the secret without updating every NiFi node stops login across the cluster |
| Initial admin identity (a named user or group in the initial admin setting) | The identity granted full access on first start, which NiFi uses to create the first policies | NiFi administrator, approved by the security owner | If this identity is deleted or its claim changes, no one may be able to manage policies in the UI |
| Recovery admin account outside SSO (exact method to confirm for your NiFi version) | A break-glass path that does not depend on Keycloak being reachable | Security owner, with a named custodian kept separate from daily administrators | Without it, a Keycloak outage or a mapping error can lock out all administrators |
| Keycloak user or group removal | Stale NiFi identities and policies remain until an administrator removes them | NiFi administrator, reviewing policies on a set schedule | Former staff keep access if policies are not reviewed after offboarding |
Hardening the NiFi and Keycloak login path
The login path runs from the browser through Keycloak to NiFi and back, and each hop can weaken the others. The controls below cover the client registration, the transport, the redirect targets, the fallback access path and the secrets NiFi stores after sign-in. Work through them together before the OpenID Connect provider goes live.
Confidential client with a managed secret
Register NiFi in Keycloak as a confidential client so the client secret is held by NiFi and never exposed to the browser. Store the secret in your secrets manager and inject it into nifi.properties at deployment, not by editing files on each node. Ask who can view and rotate the secret in the Keycloak admin console, and confirm that rotation can be done on every cluster node in one change window.
PKCE enablement on the client
Turn on PKCE (Proof Key for Code Exchange) for the NiFi client in Keycloak and confirm the NiFi OIDC settings send the matching code challenge. PKCE protects the authorization code flow from interception, which matters most when a redirect can be observed or a client is misconfigured. Test that a sign-in without the verifier fails, so you know the check is enforced rather than assumed.
HTTPS and certificate trust
Serve NiFi and Keycloak over HTTPS and make NiFi trust the certificate chain of the Keycloak issuer, including the discovery endpoint and token and JWKS URLs. Use certificates whose hostnames match the URLs NiFi calls, because a mismatch often gets patched by disabling verification, which removes the protection entirely. Confirm the trust store is managed and rotated with the other NiFi certificates.
Strict redirect URI registration
Register the exact NiFi callback URL in the Keycloak client and avoid wildcards or broad path patterns. A loose redirect list lets an attacker who can place a user on a crafted link receive authorization codes for a different target. List each environment separately, and review the list whenever a hostname, load balancer or cluster endpoint changes.
Recovery admin outside Keycloak
Keep a local recovery administrator in NiFi that does not depend on Keycloak being reachable, and store its credentials in a sealed, audited location. If Keycloak is down, misconfigured or its signing keys rotate badly, this account is how you restore access and fix the mapping. Test the recovery path on a non-production cluster before go-live, and confirm who may use it and how each use is logged.
Sensitive properties key protection
NiFi encrypts stored secrets, including the OIDC client secret, using the key in nifi.sensitive.props.key. Keep that key out of version control, make it identical on every node, and record where the backup copy is held. Losing the key makes protected values unreadable, and a leaked key exposes them, so confirm the key handling procedure with the team that will rotate it before you move the client secret into NiFi.
What happens at logout and when tokens refresh
A NiFi logout ends the NiFi session, but it does not by itself end the Keycloak session. The browser session that NiFi issues is separate from the Keycloak login behind it. When a user signs out of NiFi only, the next visit to the NiFi UI can often pass through Keycloak again without a password prompt because the identity provider session is still active. Single logout, where NiFi also redirects the browser to the Keycloak end-session endpoint, closes the Keycloak session as well. Confirm in the NiFi System Administrator's Guide which logout path your NiFi version uses, whether the OIDC configuration includes a logout redirect, and whether Keycloak's front-channel or back-channel logout is needed for other applications sharing the same realm session. Do not assume that a user who clicked logout has been signed out of every application.
Token refresh governs how long a browser session survives after the initial sign-in. Keycloak issues access and refresh tokens with lifetimes set per realm and per client, and NiFi uses the refresh token to renew its session when the access token expires. Keycloak session idle and maximum limits, and the client's token settings, decide when renewal stops working. Confirm these values in your realm before go-live, and confirm how NiFi behaves when a refresh fails: it may keep a session alive, prompt a new login, or drop the user mid-task. Cluster nodes each hold the session state needed to validate requests, so test a sign-in against each node behind your load balancer and confirm that a refresh routed to a different node succeeds.
Revoking a user or changing group membership in Keycloak takes effect at the next token or session boundary, not immediately. A disabled user keeps working until the current session ends, and a removed group only changes NiFi policy once NiFi reads a token that no longer carries that claim. For an access revocation that must be immediate, plan a procedure that ends active NiFi sessions and disables the Keycloak session, then verify it. During acceptance testing, sign in as a test user, change that user's group in Keycloak, disable the account, and record exactly when access stops in the browser, through the API, and on every node. Keep this result with your change records so the operations team knows the real window.
Why NiFi login with Keycloak fails and how to fix it
This table pairs common sign-in failures with their likely cause, a check to run and a fix. Work through it in order when a login breaks, because discovery and redirect problems block everything after them. The main takeaway is that most failures trace back to a mismatch between the NiFi and Keycloak configuration, the network path to Keycloak, or the claims NiFi expects in the token.
| Symptom | Likely cause | Check | Fix |
|---|---|---|---|
| NiFi fails to start or shows an OIDC discovery error | Discovery URL unreachable from the NiFi nodes, or the Keycloak certificate is not trusted by the NiFi truststore | From each NiFi node, request the discovery document with curl using the same truststore NiFi uses | Open the network path from every node, then import the Keycloak CA into the NiFi truststore and restart |
| Keycloak login page returns an invalid redirect URI error | The redirect URI registered on the Keycloak client does not match the NiFi callback URL character for character | Compare the client's valid redirect URIs with the scheme, host, port and path NiFi sends | Register the exact callback URL for each NiFi address, including the proxy or load balancer hostname if one is used |
| Login works on one node but fails on another | Cluster nodes use different callback URLs or hostnames, so the redirect returns to a node that did not start the flow | Check the callback URL configured on each node and the hostname the browser uses | Use one externally reachable address for all nodes and register every callback URL on the Keycloak client |
| Login fails after the client secret was rotated | NiFi still holds the old client secret, or the rotated value was only changed in Keycloak | Compare the secret stored in NiFi with the current value on the Keycloak client credentials tab | Update the client secret in NiFi, restart the nodes and confirm the new value is used on every node |
| User signs in but sees no components or cannot modify anything | The user has no matching policy, or the identity NiFi derived does not match the identity used in policies | Review the identity in the NiFi user log and the users and policies screen, then compare them | Map the claim to the identity NiFi expects, add the user or group to policies, and keep a recovery admin |
| Group policies do not apply | The configured group claim is missing from the ID or access token, or the mapper is not added to the client scope | Decode a test token and look for the groups claim, then confirm the Keycloak client scope includes a group mapper | Add a group membership mapper to the client scope, set the claim name NiFi expects, and sign in again |
| Token validation fails with time or expiry errors | Clock skew between Keycloak, NiFi nodes and the browser, so tokens appear not yet valid or already expired | Compare system time on Keycloak and each NiFi node against a common time source | Synchronize time on all hosts with NTP or the platform time service, then retest the login |
| Logout returns the user to the login page in a loop | The post-logout redirect URI is not registered in Keycloak, or the session is restored from a still-valid SSO session | Check the post-logout redirect URI on the client and watch the redirect chain in browser developer tools | Register the post-logout redirect URI, then confirm the logout path ends the Keycloak session as well as the NiFi session |
| Sessions expire unexpectedly or refresh fails | Token lifetimes in Keycloak are shorter than the NiFi session expectations, or the refresh token is not issued to the client | Review the realm token lifespan settings and the NiFi OIDC log entries around the refresh attempt | Align the Keycloak token and session lifetimes with the NiFi session timeout and confirm the client is allowed to refresh |
Questions teams ask before connecting NiFi to Keycloak
How much effort does a NiFi and Keycloak OpenID Connect integration take?
The effort depends on how much of the identity setup already exists and how many NiFi nodes need to be reconfigured. A single standalone NiFi with a Keycloak realm that already has a confidential client and group membership is a small change. Effort grows with cluster size, because every node needs matching TLS trust and consistent settings, and with the number of groups that must map to NiFi policies. Keycloak maturity matters too: a realm with clean group structure, documented client scopes and a tested token configuration takes less time than one where claims must be designed from scratch. Certificate work is often the longest item, since NiFi must trust the Keycloak endpoints it contacts over HTTPS. Ask any partner to break the quote into identity design, Keycloak changes, NiFi configuration, testing and handover.
Can our team connect NiFi to Keycloak without a partner?
Yes, if the team has people who can operate both platforms. The NiFi administration guide documents the OpenID Connect provider settings, and Keycloak's server administration guide covers clients, scopes, mappers and groups. The harder parts are judgment calls: which claim becomes the NiFi identity, how group claims map to policies, how a recovery administrator is kept available if the identity provider fails, and how a failed login is diagnosed across two products. A team that has run NiFi in production and has someone comfortable with Keycloak token internals can usually do this in-house. A team without either skill usually benefits from an outside review of the design before the change reaches production.
What do we need to provide for a Keycloak OIDC engagement?
The engagement needs a few specific inputs from your side before work starts. You need administrative access to the Keycloak realm, or a named administrator who can make changes during the work, and a test realm or test client where changes can be verified before production. DNS records must resolve the NiFi hostname and the Keycloak hostname consistently for every node, and the redirect URI must match what NiFi presents. Certificates must be issued for those hostnames, and your team must decide which trust store NiFi uses to reach Keycloak. Finally, prepare a small test group of real users and a list of the NiFi groups and policies that each group should receive. Confirm these inputs in writing so that scope and schedule reflect what your environment actually provides.
How long does acceptance testing take for a NiFi single sign-on change?
Acceptance testing length depends on scope, not on a fixed number of days. A narrow test covers one NiFi instance, one Keycloak realm, and a few users in one group, checking login, logout, token refresh during a long session, and policy results for each group. A broader test covers every node in a cluster, several group-to-policy mappings, failure cases such as an expired certificate or a disabled user, and the recovery administrator path. Each added group, node or identity source adds test cases and review time. Ask for the test matrix in the written scope so you can see which cases are covered and who signs off on the results.
Will Keycloak upgrades break NiFi login?
They can, which is why upgrades need their own test step. Keycloak documents that breaking changes in minor releases are opt-in, and its upgrading guide explains the changes for each release. Still, an upgrade can change client behavior, default scopes, token contents or certificate handling, and any of these may affect a NiFi client. Schema migration also happens automatically at startup by default, while the upgrading guide suggests manual migration for large deployments. Treat each Keycloak upgrade as a change to the NiFi integration: read the release notes, test login and group mapping against a copy of the realm, and keep the NiFi recovery administrator working throughout. Plan the same review for NiFi upgrades, since the NiFi migration guidance describes changes between versions.
Does DeployOpen certify that our NiFi and Keycloak setup is secure or compliant?
No. DeployOpen does not issue audit reports, attestations or certifications. For the NiFi and Keycloak integration, DeployOpen can plan, configure, test and document the setup and prepare the evidence an assessor will ask for, such as configuration records, group-to-policy mappings and test results. An independent auditor or certification body decides whether your controls meet a given framework. If your organization needs assurance for a specific control set, confirm with your auditor which evidence they expect and agree on that list before the work is scoped.
Which Keycloak version should we target for the NiFi integration?
Choose a supported Keycloak release that your organization can keep current, and confirm the database and high availability design before you pick one. Keycloak's current release is 26.8.1, published October 13, 2026, and Red Hat's supported build of Keycloak is a separate product line with its own release cadence. Keycloak supports several production databases, and its high availability designs need a synchronously replicated database. The version decision affects the test plan, because every later upgrade will repeat the same login checks. Ask your identity team to confirm the version policy first, then align the NiFi change with it.
Official sources for the NiFi and Keycloak configuration
Start with the NiFi System Administrator's Guide, which documents the OpenID Connect authentication provider, its properties and how NiFi behaves when the provider is enabled. Read the OIDC section alongside your exact NiFi version, because property names, default values and the handling of identity claims can differ between the 1.x and 2.x lines. Keep a copy of the relevant section with your change record so the configuration you deployed can be traced back to the documentation it followed. The Apache NiFi System Administrator's Guide is the authoritative reference for every nifi.security.user.oidc.* key used in this topic.
Pair that with the Keycloak server administration guide and the Keycloak production configuration page. The administration guide covers how to create the realm, the confidential client, client scopes, protocol mappers that place group and identity claims into the token, and the session and token lifetime settings that govern refresh behavior. The production configuration page covers the hostname, proxy and TLS settings that must match the redirect URI and issuer NiFi is configured with. Confirm the Keycloak version you run against the current documentation, since the project ships minor releases several times a year and treats some changes as opt-in. Check the Keycloak server administration guide and the Keycloak production configuration page before you finalize the client settings.
Before go-live, confirm three things against those sources in your own environment: the exact property names and accepted values for your NiFi version, the issuer and discovery URL your Keycloak realm publishes through its public hostname, and whether PKCE and the logout and refresh behaviors match your security requirements. Record the answers in a configuration review signed by the platform owner. Ask your implementation partner to show where each value came from so that a later upgrade of either product starts from verified settings rather than from memory.
How DeployOpen scopes and delivers the NiFi Keycloak login
The NiFi and Keycloak login is delivered as one written scope, so realm design, NiFi settings, claim mapping and acceptance tests are agreed before any change is made. The cards below describe what that scope covers, how support can continue after handover, and where DeployOpen's responsibility ends.
Written fixed scope
Most engagements are fixed-scope, so the realm design, NiFi configuration, claim and policy mapping, acceptance tests and handover are agreed in writing before work starts. The scope names the Keycloak version, the NiFi version, the environments and the identity claim to be used. Ask for the scope document to list which items are excluded, such as changes to the Keycloak server itself or the upstream identity source.
Realm and client design
The realm, the NiFi OpenID Connect client and its redirect URIs are designed before NiFi is touched, including whether the client uses client authentication and PKCE. Keycloak is the system of record for these settings, so they are reviewed with the team that owns the identity provider. Confirm who on your side approves client secrets and where they will be stored.
Claim and policy mapping
The delivery maps the chosen identity claim and group claims to NiFi identities and to the initial admin group, so that access policies work from the first login. The mapping is tested with real test accounts from each group. Ask how group membership changes are expected to flow into NiFi policies and who signs off each mapping rule.
Acceptance tests and handover
Acceptance tests cover login, logout, token expiry and refresh, denied access for users outside the group, and recovery if the identity provider is unavailable. Handover includes a runbook and the test scripts so your team can repeat them after changes. Ask which tests are run in your environment and which are run on DeployOpen's own test setup.
Retainer and evidence limits
A retainer can cover Keycloak and NiFi upgrades, rerunning acceptance tests after releases, and reviewing configuration drift. DeployOpen prepares the configuration, test records and change evidence that an assessor may ask for, but it does not issue audit reports, attestations or certifications. Independent auditors and certification bodies make those determinations, so ask them early which evidence they expect.
