Inflow.aiDocs

Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.

Preserved from source baseline d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.

Identity Configuration Manual

Practical guide and worked examples

Plan an identity lifecycle, not just a login form

Use this guide for platform identity administrators and developers integrating a normal user session. A user account, group membership, workspace role, application contribution, API-key ceiling and task eligibility are separate layers. Provisioning a Basic account does not populate all those layers automatically. The connected People Operations tutorial uses Nadia as its authorized administrator, Mohammad as an employee and Sara as a manager; their actual server-issued account IDs must be retained for later references.

The administration request separates personal profile fields (displayName, names, email, locale, timezone, employee/job/manager fields), organizational memberships (groupKeys and supported references), sign-in state (active, locked, local-password choices) and protected/server-owned metadata. Use the published user-profile schema for custom attributes; preferences are not another permission store. Do not copy a full GET response into an upsert: returned capabilities, authentication provenance and server-owned metadata are not arbitrary editable fields.

Task Preparation Result to retain
Create a Basic person Allowed account type, valid identity fields, admitted welcome delivery Actual id, username, state and safe capabilities; handle any one-time material privately.
Set a manager Select the actual manager account managerUserId, not a display name or an assumed username-as-ID.
Reset local sign-in Authorized other local-password account Forced-change/session effects; no password value is returned by reset.
Inspect the current session Normal authenticated caller Actor, effective permission hints, timing and current policy hints.
Configure a deployment posture Selected canonical file and supported feature keys Startup snapshot and explicit local/production classification.

Follow the external-provider guide for federated configuration, application users for app-only journeys and workspace security for object grants. The session response helps Studio present controls; each service still authorizes its own request.

The examples below use synthetic teaching data. They are grounded in the cited source contracts; this documentation change did not execute these operations against a running Inflow deployment. Use normal authenticated sessions and the actual returned identifiers, revisions and versions from an authorized environment.

Example ROOT-ID-01 — Provision Mohammad as a Basic person

Scenario and inputs. Nadia has the required identity-management authority and an admitted test email destination. She wants a new Basic person for the leave tutorial, without inherited administrator groups or fabricated provider provenance. The sample email uses the reserved example domain; substitute an approved test-mail destination if the exercise includes real welcome delivery.

Procedure. Read the user-profile schema and allowed directory groups before creating the person. This is a complete create-body example with only its relevant editable fields:

POST /api/admin/identity/users
Content-Type: application/json
{"username":"mohammad_learner","displayName":"Mohammad Learner","email":"mohammad@example.test","accountType":"BASIC","active":true,"groupKeys":[],"passwordChangeRequired":true,"attributes":{},"preferences":{}}

Retain the returned id for membership/manager/application references. Inspect the actual welcome result and account capabilities. Complete normal sign-in through the admitted local-password welcome flow before using the person for runtime acceptance.

Expected result. Creation is insert-only. Omitting a password follows the server's generated/local welcome policy; any generated one-time value allowed for this account classification is private credential material, not a value to paste into this tutorial or a screenshot. The new account is not automatically an employee-group member or an application user.

Failure and recovery. An existing ID is refused rather than overwritten, and invalid/duplicate email or an invalid profile field must be corrected at the declared field. Do not set administrative roles, inject metadata.externalClaims or change account kind to bypass a refusal. An unsuccessful welcome delivery must be resolved through the supported account/welcome flow, without creating a second ambiguous identity.

Sources. AdminIdentityController.java:365, AdminUserUpsertRequest.java:1, AdminIdentityController.java:385.

Example ROOT-ID-02 — Reset a local password without returning a new secret

Scenario and inputs. Mohammad has an existing local-password account and cannot use its current sign-in credential. Nadia is a different authorized identity administrator; resetting her own account or an administrative person has its additional restrictions. This is a reset of an existing local identity, not an implicit conversion of a federated-only account.

Procedure. Open the user's authorized drawer, inspect the actual local-sign-in capability and choose Reset password with the required confirmation. The administration route is POST /api/admin/identity/users/<mohammad-user-id>/password-reset; substitute the real account ID and use the normal authenticated session. It does not take a newly chosen password body. Read the resulting safe account state and have Mohammad complete the supported sign-in/password-change journey. Record identifiers and outcome in operational notes, never a secret or a full credential-bearing response.

Expected result. The reset routine marks the local person to choose a new password at next sign-in, ends the affected sessions and records the user update. The reset endpoint does not generate, set, return or log a replacement password. These effects are distinct from the create-account response or a set-password welcome link.

Failure and recovery. PASSWORD_RESET_NOT_APPLICABLE identifies an account that is not eligible for this local-password operation. Do not delete its provider binding or fabricate a temporary password. If converting an eligible federated account is genuinely intended, use the separately authorized explicit conversion operation and review its session/provider effects; otherwise ask the accountable identity owner to restore the legitimate sign-in route.

Sources. AdminIdentityController.java:355, AdminUserUpsertRequest.java:45.

Example ROOT-ID-03 — Read the caller’s session without granting authority or extending idle time

