krn.CheckUserAccount

Dieser Job überprüft, ob der angegebene Benutzer sich am System anmelden kann. Das übergebene Passwort wird geprüft — ein falsches Passwort kann zur Sperrung des Accounts führen (gleiche Kriterien wie im enaio® enterprise-manager).

Der Job kehrt mit einem Fehler zurück, wenn der Benutzer sich nicht am System anmelden kann.

Der Job läuft auf der bestehenden Session und öffnet keine Session für den geprüften Benutzer — er liefert keine SessionGUID, sondern ausschließlich das Prüfergebnis.

1. Eingabeparameter

Name Typ Pflicht Beschreibung

Flags

INT

Ja

Muss 0 sein.

UserName

STRING

Ja

Anmeldename des Benutzers. Wird ohne Beachtung der Groß-/Kleinschreibung aufgelöst.

Password

STRING

Ja

Verschlüsseltes Passwort — gleiches Format wie krn.SessionLogin/UserPwd, Kodierungsverfahren gemäß Registry-Eintrag Security\PwdDecryption. Klartext wird mit -1042218021 („Invalid password") abgewiesen — anders als bei krn.VerifyPassword kann eine falsche Kodierung hier also nicht unbemerkt bleiben.
Password ist ein Pflichtparameter. Ein Aufruf ohne diesen Parameter — etwa als reine Existenzprüfung des Benutzernamens — wird mit -1043332470 („A required parameter was not specified: Password.") abgewiesen.

2. Ausgabeparameter

Name Typ Abhängigkeit Beschreibung

Action

INT

—

Ergebnis der Anmeldeprüfung:
0 = Anmelden ist möglich
2 = Benutzer nicht bekannt
3 = Account gesperrt durch falsches Passwort, Anmelden nicht möglich
4 = Falsches Passwort, erneutes Anmelden ist möglich
5 = Account bereits gesperrt, Anmelden nicht möglich

PwdExpires

INT

nur bei Action = 0

Gültigkeit des Passworts:
-1 = Passwort läuft nicht innerhalb des Gültigkeitszeitraums ab. Dies ist auch die Antwort eines Servers ohne Passwortablauf, also bei Login\PasswordExpirationInterval = 0 (Standard).
0 = Passwort muss geändert werden, bevor der Benutzer arbeiten kann. Neben dem tatsächlich abgelaufenen Passwort deckt dieser Wert auch das Einmal-Passwort ab (Login\PasswordSingleUse global bzw. das Attribut changepwd je Account, siehe mng.SetUserAttributes) — dort ist das Passwort nie abgelaufen.
n = Anzahl der Tage bis zum Ablauf. Der Wert 0 würde „läuft heute ab" bedeuten und fällt damit mit dem Fall oben zusammen.

InternalName

STRING

nur bei Action = 0

Interner Benutzername in der Schreibweise, in der der Server ihn aufgelöst hat, z. B. ROOT. Da UserName ohne Beachtung der Groß-/Kleinschreibung aufgelöst wird, liefert dieser Parameter die kanonische Schreibweise.

LoginMethod

STRING

nur bei Action = 0

Authentifizierungsverfahren, z. B. AS für die enaio®-interne Benutzerverwaltung.

3. Rückgabe

(INT): 0 = Job erfolgreich, sonst Fehlercode.

In der Praxis tritt nur Action = 0 auf: Die in der Tabelle dokumentierten Fehlerfälle 2, 3, 4 und 5 kommen stattdessen als Fehlercode zurück — passend dazu, dass der Job mit einem Fehler zurückkehrt, wenn der Benutzer sich nicht anmelden kann.

Code Server-Meldung Entspricht Action

-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.

— (Aufrufer nicht berechtigt)

-1042218019 wird sowohl für einen manuell gesperrten Account als auch für einen durch Fehlanmeldungen gesperrten Account geliefert, und zwar auch bei korrektem Passwort. Die beiden Fälle sind aus der Antwort nicht unterscheidbar.

Als Erfolg dürfen nur return_code = 0 und Action = 0 gewertet werden. Ein fehlendes oder unbekanntes Action muss zu einer Ablehnung führen — eine Positivliste bekannter Fehlercodes wird zur offenen Tür, sobald eine Serverversion anders antwortet.

4. Benötigte Systemrolle

Der aufrufende Benutzer benötigt die Systemrolle 72 (Server: Jobkontext wechseln, R_SRV_SWITCH_CONTEXT) — dieselbe Rolle, die auch die Parameter $$$SwitchContextUser*$$$ voraussetzen (siehe Wechsel des Benutzerkontextes). Fehlt sie, wird der Aufruf mit dem Fehlercode -1042218022 abgewiesen; der zugehörige Fehlertext lautet:

The system role R_SRV_SWITCH_CONTEXT is not present.

Die Rolle ist notwendig und ausreichend und von allen anderen Rollen unabhängig: Ein Benutzer, der ausschließlich diese Rolle besitzt, ist erfolgreich; ein Benutzer mit den 71 anderen Rollen scheitert mit -1042218022. Normale Benutzer können den Job damit nicht selbst aufrufen — er ist für Hintergrundprozesse und technische Accounts gedacht.

Die dem aufrufenden Benutzer zugewiesenen Systemrollen lassen sich mit mng.GetUserRoles ermitteln; eine Übersicht aller Rollen findet sich unter Systemrollen.

5. Sperrverhalten

  • Der Fehlversuchszähler gilt pro Account; andere Accounts sind nicht betroffen.

  • Ein erfolgreicher Aufruf setzt den Zähler zurück. Abwechselnd korrekte und falsche Prüfungen lösen die Sperre daher nie aus.

  • Was ein Fehlversuch bewirkt, steuert die Sicherheitsstufe (Login\SecurityLevel, Standard 0 = keine Einschränkung; die übrigen Stufen schließen die Anwendung bzw. sperren den Account nach drei Fehlversuchen). Für Benutzer mit Zwei-Faktor-Authentifizierung gilt die Einstellung nicht.

  • Der Schwellwert ist über die API nicht lesbar — Einträge wie Security\PwdLockCount, MaxLoginAttempts oder LoginRetries existieren nicht (krn.REGetRegValue liefert -1042218742). Aufrufer müssen ihre Versuche selbst begrenzen.

Eine durch Fehlanmeldungen entstandene Sperre ist in den Benutzerattributen nicht sichtbar. mng.GetUserAttributes meldet für einen so gesperrten Account weiterhin locked = 0, während krn.CheckUserAccount den Zugang mit -1042218019 verweigert. Das Attribut taugt damit nicht zur Erkennung dieses Zustands; dieser Job ist die einzige Quelle. Ob die Sperre über die API aufgehoben werden kann, ist offen — mng.SetUserAttributes mit ausschließlich UserGUID und Locked scheitert mit -1043332470.

6. Zugehörige Einstellungen

enaio® enterprise-manager Registry-Eintrag Standard Wirkung auf diesen Job

Gültigkeitszeitraum für Passwörter

Login\PasswordExpirationInterval

0 (aus)

0 → PwdExpires ist immer -1

Hinweis auf den Ablauf des Gültigkeitszeitraums

Login\PasswordExpirationWarning

5

steuert die Warnung von enaio® selbst, nicht PwdExpires

Einmal-Passwort

Login\PasswordSingleUse

0

neue Accounts melden PwdExpires = 0

Sicherheitsstufe

Login\SecurityLevel

0

ob Fehlversuche den Account sperren

7. Siehe auch