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 this job’s response; the user attribute locked (see Lockout Behaviour) and a context switch to the user (see Cause Codes in the Error Stack) do distinguish them.

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 server counts failed attempts per account in the attribute logincount; other accounts are unaffected. 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.

Sequence on a server that locks after three failed attempts:

Call logincount locked Return value

1st wrong password

1

0

-1042218021 ("Invalid password")

2nd wrong password

2

0

-1042218021

3rd wrong password

3

2

-1042218021 — the lock already closes here

every further call, including one with the correct password

3

2

-1042218019 ("…account is blocked")

  • The third failed attempt locks the account but still answers -1042218021. A caller watching for -1042218019 to detect the moment the lock closed will miss it.

  • A successful call resets logincount to 0 as long as the lock has not closed yet — alternating correct and wrong checks therefore never trip it. Once the account is locked, the correct password is refused as well and the counter stays at its maximum; only an administrative reset helps then (see below).

  • The threshold itself is not readable through the API — entries such as Security\PwdLockCount, MaxLoginAttempts or LoginRetries do not exist (krn.REGetRegValue returns -1042218742). With Name = Login\SecurityLevel a caller can only read whether failed attempts lock accounts, not after how many. Callers must throttle their own attempts.

5.1. Detecting and Releasing a Lock

The user attribute locked distinguishes the two kinds of lock: 1 = locked manually by an administrator, 2 = locked by failed logins. Both values are reported by mng.GetUserAttributes and mng.GetUserList.

The marker 2 only survives until the next write. mng.SetUserAttributes always writes locked along with everything else, so any unrelated change — to the remark or the e-mail address, say — replaces the value 2 with 0 without unlocking the account. Further failed attempts do not restore the marker, because logincount is already at its maximum; from then on the lock is only detectable through this job or through a context switch.

What enforces the lock is logincount, not locked — writing locked = 0 alone does not release it. The account is released by calling mng.SetUserAttributes with a complete UserInfo for the account and logincount="0"; immediately afterwards this job reports Action = 0 again.

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; the only entry listed here that is readable via krn.REGetRegValue

7. See Also