check_user_account()

Prüft, ob sich ein Benutzer mit dem angegebenen Passwort anmelden kann - nach denselben Kriterien wie der enaio® enterprise-manager. Das ist die echte Anmeldedatenprüfung: Das Passwort wird mit dem gespeicherten Passwort des Kontos verglichen (im Gegensatz zu check_password_complexity(), das nur die Passwortregel prüft).

Neben dem Passwort beantwortet der Job auch, ob das Konto existiert, ob es gesperrt ist und wie lange das Passwort noch gültig ist.

Der Session-Benutzer braucht die Systemrolle SERVER_SWITCH_JOB_CONTEXT (serverseitig R_SRV_SWITCH_CONTEXT, im enterprise-manager JobKontext wechseln - dieselbe Rolle, die auch die $SwitchContextUser*$-Parameter hinter impersonate() verlangen). Fehlt sie, schlägt der Job mit ECMAccessDeniedException fehl - egal, welches Konto geprüft wird. check_password_complexity() braucht die Rolle nicht.

Fehlversuche zählen wie bei einer echten Anmeldung auf die Kontosperre ein; ein erfolgreicher Aufruf setzt den Zähler zurück. Die Schwelle ist über die API nicht auslesbar, also selbst begrenzen - eine Schleife über Passwortkandidaten sperrt das Konto.

1. Signatur

  • Sync

  • Async

ecm.security.check_user_account(username: str, password: str) -> ECMUserAccountCheck
await ecm.security.check_user_account(username: str, password: str) -> ECMUserAccountCheck

2. Parameter

Parameter Standard Beschreibung

username

erforderlich

Anmeldename des Kontos, z.B. "john". Gross-/Kleinschreibung egal - der Server liefert die interne Schreibweise im Ergebnis zurück.

password

erforderlich

Das zu prüfende Passwort im Klartext (oder ein mit ECMIND_KEY verschlüsselter Wert). Es wird vor dem Senden mit dem Verfahren kodiert, das der Server verlangt (Security\PwdDecryption).

Das Server-Handbuch führt Password als optional (reine Existenzprüfung über den Namen). enaio® 12.0 weist den Aufruf ohne Passwort ab, deshalb sendet die Methode immer eines.

3. Rückgabewert

ECMUserAccountCheck:

Attribut Typ Beschreibung

status

ECMUserAccountStatus

Ergebnis der Prüfung, siehe Tabelle unten.

username

str

Interner Benutzername (InternalName), wie der Server ihn auflöst, z.B. "ROOT". Fällt auf den angefragten Namen zurück, wenn der Server keinen liefert.

login_method

str

Authentifizierungsverfahren, z.B. "AS" für die enaio-interne Benutzerverwaltung. Leer, wenn die Prüfung nicht erfolgreich war.

password_expires_in_days

int | None

Restgültigkeit innerhalb des konfigurierten Login\PasswordExpirationInterval: -1 = läuft innerhalb des Gültigkeitszeitraums nicht ab (auch wenn der Zeitraum mit 0 abgeschaltet ist), 0 = abgelaufen und muss geändert werden - das meldet auch ein Einmalpasswort -, sonst Anzahl Tage bis zum Ablauf (0 wäre der aktuelle Tag). None, wenn die Prüfung nicht erfolgreich war.

login_possible

bool (Property)

True, wenn status gleich LOGIN_POSSIBLE ist.

password_expired

bool (Property)

True, wenn password_expires_in_days gleich 0 ist - also bei abgelaufenem Passwort und bei einem noch nicht geänderten Einmalpasswort.

ECMUserAccountStatus:

Wert Code Bedeutung

LOGIN_POSSIBLE

0

Konto existiert, ist nicht gesperrt, Passwort stimmt.

USER_UNKNOWN

2

Kein Konto mit diesem Anmeldenamen.

LOCKED_BY_WRONG_PASSWORD

3

Konto wurde gerade durch zu viele Fehlversuche gesperrt.

WRONG_PASSWORD

4

Passwort falsch, ein weiterer Versuch ist möglich.

ACCOUNT_LOCKED

5

Konto war bereits gesperrt, Anmeldung nicht möglich.

Falsches Passwort, unbekannter Benutzer und gesperrtes Konto werfen keine Exception - das sind erwartete Ausgänge einer Anmeldeprüfung und kommen als Status zurück. Der Server meldet sie als Jobfehler statt über die dokumentierten Action-Werte 2/4/5; die Methode übersetzt diese Fehlercodes in den passenden Status. Andere Serverfehler bleiben Fehler.

Als Erfolg gilt ausschliesslich Action = 0. Ein fehlender oder unbekannter Wert ist eine Ablehnung, damit eine abweichende Serverantwort keine offene Tür wird.

4. Fehler

Exception Ursache

ValueError

username oder password ist leer, oder das Passwort lässt sich im Verfahren des Servers nicht darstellen (z.B. mehr als 62 Zeichen auf einem Server mit PwdDecryption=1).

