Keycloak

Nova manages accounts – called users in Keycloak – and their group memberships in Keycloak. For this, Nova uses the Admin REST API; one target system corresponds to one realm.

Connection

Nova signs in through a confidential client with a service account (OAuth 2.0 client credentials). The fields: “Base URL”, “Realm”, “Client ID” and “Client Secret”.

The service account needs the roles manage-users, view-users, query-users and query-groups of the realm-management client. Depending on use, these are added:

• view-events – to read the last logon from login events
• manage-clients and view-clients – to create AI agents as clients

“Check status” requests a token and counts the accounts in the realm. The test therefore also checks whether the service account may read accounts.

Accounts

• Create: username, email address, first and last name; the account is enabled. Nova stores further attributes from the “Mapping” as Keycloak attributes of the account.
• Change: Nova reads the account, adds the changed values and writes it back. This keeps the account's other attributes intact.
• Lock and unlock via the enabled field.
• Delete.
• Passwords: Nova sets them through the Admin API.

Keycloak stores usernames in lower case; Nova therefore also writes and compares them in lower case. Nova finds accounts by username, email address or Keycloak ID.

Groups

Nova takes over groups and subgroups as entitlements with a job of type “Import Keycloak Groups”. Nova shows them with their path, for example “Engineering/Backend”, and recognises them by their Keycloak ID. Nova does not manage realm or client roles.

Keycloak lists an account as a member only of the groups it belongs to directly. Nova reads and writes only these direct memberships, one at a time. During provisioning, Nova first reads the current memberships so that the change journal contains only effective changes.

Last logon

Nova takes the most recent point in time from the realm's login events and from the account's active sessions. Login events exist only if the realm stores them and the service account has view-events. Without them, Nova only knows the last access from currently active sessions.

AI agents

Nova does not create identities of type “AI Agent” as Keycloak users, but as a confidential client with a service account. Their group memberships belong to the service account of this client. Nova does not store the client secret; “Rotate Secret” creates a new one, which Nova shows once. See AI agents as identities.