Scenario and inputs. Sara is signed in normally and needs to understand why Studio shows some actions and hides others. The caller's current session has a server-enforced idle/absolute lifetime and may carry an API-key ceiling. An administrator's session output must not be used as Sara's effective permission evidence.

Procedure. Use GET /api/admin/identity/session in Sara's own authenticated session. Read the returned actor, permission hints, identity/group administration capability hints and effective timing fields. When implementing a passive session probe, follow the supported touchSession=false behavior rather than sending activity on every polling read. Compare the hints with the action's actual scoped capability in the relevant domain; use the authorized Check access surface for a specific workspace/object decision, not a global-key guess.

Expected result. The response contains the caller's safe identity and current presentation hints, including the effective idle/absolute timing budget and remaining idle time where available. A passive probe observes the server clock without making the session immortal. The permission list is a hint after the caller's API ceiling; each service request still evaluates current authorization and object/workspace policy.

Failure and recovery. If the session ends, require normal reauthentication and reconcile any earlier mutation using its original native intent/receipt. Do not silently replay a task completion after login or manufacture a new user ID in a request header. A missing scoped capability, an explicit denial and an unavailable policy service must remain distinct states in both UI behavior and diagnosis.

Sources. AdminIdentityController.java:190, PlatformAuthenticationFilter.java:316.

Example ROOT-ID-04 — Initialize a local development posture without changing production policy

Scenario and inputs. Nadia is preparing her own admitted local Compose lane. The repository has canonical feature configuration, a local-only development profile and a generated private runtime file. Production authentication posture and existing operator edits must remain intact; an old JVM feature-value alias is not a supported shortcut to enable development conveniences.

Procedure. Inspect the actual INFLOW_CONFIG_FILE path selected for the lane and the Compose launcher. scripts/dev/with-canonical-config.sh initializes that physical file from the checked-in configuration plus conf/feature-profile.development.properties only when the runtime file is absent, then executes the requested Java command. Read the resulting canonical settings privately and retain intended operator/API edits on later starts. Use the normal documented lane startup when authorized; do not reset the generated file just to recover an old seeded authentication example.

Expected result. The canonical startup snapshot supplies the registered feature values before security assembly. Local development initialization is explicit and isolated. A restart-only feature does not become hot merely because a legacy environment/JVM alias changed, and an existing generated file is not silently overwritten on subsequent launches.

Failure and recovery. If the selected file or posture is wrong, have its authorized owner correct that exact configuration and follow the declared activation requirement. Do not copy the development profile into Production, expose root credentials, delete another lane's file or change shared services during a documentation exercise. Configuration-source checks are not proof that a running deployment has restarted into the intended posture.

Sources. with-canonical-config.sh:1, FeatureConfiguration.java:1, CanonicalFeatureEnvironmentPostProcessor.java:1.

Document status: Current identity configuration reference. Verified against origin/master on 2026-08-14.

This manual explains how Inflow Platform models user accounts and how tenants can extend user profiles through configuration.

For external SSO and directory provider configuration, see the External Authentication Providers Manual.

Local-password welcome (SCRUM-1806)

Creating an Inflow local-password user (Authorization → Users, or POST /api/admin/identity/users) no longer requires the administrator to invent a long-lived password:

  • Leave Password blank to generate a one-time secret. It is shown once in the create dialog for in-person handoff. It is never written into email, logs, or later GET responses.
  • Fill a policy-valid password if you want to set the value yourself.

When outgoing SMTP is configured and enabled (Authorization → Email configuration), Inflow sends exactly one welcome email to the user's address. The email contains the username, installation context, and a single-use, 48-hour set-password link. It never contains the password, hash, or raw token. If SMTP is off, create still succeeds and the dialog reports that mail was skipped.

The person can set their password by opening the link, or by signing in with the one-time password and completing the forced change before a Studio session is issued. Used, expired, or invalid tokens fail closed with a non-enumerating message.

This flow runs only for Inflow local-password accounts. SCIM, JIT / create-user-at-login, SAML/OIDC/LDAP, API keys, and passkeys as primary sign-in do not receive a generated Inflow password or this welcome email. A federated account gets a local password only through an explicit conversion (below).

Convert a federated account to local sign-in (SCRUM-4031)

