krn.CheckUserAccount

This job checks whether the specified user can log into the system. The given password is checked — an incorrect password can lead to account lockout (same criteria as in the enaio® enterprise-manager).

The job returns with an error if the user cannot log into the system.

The job runs on the existing session and does not open a session for the checked user — it returns no SessionGUID, only the verdict.

1. Input Parameters

Name Type Required Description

Flags

INT

Yes

Must be 0.

UserName

STRING

Yes

Login name of the user. Matched case-insensitively.

Password

STRING

Yes

Encrypted password — same format as krn.SessionLogin/UserPwd, encoding scheme according to the registry entry Security\PwdDecryption. Plaintext is rejected with -1042218021 ("Invalid password") — so unlike krn.VerifyPassword, a wrong encoding cannot pass unnoticed here.
Password is a mandatory parameter. A call without it — for instance as a name-only existence check — is rejected with -1043332470 ("A required parameter was not specified: Password.").

2. Output Parameters

Name Type Dependency Description

Action

INT

—

Result of login check:
0 = login is possible
2 = user not known
3 = account locked by wrong password, login not possible
4 = wrong password, re-login possible
5 = account already locked, login not possible

PwdExpires

INT

only when Action = 0

Password validity:
-1 = password does not expire within the validity period. This is also what a server without password expiry reports, i.e. when Login\PasswordExpirationInterval is 0 (default).
0 = the password must be changed before the user can work. Besides an actually expired password, this value also covers a one-time-password account (Login\PasswordSingleUse globally, or the changepwd attribute per account, see mng.SetUserAttributes) — where the password never ran out.
n = number of days until expiration. The value 0 would mean "expires today" and therefore collapses with the case above.

InternalName

STRING

only when Action = 0

Internal user name in the spelling the server resolved it to, e.g. ROOT. Since UserName is matched case-insensitively, this parameter returns the canonical spelling.

LoginMethod

STRING

only when Action = 0

Authentication method, e.g. AS for the enaio®-internal user administration.

3. Return Value

(INT): 0 = job successful, otherwise error code.

In practice only Action = 0 occurs: the failure cases 2, 3, 4 and 5 documented in the table come back as an error code instead — consistent with the job returning an error if the user cannot log in.

Code Server message Documented Action equivalent

-1042218023

User name <x> is unknown.

2

-1042218021

Invalid password

4

-1042218019

Your user account is blocked. Please contact your system administrator.

3 / 5

-1042218022

The system role R_SRV_SWITCH_CONTEXT is not present.

— (caller not authorised)

-1042218019 is returned both for a manually locked account and for one locked by failed logins, and also with a correct password. The two cases are not distinguishable from the response.

Treat only return_code = 0 and Action = 0 as success. A missing or unrecognised Action must lead to a rejection — a positive list of known error codes turns into an open door as soon as a server version answers differently.

4. Required System Role

The calling user needs system role 72 (Server: Switch job context, R_SRV_SWITCH_CONTEXT) — the same role the $$$SwitchContextUser*$$$ parameters require (see Switching the User Context). If it is missing, the call is rejected with the error code -1042218022; the associated error text reads:

The system role R_SRV_SWITCH_CONTEXT is not present.

The role is necessary and sufficient and independent of every other role: a user holding only this role succeeds; a user holding the other 71 roles fails with -1042218022. Normal users therefore cannot call the job themselves — it is meant for background processes and technical accounts.

The system roles assigned to the calling user can be determined with mng.GetUserRoles; an overview of all roles is available under System Roles.

5. Lockout Behaviour

  • The failed-attempt counter is per account; other accounts are unaffected.

  • A successful call resets the counter. Alternating correct and wrong checks therefore never trip the lock.

  • What a failed attempt does is governed by the security level (Login\SecurityLevel, default 0 = no restriction; the other levels close the application or lock the account after three failed attempts). The setting does not apply to users with two-factor authentication.

  • The threshold is not readable through the API — entries such as Security\PwdLockCount, MaxLoginAttempts or LoginRetries do not exist (krn.REGetRegValue returns -1042218742). Callers must throttle their own attempts.

A lockout caused by failed logins is not visible in the user attributes. For an account locked this way, mng.GetUserAttributes keeps reporting locked = 0 while krn.CheckUserAccount refuses access with -1042218019. The attribute is therefore unusable for detecting this state; this job is the only source. Whether the lock can be released through the API is open — mng.SetUserAttributes with only UserGUID and Locked fails with -1043332470.

6. Related Settings

enaio® enterprise-manager Registry entry Default Effect on this job

Gültigkeitszeitraum für Passwörter

Login\PasswordExpirationInterval

0 (off)

0 → PwdExpires is always -1

Hinweis auf den Ablauf des Gültigkeitszeitraums

Login\PasswordExpirationWarning

5

drives enaio®'s own warning, not PwdExpires

Einmal-Passwort

Login\PasswordSingleUse

0

new accounts report PwdExpires = 0

Sicherheitsstufe

Login\SecurityLevel

0

whether failed attempts lock the account

7. See Also