Configure automatic account inactivity disable

What you’ll accomplish

You’ll configure UDS Core’s Keycloak to automatically disable non-admin user accounts that have not authenticated for a configurable number of days. Accounts belonging to realm administrators are excluded and are never automatically disabled.

Prerequisites

• UDS Core 1.2+ deployed
• UDS CLI installed
• UDS Registry account created and authenticated locally with a read token

Before you begin

UDS Core uses the Keycloak Workflows preview feature to track user-authenticated events per user and trigger a disable-user action after the configured inactivity window. The workflow is seeded into the uds realm on initial deployment and is disabled by default (ACCOUNT_INACTIVITY_DAYS unset).

What counts as activity: The workflow tracks user-authenticated events. Any successful login through UDS Core SSO, including logins via federated identity providers (Azure AD, Google SAML), resets the inactivity timer.

Newly provisioned accounts: Accounts that have never logged in do not generate a user-authenticated event and therefore never start a workflow instance. Accounts provisioned before this feature was enabled are also not retroactively evaluated. Run a one-time audit of last-login timestamps after enabling via Keycloak Admin Console → Users.

Admin accounts excluded: Users with the realm-management/realm-admin role are never disabled by this workflow.

Steps

1. Set ACCOUNT_INACTIVITY_DAYS in your bundle override

   Add the override to your uds-bundle.yaml. Set the value to the number of days of inactivity after which you want non-admin accounts to be disabled.

   uds-bundle.yaml

   packages:
     - name: core
       repository: registry.defenseunicorns.com/public/core
       ref: x.x.x-upstream
       overrides:
         keycloak:
           keycloak:
             values:
               - path: realmInitEnv
                 value:
                   ACCOUNT_INACTIVITY_DAYS: "35"

   Omitting ACCOUNT_INACTIVITY_DAYS (the default) leaves the workflow disabled.

   Caution

   This setting is applied during initial realm import only. Changing ACCOUNT_INACTIVITY_DAYS in a bundle re-deploy updates the Kubernetes Secret but does not update the live workflow. Keycloak only reads the value during the first realm import. To update the inactivity window on a running instance, see step 3 below.

2. Create and deploy your bundle

   uds create <path-to-bundle-dir>
   uds deploy uds-bundle-<name>-<arch>-<version>.tar.zst

3. Optional: Update the inactivity window on a running instance

   If you need to change the inactivity window after initial deployment, update the workflow directly in the Keycloak Admin Console:

   1. Log in to the Keycloak Admin Console at keycloak.<admin_domain>
   2. Switch to the uds realm
   3. In the left sidebar under Configure, click Workflows
   4. Open the disable-inactive-users workflow
   5. Click the disable-user step and update the after duration to your desired number of days
   6. Toggle Enabled to On if not already enabled
   7. Click Save

   Caution

   In the Admin Console, setting the after duration to 0 days will disable non-admin accounts immediately on their next login. Always confirm the duration is correct before enabling the workflow.

Verification

After deployment, confirm the workflow is active:

1. Log in to the Keycloak Admin Console at keycloak.<admin_domain>
2. Switch to the uds realm
3. In the left sidebar under Configure, click Workflows
4. Confirm the disable-inactive-users workflow is listed and Enabled is toggled on
5. Log in as a non-admin test user through UDS Core SSO
6. Return to the Admin Console, open the workflow, and click View active instances. A new instance should appear for the test user with a disable-user step scheduled at the number of days you configured

Note

No instance appears for accounts that have not logged in since the workflow was created. Those accounts must be audited manually.

Troubleshooting

Problem: Workflow shows as disabled after deployment

Symptom: The disable-inactive-users workflow exists in the Admin Console but Enabled is off.

Solution: ACCOUNT_INACTIVITY_DAYS was not set or was not applied. Verify the bundle override was included and the value is set to a positive integer. To enable on a running instance without redeploying, toggle Enabled directly in the Admin Console and verify the after duration on the disable-user step is set to your desired number of days. If the value reads 0, update it before enabling. A 0d duration will disable accounts immediately on their next login.

Problem: No workflow instances appear after user login

Symptom: A non-admin user logged in successfully but no active workflow instance appears.

Solution: Confirm the login fired a user-authenticated event. In the Admin Console, navigate to Manage → Events, filter by event type LOGIN, and confirm the user’s event is present. Federated logins via an IdP also fire this event as long as the user authenticated through Keycloak.

Problem: A disabled account needs to be re-enabled

Symptom: A user cannot log in and their account shows as disabled.

Solution: An administrator must manually re-enable the account in the Keycloak Admin Console:

1. Navigate to Users and find the affected user
2. Click the user to open their profile
3. On the Details tab, toggle Enabled to On
4. Save

Problem: Admin account was disabled

Symptom: A user with admin privileges was automatically disabled.

Solution: The workflow excludes users with the realm-management/realm-admin client role. If an admin account was disabled, it was not assigned that role. Re-enable the account manually and assign the role via Users → select user → Role Mapping → assign realm-admin under realm-management.

Related documentation

• Keycloak: Managing workflows - upstream reference for the Workflows preview feature
• Configure Keycloak account lockout - configure brute-force lockout thresholds alongside inactivity disable
• Configure user accounts and security policies - set password policy, email verification, and other account-level security settings