Local-password settings apply only to accounts on Inflow's own identity management. A federated account was created or linked by SCIM, SSO/OIDC, SAML, LDAP or another external provider (its server-owned provisioning metadata names scimProviderId or externalProviderId). For such an account:

  • Edit user. The Sign-in setup step shows only how the account signs in. The password choices and Require password change at next sign-in are not shown.
  • The API refuses local-password settings. PUT /api/admin/identity/users/{userId} refuses a set password, enableLocalPassword, and turning on passwordChangeRequired with 400 LOCAL_PASSWORD_NOT_APPLICABLE ("Local password settings do not apply to this account."). It writes, audits and ends nothing. Turning on the forced change without a new password also needs a stored local password, as Reset password does.
  • Conversion is a separate, deliberate step. In Edit user → Sign-in setup, choose Convert to local sign-in and confirm. The API equivalent is PUT /api/admin/identity/users/{userId} with {"username": "...", "convertToLocalSignIn": true, "enableLocalPassword": true}.
    • Who may convert. The same rules as any account change: IDENTITY_MANAGE, * when the person is an administrator, and never your own account. Without the right, the action is not shown. Authorization is checked before the sign-in source, so a refusal for missing rights never reveals how the account signs in.
    • What it does. In one transaction, the server removes the seven provisioning keys, so the account becomes Local. It also removes every external sign-in binding of the account (identity_external_identities), so no provider subject resolves to it any more. It generates a one-time password (shown once, never to an administrative person) and forces a change at next sign-in. It sends the welcome email when SMTP is on, and ends the person's sessions as any administrator password set does.
    • When it is refused. convertToLocalSignIn on a local account, or without enableLocalPassword, is refused with 400 LOCAL_SIGN_IN_CONVERSION_NOT_APPLICABLE, and nothing is written.
    • Audit. Besides the account USER_UPDATED, a separate USER_UPDATED with change: signInSource records the old and new sign-in source: kind (SCIM, EXTERNAL, LOCAL), provider id and provider type, and for SCIM the linked sign-in provider's id and type. It never records the external subject, claims, SCIM external id, password or hash.
    • After converting. A sign-in through the old provider is declined: it finds no binding, and JIT never links by username or email. As defence in depth, JIT and external sign-in also decline any account that has a local password and no provider metadata, and write nothing back. Remove the person from the provider's assignment too, so SCIM stops trying to manage them.
    • New accounts. convertToLocalSignIn on POST /users is refused with 400 LOCAL_SIGN_IN_CONVERSION_NOT_APPLICABLE. A new account is already local.

Reset a password from the user drawer (SCRUM-190)

Authorization → Users → open a person → More actions → Reset password, or POST /api/admin/identity/users/{userId}/password-reset (no body). After a confirmation, the person must choose a new password the next time they sign in, and every session they have ends now. Their current password is not replaced, generated, returned or logged.

  • Local-password accounts only. The reset applies only to an account on Inflow's own identity management: one with a stored local password and no provisioning provider (no SCIM provider, and no SSO/OIDC, SAML, LDAP or other external provider that created or linked it). For any other account the drawer shows no Reset password at all. The server refuses it with 400 PASSWORD_RESET_NOT_APPLICABLE ("Password reset does not apply to this account.") and writes, audits and ends nothing. That person's password belongs to their identity source.
  • Who may. The rules are the same as for a forced password change. You need IDENTITY_MANAGE, and * when the person is an administrator. Nobody resets their own password this way. Authorization is checked before the account's source is considered, so a refusal for missing rights never reveals how the account signs in. Without the right, the drawer shows no Reset password.
  • Audit. One USER_UPDATED (change: passwordChangeRequired, old false, new true) names the administrator. The session end is the "Require password change" row in When sessions end below.
  • When a change is already required, the menu item is shown disabled, with the reason "A password change is already required". The drawer's Security block shows Password: Password change required.

Public origin for sign-in emails

Magic-link emails include a complete, clickable sign-in URL. That URL is built from an operator-configured public origin, not from the inbound request Host (emails are opened on another device; Docker and internal hostnames must not appear in a credential-bearing link).

