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 dieses Jobs nicht unterscheidbar; das Benutzerattribut locked (siehe Sperrverhalten) und ein Kontextwechsel auf den Benutzer (siehe Ursachencodes im Fehlerstack) unterscheiden sie.

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

Fehlversuche zählt der Server pro Account im Attribut logincount; andere Accounts sind nicht betroffen. 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.

Verlauf auf einem Server, der nach drei Fehlversuchen sperrt:

Aufruf logincount locked Rückgabe

1. falsches Passwort

1

0

-1042218021 („Invalid password")

2. falsches Passwort

2

0

-1042218021

3. falsches Passwort

3

2

-1042218021 — die Sperre greift hier bereits

jeder weitere Aufruf, auch mit korrektem Passwort

3

2

-1042218019 („…account is blocked")

  • Der dritte Fehlversuch sperrt den Account, antwortet aber weiterhin mit -1042218021. Wer auf -1042218019 wartet, um das Zuschnappen der Sperre zu erkennen, verpasst den Moment.

  • Ein erfolgreicher Aufruf setzt logincount auf 0 zurück, solange die Sperre noch nicht zugeschnappt ist — abwechselnd korrekte und falsche Prüfungen lösen sie daher nie aus. Ist der Account gesperrt, wird auch das korrekte Passwort abgewiesen und der Zähler bleibt auf seinem Maximum; dann hilft nur ein administratives Zurücksetzen (siehe unten).

  • Der Schwellwert ist über die API nicht lesbar — Einträge wie Security\PwdLockCount, MaxLoginAttempts oder LoginRetries existieren nicht (krn.REGetRegValue liefert -1042218742). Lesbar ist mit Name = Login\SecurityLevel lediglich, ob Fehlversuche sperren — nicht, nach wie vielen. Aufrufer müssen ihre Versuche selbst begrenzen.

5.1. Sperre erkennen und aufheben

Das Benutzerattribut locked unterscheidet die beiden Sperrarten: 1 = manuell durch einen Administrator gesperrt, 2 = durch Fehlanmeldungen gesperrt. Beide Werte liefern mng.GetUserAttributes und mng.GetUserList.

Die Markierung 2 überlebt nur bis zum nächsten Schreibzugriff. mng.SetUserAttributes schreibt locked immer mit, sodass jede beliebige Änderung — etwa an der Bemerkung oder der E-Mail-Adresse — den Wert 2 durch 0 ersetzt, ohne den Account zu entsperren. Weitere Fehlversuche stellen die Markierung nicht wieder her, weil logincount bereits am Maximum steht; die Sperre ist dann nur noch über diesen Job oder über einen Kontextwechsel erkennbar.

Maßgeblich für die Sperre ist logincount, nicht locked — ein Schreiben von locked = 0 allein hebt sie nicht auf. Entsperrt wird der Account, indem mng.SetUserAttributes mit einer vollständigen UserInfo des Accounts und logincount="0" aufgerufen wird; unmittelbar danach meldet dieser Job wieder Action = 0.

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; als einziger der hier genannten Einträge über krn.REGetRegValue lesbar

7. Siehe auch