ECMAccessDeniedException

Dem Session-Benutzer fehlt die Systemrolle SERVER_SWITCH_JOB_CONTEXT.

ECMException

Unterklasse, die raise_for_blue_exception bei einem anderen Serverfehler auslöst.

5. Beispiele

5.1. Anmeldedaten prüfen

  • Sync

  • Async

from ecmind_blue_client.ecm import ECMUserAccountStatus

check = ecm.security.check_user_account("john", "S3cret!")

if check.login_possible:
    print(f"Anmeldung möglich als {check.username} über {check.login_method}")
    if check.password_expired:
        print("Passwort ist abgelaufen und muss geändert werden")
    elif check.password_expires_in_days > 0:
        print(f"Passwort läuft in {check.password_expires_in_days} Tagen ab")
elif check.status is ECMUserAccountStatus.WRONG_PASSWORD:
    print("Passwort falsch")
elif check.status is ECMUserAccountStatus.USER_UNKNOWN:
    print("Benutzer unbekannt")
else:
    print("Konto gesperrt")
from ecmind_blue_client.ecm import ECMUserAccountStatus

check = await ecm.security.check_user_account("john", "S3cret!")

if check.login_possible:
    print(f"Anmeldung möglich als {check.username} über {check.login_method}")
elif check.status is ECMUserAccountStatus.WRONG_PASSWORD:
    print("Passwort falsch")

5.2. Ablaufende Passwörter melden

for user in ecm.security.users():
    check = ecm.security.check_user_account(user.username, service_passwords[user.username])
    if check.login_possible and 0 <= check.password_expires_in_days <= 14:
        print(f"{check.username}: Passwort läuft in {check.password_expires_in_days} Tagen ab")

6. Serverseitige Einstellungen

Ablauf und Sperrverhalten steuern vier Parameter im enaio® enterprise-manager (Servereigenschaften, Bereich Anmeldung):

enterprise-manager Registry-Eintrag Bedeutung

Gültigkeitszeitraum für Passwörter

Login\PasswordExpirationInterval

"Sie geben einen Zeitraum in Tagen an, über den ein Passwort gültig ist. Der Wert '0' schaltet diese Funktion aus." Standard: 0. Ist die Funktion aus, meldet password_expires_in_days immer -1.

Hinweis auf den Ablauf des Gültigkeitszeitraums

Login\PasswordExpirationWarning

"Sie geben einen Wert in Tagen an, ab dem der Benutzer beim Login einen Hinweis auf den Ablauf des Passwortes erhält." Standard: 5. Betrifft die Hinweismeldung von enaio, nicht den von check_user_account() gelieferten Wert.

Sicherheitsstufe

Login\SecurityLevel

Verhalten bei fehlgeschlagenen Anmeldungen: Standard 0 = keine Einschränkung, darüber Beendigung der Anwendung bzw. Sperrung des Kontos nach drei Fehlversuchen. Gilt nicht für Benutzer mit Zwei-Faktor-Authentifizierung. Über die API nicht auslesbar.

Einmalpasswort

Login\PasswordSingleUse

"Neue Benutzer werden mit Einmalpasswort angelegt, sie müssen beim Anmelden an enaio® sofort ihr Passwort ändern." Standard: 0. Ein solches Konto meldet password_expires_in_days = 0 (verifiziert gegen enaio® 12.0). Pro Konto steuert das das Attribut change_pwd, siehe create_user().

Die Parameter sind in der enaio®-Administratordokumentation unter den Servereigenschaften beschrieben, die Job-Parameter Action und PwdExpires in der enaio® server-api-Referenz.

7. Hinweise

  • Die Prüfung läuft in der bestehenden Session; der Job baut keine Sitzung für den geprüften Benutzer auf, sondern liefert nur das Prüfergebnis.

  • Das Passwort niemals selbst im Klartext übergeben: Der Server dekodiert den Wert und meldet Klartext als "Invalid password". Die Methode kodiert deshalb grundsätzlich selbst.

  • Ob Fehlversuche zur Sperre führen, steuert die Sicherheitsstufe (Login\SecurityLevel, Standard 0 = keine Einschränkung; darüber Beendigung der Anwendung bzw. Sperrung des Kontos nach drei Fehlversuchen). Der Zähler gilt pro Konto, andere Benutzer bleiben unbeeinträchtigt.

  • Eine Sperre aus Fehlanmeldungen ist an den Kontoattributen nicht erkennbar: user() meldet weiterhin locked = False, während diese Prüfung ACCOUNT_LOCKED liefert.

8. Siehe auch

  • check_password_complexity() — Passwortregel prüfen (keine Anmeldedatenprüfung, keine Rolle nötig)

  • roles() — Systemrollen des Benutzers prüfen

  • user() — Kontoattribute inkl. locked, valid_to, change_pwd

  • update_user() — Konto entsperren oder Passwort setzen