identity.login.publicBaseUrl=http://localhost:8080
Property / env Role
identity.login.publicBaseUrl Browser-facing Studio origin. Absolute http or https, no credentials, query, or fragment. A path prefix is preserved (https://host/app → https://host/app/login?magicToken=…). Trailing slashes are stripped.
INFLOW_LOGIN_PUBLIC_BASE_URL Environment override. A blank value is ignored so a deployment that sets nothing keeps the properties file.

The committed default is http://localhost:8080 for local development. Production must use https and the hostname people type in a browser. Shared test lanes must set the published Studio URL (for example INFLOW_LOGIN_PUBLIC_BASE_URL=http://185.189.45.171:28180). Missing or invalid configuration fails at API startup rather than sending a relative /login?… path.

The local-password welcome mail still builds its set-password link from the admin request (including X-Forwarded-*). Magic-link mail does not.

User Account Model

UserAccount has two layers.

The first layer is the stable identity core. These fields are part of the Java model because authentication, assignment, authorization, workflow ownership, and audit logging need them consistently:

  • id
  • username
  • displayName
  • firstName
  • middleName
  • lastName
  • preferredName
  • email
  • phoneNumber
  • mobileNumber
  • avatarUrl (the platform's own picture route only; see below)
  • locale
  • timezone
  • employeeNumber
  • jobTitle
  • jobGrade
  • managerUserId
  • costCenter
  • organizationUnit
  • passwordHash
  • roles
  • teams
  • departments
  • groups
  • active
  • locked
  • emailVerified
  • phoneVerified
  • passwordChangeRequired
  • createdAt
  • updatedAt
  • lastLoginAt
  • lockedAt

avatarUrl is set by uploading a picture (POST /api/admin/identity/users/{id}/avatar), which stores /api/admin/identity/users/{id}/avatar?v=<number>. Since SCRUM-4478 the create and update requests accept only that route for the same person, with or without ?v=<digits>. Any other value, including an external https:// address, data:, javascript: or another person's route, is refused with 400 AVATAR_URL_INVALID ("The picture address is not accepted. Upload a picture instead."). A blank or omitted value keeps the stored picture; re-sending the stored value unchanged is allowed. Responses (users, groups, the own session) show a stored address only when it is the record's own route, so a value saved before this rule reads as no picture until a picture is uploaded. Group pictures follow the same rule with /api/admin/identity/groups/{id}/avatar.

The second layer is extensible:

  • attributes: tenant-defined identity fields that can be validated by configuration.
  • preferences: user-facing preferences such as notification behavior, AI preferences, or UI preferences.
  • metadata: system-owned technical metadata from imports, connectors, migrations, and external identity providers.

Configuration File

Custom user profile fields are configured in:

conf/custom_config.properties

The default runtime loader reads that file before identity services are wired. In a production deployment, this file can be mounted through container configuration, a config volume, or replaced by a database-backed configuration adapter later.

Custom Field Format

Every custom field uses this property pattern:

identity.user.custom-fields.<fieldKey>.<property>=<value>

Example:

identity.user.custom-fields.nationalId.enabled=true
identity.user.custom-fields.nationalId.label=National ID
identity.user.custom-fields.nationalId.type=STRING
identity.user.custom-fields.nationalId.required=false
identity.user.custom-fields.nationalId.searchable=true
identity.user.custom-fields.nationalId.unique=true
identity.user.custom-fields.nationalId.sensitive=true

The platform exposes configured fields through UserConfigurationService.userProfileSchema().

Supported Field Properties

enabled: Enables or disables the custom field.

label: Human-readable display label.

type: Field type. Supported values are:

  • STRING
  • TEXT
  • INTEGER
  • DECIMAL
  • BOOLEAN
  • DATE
  • DATETIME
  • EMAIL
  • PHONE
  • URL
  • ENUM
  • USER_REFERENCE
  • GROUP_REFERENCE
  • JSON

required: Requires the field to be present in UserAccount.attributes.

searchable: Marks the field as intended for search indexes in database adapters.

unique: Marks the field as intended to be unique in database adapters.

sensitive: Marks the field as sensitive for masking, audit handling, and export controls.

multiValued: Allows the value to be a collection.

referenceType: Names the referenced actor or external entity type.

defaultValue: Optional default value.

allowedValues: Comma-separated allowed values for enum-like fields.

description: Help text for administrators and UI builders.

Validation Behavior

SchemaUserAccountValidator validates UserAccount.attributes against the configured schema.

It checks:

  • Required custom fields.
  • Unknown custom fields.
  • Basic value type compatibility.
  • Allowed values.
  • Multi-valued fields.

The application assembly injects this validator into JdbcUserAccountRepository, so the durable user path validates configured attributes before saving. The in-memory repository uses the same validator in focused tests and local compositions.

Development Root Account

The development application assembly inserts a local superuser into the JDBC identity repository when development identity data is enabled and that account is missing (no row with id, username, or seed email). A later API start does not overwrite an existing root, designer, or worker row (email, password hash, names, flags). The development API key dev-root-key is inserted the same way: revoke or rotate survives an API recreate.

username: root
password: root

The development API key is:

dev-api-key-root

This account receives the development administrator authority and can perform all platform operations.

These credentials are development-only. Production startup includes an authentication-posture verifier and must not be configured with the seeded root password or development API key.

API Keys and Permission Scopes (S6.1)

Identity API keys (infk_ prefix) can carry permission scopes — least-privilege builder credentials analogous to GitHub fine-grained PATs. Issued through POST /api/admin/identity/api-keys with a scopes array.

The scope taxonomy mirrors the MCP tool domains:

Scope Covers
build Workspaces, data models, screens, themes, forms, contracts, documents
rules Rule definition authoring/validation/execution, approved queries
identity Users, groups, API-key administration
admin Operations, audit, AI configuration, connected systems, integrations, vault, API management
data Records, connectors, Fabric, AI Fabric
runtime Process definitions/instances, tasks, agents, service-task runs, timers, incidents

Enforcement rules (all in the platform's access layer, AccessGuard-adjacent — never bypassed by any client, MCP included):

  • A scoped key's effective permissions are the intersection of the owner's permissions and the key's scope ceiling. A key can never exceed its owner.
  • A key whose scope does not cover a required permission is refused with a scope-named message naming the permission and the valid scopes.
  • Legacy unscoped keys keep working: a key issued without scopes keeps the owner's full permission set.
  • When the password policy's requireScopedApiTokens toggle is enabled, new keys MUST be issued with at least one scope (scopeless issuance is refused); existing keys are never invalidated by the toggle.

whoami (via the MCP get_build_status tool) reports the presenting key's scopes array (empty for legacy keys) so an agent can verify coverage before acting. The raw key value is never included in any response.

Who may manage keys, and audit (spec 302)

Key administration is decided by SecuredApiKeyAdminService, not by the controller:

Route Needs
GET /api/admin/identity/api-keys, read one key IDENTITY_MANAGE. Keys owned by administrative people are left out for callers without *, and reading one answers API_KEY_NOT_FOUND.
POST /api/admin/identity/api-keys, DELETE /api/admin/identity/api-keys/{id} IDENTITY_MANAGE, then *

Every issue writes IDENTITY_API_KEY_ISSUED (name, owner, owner account type ADMINISTRATOR or BASIC, scopes, expiry, issuer) and every revoke writes IDENTITY_API_KEY_REVOKED (reason: administrator). A refusal for * is recorded as ACCESS_DENIED. The key value is shown once in the issue answer and is never written to audit or logs.

Revocation on a high-risk reset: when the password policy switch invalidateApiTokensAfterHighRiskReset is on (default off), an administrator setting or generating a person's password, or the person redeeming a reset or welcome link, revokes every key that person owns (IDENTITY_API_KEY_REVOKED, reason: high-risk-reset). Deactivating or locking a person does not revoke their keys; authentication refuses a key whose owner is inactive or locked, and the key works again after re-enable.

Browser Session Timing

First-party browser session timing is configured in:

conf/custom_config.properties
identity.session.idleTimeoutMinutes=45
identity.session.absoluteTimeoutHours=12
identity.session.continuePromptSeconds=60
identity.session.softProbeIntervalSeconds=60
Property Role
identity.session.idleTimeoutMinutes Documented platform default idle budget (minutes). Live server enforcement always uses the password-policy value returned on GET /api/admin/identity/session — editing this key alone does not change an already-stored policy.
identity.session.absoluteTimeoutHours Documented platform default absolute lifetime (hours). Live enforcement uses the password-policy value.
identity.session.continuePromptSeconds How many seconds before idle expiry Studio opens the shared "Stay signed in?" dialog (returned on the session payload).
identity.session.softProbeIntervalSeconds How often Studio soft-probes the session without refreshing idle lastUsedAt (returned on the session payload).

Studio owns one session lifecycle host for both:

  1. Continue — client idle approaches the budget → modal: Stay signed in / Sign out.
  2. Ended — server session already dead (401 / auth loss) or continue ignored → modal: Session ended / Sign in again, then login with a compact session-expired banner.

Do not configure a second parallel client probe path. Soft probe and continue timing both come from the session payload above.

When sessions end (spec 302)

A credential or standing change ends the person's sessions, whoever makes it (admin API, Tenant Security steps, SCIM, the person). The MCP tokens bound to the ended sessions are revoked in the same transaction.

Change Sessions ended Policy switch
Person completes a forced password change all others; the new session is kept logoutAllSessionsAfterPasswordChange
Person redeems a reset or welcome link all invalidateSessionsAfterReset
Administrator sets or generates a password all logoutAllSessionsAfterPasswordChange
Deactivate all always
Lock all always
"Require password change" set all always
SCIM deprovisioning (active false or DELETE) all always

Re-activating or unlocking restores nothing: the person signs in again. The administrator's own session is never ended by changing someone else. Each change writes USER_CREDENTIAL_CHANGED and, when sessions ended, LOGIN_SESSION_REVOKED. If ending sessions fails, the change is rolled back and the caller is told it was not saved. An ended session answers its next API request with a plain 403.

Magic link, one-time code, passkey and single sign-on do not ask for a password, so they do not apply the "require password change" flag. Setting the flag ends every session, which contains the account until the person changes the password at a password sign-in.

MCP clients follow the browser idle rule: an MCP access token stops working when its bound browser session has been idle longer than the policy's sessionIdleTimeoutMinutes, and a successful MCP request counts as activity on that session. Token use, refresh and code exchange are refused for a person who is inactive or locked.

Local Password Policy

Local password rules are configured as a first-class password policy under:

Authorization / Authentication
  Sign In
    Local Password Policy

The policy exists even when most users authenticate through SSO because local users, administrators, emergency access accounts, service accounts, and non-SSO environments still need enforceable standards.

The default policy is MODERN_RECOMMENDED. Its stored values are listed below; not every stored value is applied yet (see "What the platform enforces"):

  • minimum password length: 15 characters
  • minimum length when MFA is enforced: 8 characters
  • maximum password length: 128 characters
  • spaces and Unicode characters allowed
  • uppercase, lowercase, number, and symbol requirements disabled
  • common-password, breached-password, username, email, profile-name, product-name, and organization-name blocking enabled
  • periodic password expiry disabled
  • forced change after compromise, admin reset, first login, and suspicious activity enabled
  • password reuse prevention enabled for the last 10 passwords
  • soft lock after 5 failed attempts for 15 minutes
  • progressive delay and CAPTCHA-after-failures settings enabled
  • self-service reset enabled with 30-minute single-use reset links
  • admin MFA required
  • service-account interactive login disabled by policy

The policy is available through the authenticated admin API:

GET  /api/admin/identity/password-policy
GET  /api/admin/identity/password-policy/enforcement
PUT  /api/admin/identity/password-policy
POST /api/admin/identity/password-policy/reset

The two reads require IDENTITY_MANAGE. The write and the reset require * (a super administrator); they are decided by SecuredPasswordPolicyService, and a refusal is recorded as ACCESS_DENIED. The reset endpoint restores the modern recommended defaults. Each write that changes something records one PASSWORD_POLICY_UPDATED row with only the changed fields, old and new (change: update or reset); a write that changes nothing records nothing. The stored updater is always the signed-in caller.

Password validation is enforced when local users are created or when an admin sets a new password for an existing local user. The API returns PASSWORD_POLICY_VIOLATION when a supplied password fails the current policy. The current implementation enforces length, Unicode/space constraints, composition toggles, repeated/sequential character checks, common and breached password denylist checks, custom denylist entries, and account-detail blocking. The policy also stores reset, lockout, session, privileged-account, and service-account settings so the UI and future reset/login flows share the same contract.

What the platform enforces

GET /api/admin/identity/password-policy/enforcement returns one status per policy switch (PasswordPolicyEnforcement):

Status Meaning Switches
ENFORCED The platform applies the stored value. minimumLength, maximumLength, allowSpaces, allowUnicode, requireUppercase, requireLowercase, requireNumber, requireSpecial, disallowRepeatedCharacters, disallowSequentialCharacters, disallowUsername, disallowEmail, disallowProfileNames, disallowOrganizationAndProductNames, blockCommonPasswords, customDenylistEnabled, customDenylist, minimumEditDistanceFromBlockedWords, adminMinimumPasswordLength, forceChangeAfterFirstLogin, forceChangeAfterAdminReset, requireScopedApiTokens, apiKeyExpiryRequired, sessionIdleTimeoutMinutes, absoluteSessionLifetimeHours, rememberDeviceEnabled, rememberDeviceDurationDays, logoutAllSessionsAfterPasswordChange, invalidateSessionsAfterReset, invalidateApiTokensAfterHighRiskReset
ALWAYS_ON The behaviour always applies; the switch is stored as on with every write and cannot be turned off. requireMfaDuringResetIfEnrolled (a reset or welcome link asks for the second factor), auditAdminPasswordActions, resetTokenSingleUse, tokenLastUsedTracking, secretShowOnce
NOT_ENFORCED Stored only; the platform does not apply it yet. minimumLengthWithMfa, blockBreachedPasswords, periodicExpiryEnabled, periodicExpiryDays, forceChangeAfterCompromise, forceChangeAfterSuspiciousActivity, preventPasswordReuse, passwordHistoryCount, preventMinorVariations, failedAttemptsBeforeSoftLock, softLockDurationMinutes, progressiveDelayEnabled, captchaAfterRepeatedFailures, notifyUserAfterSuspiciousFailures, notifyAdminAfterHighRiskFailures, permanentLockoutEnabled, selfServiceResetEnabled, resetByEmailLinkEnabled, resetByOtpEnabled, resetLinkExpiryMinutes, requireMfaForAdmins, breakGlassAccountsEnabled, breakGlassAccountCount, breakGlassMonitoringRequired, adminResetRequiresAuditReason, disableInteractiveLoginForServiceAccounts, apiKeyRotationRequired, secretRotationReminder, disableUnusedServiceAccounts, reauthenticateSensitiveActions

So, of the defaults above, the MFA minimum length, breached-password blocking, forced change after compromise or suspicious activity, reuse prevention, soft lock, progressive delay, CAPTCHA, the self-service reset switch and reset-link expiry, admin MFA and the service-account login rule are stored but not applied. requireMfaForAdmins stays not enforced on purpose: enforcing it without a way to enrol a factor at sign-in would lock administrators without a factor out.

Not-enforced switches keep their stored value on every write and reset: the server ignores a new value for them (from Studio or any other client) and does not audit it as a change.

In Studio the Local Password Policy screen shows a "Not enforced yet" badge on not-enforced switches and "Always on" on always-on switches; both are disabled with a plain reason. People who may read but not change the policy (no *) see it in view mode, without Save or Restore. If Studio cannot read which switches the platform applies, the policy opens in view mode with a short note; Refresh tries again. The posture summary counts only checks the platform applies.

Service-Level Security

The platform now enforces access at two layers:

HTTP request -> Spring Security -> Controller -> Secured Service -> Core Service -> Repository

The Spring API authenticates requests first. Then public service beans enforce permissions through secured decorators.

Current secured decorators:

  • SecuredProcessDefinitionService
  • SecuredWorkflowRuntimeService
  • SecuredTaskService
  • SecuredFormDefinitionService
  • SecuredFormSubmissionService

Each decorator uses AccessGuard, which resolves the current actor through CurrentActorProvider and checks permissions through IdentityAccessService.

This means callers cannot bypass authorization just because they reached the service layer. Concrete implementations such as TaskServiceImpl and WorkflowRuntimeServiceImpl remain focused on business behavior, while security policy stays in a dedicated layer.

The current permission mapping is intentionally simple:

  • Process definition operations require PROCESS_DEFINITION_* permissions.
  • Runtime operations require PROCESS_INSTANCE_* permissions, plus RUNTIME_TIMER_LEASE_MANAGE for timer-job lease renewal and release.
  • Task operations require TASK_* permissions.
  • Service-task run operations require SERVICE_TASK_RUN_* permissions, including SERVICE_TASK_RUN_RECOVER_TIMEOUTS for timeout recovery sweeps.
  • Agent-run operations require AGENT_RUN_* permissions, including AGENT_RUN_RECOVER_TIMEOUTS for timeout recovery sweeps.
  • Form definition operations require FORM_DEFINITION_* permissions.
  • Form submission operations require FORM_SUBMISSION_* permissions.
  • Activity catalog access requires ACTIVITY_CATALOG_VIEW.

Identity administration (spec 302)

Every identity-administration write is decided in a secured service. The controllers under /api/admin/identity/** only parse the request, call one secured service and shape the answer; IdentityControllerWriteBoundaryTest fails the build if a controller writes identity data or decides * itself (one reasoned exception: the login asset upload is still decided in LoginAssetController).

Secured service Decides
SecuredGroupService group create, update, parent, activation, delete, membership, group pictures
SecuredGroupPermissionService group permissions
SecuredUserAccountAdministrationService user create and update, status, forced change, MFA reset, profile visibility, user pictures
SecuredMfaAdministrationService factor lists and removal, group MFA requirement
SecuredPasswordPolicyService password policy writes and reset
SecuredApiKeyAdminService identity API key list, read, issue, revoke
SecuredScimAdministrationService SCIM token list, issue, revoke
SecuredLoginAppearanceService login appearance reads, drafts, validate, publish
SecuredAuthProviderAdminService sign-in providers and their group mappings

Terms used below: an administrative permission is any permission the platform does not list as non-administrative, and *. An administrative group holds one directly or through an ancestor (today super-administrators, platform-administrators, application-creators, application-administrators, read-only-auditors, service-accounts; only application-users is ordinary). A privileged group is super-administrators or a group that holds * directly or through an ancestor. An administrative person holds * or any administrative permission.

Group rule (owner decision DEC-18). A caller with GROUP_MANAGE may manage groups, including administrative groups, except:

  • anything involving *: a privileged group (any change, a rename included), placing a group under one, or adding or removing * anywhere needs *;
  • their own membership of any group (GROUP_SELF_MEMBERSHIP_CHANGE, 403);
  • a group they belong to, directly or through a nested group, active or not: its permissions, parent, activation or existence, and its membership when it is administrative (GROUP_OWN_GROUP_CHANGE, 403).

There is no "grant only what you hold" ceiling. Every change to an administrative group's membership, permissions, parent, activation or existence is audited with old and new values and administrative: true, and after it commits every active super administrator with an email address gets one notice mail through the outgoing-mail provider used for welcome mail. Names in the notice are quoted, cut to 80 characters and stripped of line breaks and invisible characters, so a group or display name cannot change the notice's sentence. The outcome is audited as IDENTITY_ADMIN_CHANGE_NOTIFIED (SENT, SKIPPED when mail is off, FAILED); a mail failure never undoes the change. Group pictures need GROUP_MANAGE, and * for a privileged group.

The person and parent a group change names are matched exactly as stored: surrounding spaces are removed before any check, an unknown person or parent is refused, and the checks above apply to the stored person or group.

User rule. Changing another person's account needs IDENTITY_MANAGE, and * when the person is administrative now or would be after the change. Through the admin API a person may change only their own non-security profile fields (names, display name, job title and grade, employee number, cost center, organization unit, locale, time zone, preferences); any other own change is refused with IDENTITY_SELF_CHANGE (403). Deactivating or locking oneself is refused with IDENTITY_SELF_DEACTIVATION or IDENTITY_SELF_LOCK (409). The provisioning metadata keys (scimProviderId, scimExternalId, scimLastSyncedAt, externalProviderId, externalProviderType, externalSubject, externalClaims) can't be added, changed or removed through the admin API (IDENTITY_METADATA_SERVER_OWNED, 400). An administrative person, on creation (including a person created straight into an administrative group) as on update, never gets a generated password in a response; they get a set-password link, and a password set for them must meet the administrator minimum length. If the person changes (for example sets a new password) between the moment an update is prepared and the moment it is written, the update is refused with USER_CHANGED_CONCURRENTLY (409) instead of overwriting it. Pictures: one's own, otherwise IDENTITY_MANAGE and * for an administrative person.

MFA and policy rule. Removing someone's factor needs IDENTITY_MANAGE, and * when the owner is administrative; removing one's own factor through the admin API is refused (IDENTITY_SELF_CHANGE). The group MFA requirement (after IDENTITY_MANAGE), the password policy, key and SCIM token issue and revoke, sign-in provider writes and login appearance changes need *.

Refusals for *, self changes and own-group changes are recorded as ACCESS_DENIED (operation, target, requirement) in their own transaction, so the record stays when the change is rolled back. A refused group key is recorded the same way (SCRUM-3883). This covers creating or renaming a group onto a built-in or permission-bearing role id (GROUP_ROLE_KEY_CONFLICT, or SCIM's SCIM_PROTECTED_GROUP), and editing the grants of a group stored with a built-in role id. The record holds only the actor, the target group id, path (admin-api, scim, tenant-security), attempt (create, rename, grant-edit) and keyClassification (built-in, permission-bearing). It never holds the key, the grants or a token. User and group reads carry per-object capabilities (and the group permission read grantable) so Studio can hide what the caller may not do; the server still decides every request.

Example: Adding a Tenant Field

To add an approval limit to users without changing Java code:

identity.user.custom-fields.approvalLimit.enabled=true
identity.user.custom-fields.approvalLimit.label=Approval Limit
identity.user.custom-fields.approvalLimit.type=DECIMAL
identity.user.custom-fields.approvalLimit.required=false
identity.user.custom-fields.approvalLimit.searchable=true

Then store the value in the account:

userAccount.attributes().get("approvalLimit")

Or create a copy with:

UserAccount updated = userAccount.withAttribute("approvalLimit", 25000.00);

Use core fields for identity concepts the platform must always understand.

Use attributes for tenant-specific fields that affect workflows, assignment, reporting, eligibility, or policy.

Use preferences for things controlled by the end user.

Use metadata for integration and migration details that should not be treated as business profile data.

Use external authentication provider settings for login, SSO, directory lookup, and passkey/WebAuthn behavior. Provider-derived technical values such as issuer, subject, tenant ID, and raw group claims should normally land in metadata; business attributes derived from those claims can be copied into attributes when workflow rules need them.

Feature configuration authority

Provider/custom-field/CAPTCHA and authentication feature switches use the canonical file and restart semantics documented in Feature switches. Native HTTP/MCP administrator writes and coordinated direct edits update that same file. The flag API exposes no provider secrets; provider metadata, credentials, object permissions and native business settings retain their existing boundaries.

Current source addition — trusted natural-person binding API (PR #4521)

Scope. Current source adds an administrative API for explicitly attesting that one existing account belongs to a canonical natural person. This is not a Studio control, an identity-document verifier, a login method, or a permission grant. The endpoint does not infer equivalence from display names, email addresses, employee numbers, profile attributes or provider claims. Its existence does not complete the separate application task-approval writer or authorize a task decision.

Authority and evidence. Use this operation only as an authorized identity security administrator with IDENTITY_MANAGE and unrestricted (*) authority; the service refuses self-change. Before writing, verify the person's identity through the organization's approved identity process. Reuse one opaque, nonzero canonical UUID for every account known to belong to that person, and provide a nonsecret reference to the verification record. Do not put identity documents, national identifiers, credentials or explanatory personal data in verificationRef; the API validates its safe reference format, not the underlying evidence.

The two routes are:

GET /api/admin/identity/users/{userId}/natural-person-binding
PUT /api/admin/identity/users/{userId}/natural-person-binding

For the PUT, send the exact existing account ID and a JSON body such as this synthetic example:

{
  "personKey": "9b4e2e3c-6050-41cb-9d45-652f63b9c183",
  "verificationRef": "IAM-CASE-EXAMPLE-42"
}

Use a real canonical key and verification reference only when the owner has approved the attestation. Read the PUT result and then GET the same account to confirm its binding. Call each account separately; retain the exact returned account identifier and the returned attestedBy, attestedAt and verificationRef only in the approved administrative record system. A first binding emits one USER_UPDATED audit event; an exact repeat does not emit a second binding event. Do not copy a complete response into ordinary user-facing records or logs.

Repeat and recovery behavior. Repeating the exact same person key and verification reference returns the existing binding and does not create a second binding audit event. A different key or changed evidence reference is refused; bindings are immutable and tied to that account incarnation. The historical binding remains after account deletion so a later account cannot silently inherit its identity. Generic profile, provisioning and sign-in conversion operations cannot rewrite it; converting to local sign-in preserves the binding. If the account has already been bound differently, stop and use the identity owner's separately authorized correction process. There is no implicit unbind, reassociation or provider-claim adoption route.

This API exposes no general person-comparison operation to ordinary users. Its internal comparison is usable only by authorized server-side policy and fails closed for missing, inactive, replaced or unbound accounts. Binding two accounts proves only the administrator's recorded attestation; it does not change their groups, roles, sessions, application access, records, tasks or business decisions.

Source and limits. See the trusted-binding contract, AdminIdentityController.java, and SecuredUserAccountAdministrationService.java. This update describes current source behavior; it does not claim a deployed runtime or make any live identity changes.

Try “document generation”, “integrations” or “first form”.