Skip to content
Open
Show file tree
Hide file tree
Changes from 25 commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
eafd7ad
fix(docs): only unlock accounts the lock script locked
mo-auto Nov 18, 2026
edef92e
fix(docs): keep admin changes made during a lock
mo-auto Nov 18, 2026
f37e4e7
fix(docs): match lock updatedAt exactly on unlock
mo-auto Nov 18, 2026
6f32447
feat(jans-orm): CAS on entries without a version
mo-auto Nov 18, 2026
bdd3e8c
feat: version jansPerson entries
mo-auto Nov 18, 2026
63e3085
fix(docs): use versioned writes in basic lock script
mo-auto Nov 18, 2026
bcc1c98
test(ci): read config-api user status key
mo-auto Nov 18, 2026
237c046
test(ci): check basic-lock unlock after expiry
mo-auto Nov 18, 2026
8b151eb
fix(docs): record stored updatedAt in lock marker
mo-auto Nov 18, 2026
78c28af
test(ci): patch user status with enum name
mo-auto Nov 19, 2026
6e63ec5
Merge branch 'pr-15743' into feat/basic-lock-cas
mo-auto Nov 19, 2026
5f26a93
feat(jans-orm): CAS plain merge on versioned entries
mo-auto Nov 19, 2026
5d19709
fix(docs): count and lock in one versioned write
mo-auto Nov 19, 2026
b76cfd2
docs: bump jansVersion in manual user updates
mo-auto Nov 19, 2026
645b264
fix(jans-auth-server): keep inherited User equality
mo-auto Nov 19, 2026
efbfd8d
refactor(jans-orm): simplify versioned merge loop
mo-auto Nov 19, 2026
e453c71
fix(jans-orm): keep first-read changes on merge retry
mo-auto Nov 19, 2026
23b4416
feat: version Casa, Link and SCIM person entities
mo-auto Nov 19, 2026
94b20cc
docs: quote jansVersion in PgSQL update, list versioned writers
mo-auto Nov 19, 2026
44a93b0
fix(jans-scim): drop version from read-only SimplePerson
mo-auto Nov 19, 2026
4f7f8a1
fix(jans-orm): fail merge instead of unchecked write
mo-auto Nov 19, 2026
66bcd99
docs: note stale-read writers can lift a lock early
mo-auto Nov 19, 2026
facfef4
docs: scope basic lock guarantee to versioned writers
mo-auto Nov 19, 2026
e07f66b
Merge branch 'main' of https://github.com/JanssenProject/jans into fe…
mo-auto Nov 19, 2026
cf6a598
fix(jans-config-api): CAS user updates on caller's read
mo-auto Nov 19, 2026
a9f7b3f
fix(jans-config-api): keep stored status on PUT w/o status
mo-auto Nov 19, 2026
97d93b3
Merge branch 'main' of https://github.com/JanssenProject/jans into fi…
mo-auto Nov 19, 2026
06e5088
fix(jans-config-api): 409 on PUT racing status change
mo-auto Nov 19, 2026
bf869b2
docs: narrow Config API lock guarantee in README
mo-auto Nov 19, 2026
356fad0
fix(jans-config-api): check role change before first save
mo-auto Nov 19, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion docs/janssen-server/reference/database/mysql-ops.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,16 @@ Say we want to increase the size of `mail` field to 144. Do the following:<br>
* c. Ensure you restart services after DB schema modification


### Add user version column on upgrade
User updates are versioned through the `jansVersion` column of `jansPerson`. Container and Kubernetes
deployments add it automatically through the persistence loader. On a VM install, add it before
upgrading the Janssen services:
```
ALTER TABLE `jansdb`.`jansPerson` ADD COLUMN `jansVersion` BIGINT NULL DEFAULT NULL;
```
Existing rows keep a `NULL` version until their next update. Manual `UPDATE` statements on `jansPerson`
should also set `jansVersion = COALESCE(jansVersion, 0) + 1`, so concurrent versioned writes notice the change.

### Add user in Jans admin group

* Search for inum of `JansGrp`
Expand All @@ -49,7 +59,7 @@ Say we want to increase the size of `mail` field to 144. Do the following:<br>
In this example we are going to update one user's email address.

* Search for existing email address: `use jansdb; select * from jansPerson where uid='testUser'\G;`
* Modify it: `use jansdb; update jansPerson set mail='newEmail@gluu.org' where uid='testUser';`
* Modify it: `use jansdb; update jansPerson set mail='newEmail@gluu.org', jansVersion=COALESCE(jansVersion, 0) + 1 where uid='testUser';`
### **Search user** :

* `use jansdb; select * from jansPerson where uid='admin'\G;`
Expand Down
13 changes: 13 additions & 0 deletions docs/janssen-server/reference/database/pgsql-ops.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,19 @@ ALTER TABLE "jansPerson"
ADD COLUMN membership_level VARCHAR DEFAULT 'Basic';
```

## Add user version column on upgrade

User updates are versioned through the `jansVersion` column of `jansPerson`. Container and Kubernetes
deployments add it automatically through the persistence loader. On a VM install, add it before
upgrading the Janssen services:

```
ALTER TABLE "jansPerson" ADD COLUMN "jansVersion" BIGINT;
```

Existing rows keep a `NULL` version until their next update. Manual `UPDATE` statements on `jansPerson`
should also set `"jansVersion" = COALESCE("jansVersion", 0) + 1`, so concurrent versioned writes notice the change.

## Output column data into txt

If you want to output the data from a PostgreSQL table's column into a text file, you can use the `COPY` command. This command allows you to copy the contents of a table or query result into an external file. Here's how you can do it:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,16 @@
from io.jans.util import StringHelper
from io.jans.model import GluuStatus
from io.jans.orm.exception import AuthenticationException
from io.jans.orm.exception import VersionMismatchException
from io.jans.orm.exception import UnsupportedOperationException as OrmUnsupportedOperationException
from jakarta.faces.application import FacesMessage
from io.jans.jsf2.message import FacesMessages
from io.jans.orm import PersistenceEntryManager
from java.util import Date

# Written to the invalid-login count attribute by lockUser: only inactive users carrying it are unlocked
# Written to the invalid-login count attribute by registerFailedLogin: only inactive users carrying it are unlocked
LOCK_MARKER_PREFIX = "locked:"
UPDATE_ATTEMPTS = 5

class PersonAuthentication(PersonAuthenticationType):
def __init__(self, currentTimeMillis):
Expand Down Expand Up @@ -114,28 +117,22 @@ def authenticate(self, configurationAttributes, requestParameters, step):
return False

logged_in = authenticationService.authenticate(user_name, user_password)
if not logged_in:
self.setInvalidLoginCount(user_name, StringHelper.toString(1))
if self.maximumInvalidLoginAttemps == 1:
self.lockUser(user_name)
return logged_in
if logged_in:
return True

countInvalidLogin = StringHelper.toInteger(countInvalidLoginArributeValue, 0)

if countInvalidLogin < self.maximumInvalidLoginAttemps:
countInvalidLogin = countInvalidLogin + 1
remainingAttempts = self.maximumInvalidLoginAttemps - countInvalidLogin

print "Remaining login count attempts '%s' for user '%s'" % ( remainingAttempts, user_name )
failed = self.registerFailedLogin(user_name)
if failed is None:
return False

self.setInvalidLoginCount(user_name, StringHelper.toString(countInvalidLogin))
if remainingAttempts > 0 and userSatus == "active":
facesMessages.add(FacesMessage.SEVERITY_INFO, StringHelper.toString(remainingAttempts)+" more attempt(s) before account is LOCKED!")
remainingAttempts = self.maximumInvalidLoginAttemps - failed['count']
print "Remaining login count attempts '%s' for user '%s'" % ( remainingAttempts, user_name )
if failed['locked']:
facesMessages.add(FacesMessage.SEVERITY_ERROR, "Your account is locked. Please try again after " + StringHelper.toString(self.lockExpirationTime) + " secs")
print "Basic (lock account). Locked '%s' for '%s' seconds" % ( user_name, self.lockExpirationTime)
elif remainingAttempts > 0:
facesMessages.add(FacesMessage.SEVERITY_INFO, StringHelper.toString(remainingAttempts)+" more attempt(s) before account is LOCKED!")

if (countInvalidLogin >= self.maximumInvalidLoginAttemps) and ((userSatus is None) or (userSatus == "active")):
print "Basic (lock account). Locking '%s' for '%s' seconds" % ( user_name, self.lockExpirationTime)
self.lockUser(user_name)
return False
return False

return logged_in
else:
Expand Down Expand Up @@ -194,30 +191,92 @@ def getUserAttributeValue(self, user_name, attribute_name):

return attribute_value

def updateUser(self, user_name, change, allow_merge=True):
# Compare-and-set on jansVersion: if another writer (lock, unlock, counter, admin) changed the
# user since the read, re-read and let change() decide again on the current state
userService = CdiUtil.bean(UserService)
entryManager = CdiUtil.bean(PersistenceEntryManager)
for _ in range(UPDATE_ATTEMPTS):
user = userService.getUser(user_name)
if user is None or not change(user):
return None
try:
entryManager.updateWithVersion(user)
return user
except VersionMismatchException:
print "Basic (lock account). User '%s' changed concurrently, retrying" % user_name
except OrmUnsupportedOperationException:
if not allow_merge:
print "Basic (lock account). Backend has no versioned update, user '%s' not updated" % user_name
return None
print "Basic (lock account). Backend has no versioned update, user '%s' updated without it" % user_name
entryManager.merge(user)
return user

print "Basic (lock account). User '%s' kept changing, update skipped" % user_name
return None

def isLocked(self, user):
current = CdiUtil.bean(UserService).getCustomAttribute(user, self.invalidLoginCountAttribute)
return user.getStatus() == GluuStatus.INACTIVE and current is not None and self.getLockTime(current.getValue()) is not None

def setInvalidLoginCount(self, user_name, count):
if StringHelper.isEmpty(user_name):
return None

userService = CdiUtil.bean(UserService)
def change(user):
if self.isLocked(user):
print "Basic (lock account). Set invalid login count. User '%s' is locked, count not updated" % user_name
return False
CdiUtil.bean(UserService).setCustomAttribute(user, self.invalidLoginCountAttribute, count)
user.setUpdatedAt(Date())
return True

find_user_by_uid = userService.getUser(user_name)
if find_user_by_uid is None:
return None
updated_user = self.updateUser(user_name, change)
if updated_user is not None:
print "Basic (lock account). Set invalid login count. User '%s' count is '%s'" % (user_name, count)

# A concurrent request may have locked the user since the caller read it: keep that lock's marker
current = userService.getCustomAttribute(find_user_by_uid, self.invalidLoginCountAttribute)
if find_user_by_uid.getStatus() == GluuStatus.INACTIVE and current is not None and self.getLockTime(current.getValue()) is not None:
print "Basic (lock account). Set invalid login count. User '%s' is locked, count not updated" % user_name
return updated_user

def registerFailedLogin(self, user_name):
# Count and lock in one write: the threshold is checked on the same state the lock replaces
if StringHelper.isEmpty(user_name):
return None

userService.setCustomAttribute(find_user_by_uid, self.invalidLoginCountAttribute, count)
updated_user = userService.updateUser(find_user_by_uid)
result = {}

print "Basic (lock account). Set invalid login count. User '%s' count is '%s'" % (user_name, count)
def change(user):
result.clear()
if self.isLocked(user):
return False
userService = CdiUtil.bean(UserService)
current = userService.getCustomAttribute(user, self.invalidLoginCountAttribute)
stored = StringHelper.toInteger(None if current is None else current.getValue(), 0)
count = stored + 1 if stored < self.maximumInvalidLoginAttemps else stored
lock = count >= self.maximumInvalidLoginAttemps and user.getStatus() != GluuStatus.INACTIVE
result['count'] = count
result['locked'] = lock
if count == stored and not lock:
return False

return updated_user
result['write'] = True
now = Date()
user.setUpdatedAt(now)
if lock:
# The marker carries the version this write stores, so unlock can tell whether anyone wrote after it
lock_version = (0 if user.getVersion() is None else user.getVersion()) + 1
user.setStatus(GluuStatus.INACTIVE)
userService.setCustomAttribute(user, self.invalidLoginCountAttribute,
"%s%s:%s" % (LOCK_MARKER_PREFIX, now.getTime(), lock_version))
else:
userService.setCustomAttribute(user, self.invalidLoginCountAttribute, StringHelper.toString(count))
return True

# Marker is locked:<lock time>:<updatedAt as stored by the lock write>, both epoch millis
if self.updateUser(user_name, change) is None and result.get('write'):
return None
return result or None

# Marker format: locked:<epoch millis>:<jansVersion written by the lock>
def parseLockMarker(self, count_attribute_value):
if count_attribute_value is None or not count_attribute_value.startswith(LOCK_MARKER_PREFIX):
return None
Expand All @@ -231,73 +290,35 @@ def getLockTime(self, count_attribute_value):
marker = self.parseLockMarker(count_attribute_value)
return None if marker is None else marker[0]

def lockMarker(self, locked_at, updated_at):
return "%s%d:%d" % (LOCK_MARKER_PREFIX, locked_at.getTime(), updated_at.getTime())

def lockUser(self, user_name):
if StringHelper.isEmpty(user_name):
return None

userService = CdiUtil.bean(UserService)
facesMessages = CdiUtil.bean(FacesMessages)
facesMessages.setKeepMessages()

find_user_by_uid = userService.getUser(user_name)
if (find_user_by_uid is None):
return None

if find_user_by_uid.getStatus() == GluuStatus.INACTIVE:
print "Basic (lock account). Lock user. User '%s' locked already" % user_name
return

# Status and marker go in one write, so a lock never exists without its marker. merge, not
# updateUser: it would overwrite the updatedAt the marker records
entryManager = CdiUtil.bean(PersistenceEntryManager)
locked_at = Date()
find_user_by_uid.setStatus(GluuStatus.INACTIVE)
find_user_by_uid.setUpdatedAt(locked_at)
userService.setCustomAttribute(find_user_by_uid, self.invalidLoginCountAttribute, self.lockMarker(locked_at, locked_at))
entryManager.merge(find_user_by_uid)

# The backend may store updatedAt rounded or shifted: record it as read back. updatedAt is
# unchanged on the read-back object, so this write keeps it
stored = userService.getUser(user_name)
stored_at = None if stored is None else stored.getUpdatedAt()
if stored_at is not None and stored_at.getTime() != locked_at.getTime():
userService.setCustomAttribute(stored, self.invalidLoginCountAttribute, self.lockMarker(locked_at, stored_at))
entryManager.merge(stored)
facesMessages.add(FacesMessage.SEVERITY_ERROR, "Your account is locked. Please try again after " + StringHelper.toString(self.lockExpirationTime) + " secs")

print "Basic (lock account). Lock user. User '%s' locked" % user_name

def unLockUser(self, user_name, expected_marker):
if StringHelper.isEmpty(user_name):
return False

userService = CdiUtil.bean(UserService)

find_user_by_uid = userService.getUser(user_name)
if (find_user_by_uid is None):
marker = self.parseLockMarker(expected_marker)
if marker is None:
return False
lock_version = marker[1]

# Re-read right before the write: skip if another request already unlocked or re-locked the user
current = userService.getCustomAttribute(find_user_by_uid, self.invalidLoginCountAttribute)
current_marker = None if current is None else current.getValue()
if find_user_by_uid.getStatus() != GluuStatus.INACTIVE or current_marker != expected_marker:
print "Basic (lock account). Unlock user. Lock of user '%s' changed, not unlocking" % user_name
return False
def change(user):
current = CdiUtil.bean(UserService).getCustomAttribute(user, self.invalidLoginCountAttribute)
current_marker = None if current is None else current.getValue()
if user.getStatus() != GluuStatus.INACTIVE or current_marker != expected_marker:
print "Basic (lock account). Unlock user. Lock of user '%s' changed, not unlocking" % user_name
return False

# The marker records updatedAt as the lock stored it; every UserService.updateUser (config-api,
# SCIM, admin UI) stamps a new one, so any other value means the user was changed while locked
updated_at = find_user_by_uid.getUpdatedAt()
expected_updated_at = self.parseLockMarker(expected_marker)[1]
if updated_at is None or updated_at.getTime() != expected_updated_at:
print "Basic (lock account). Unlock user. User '%s' was modified after the lock (updatedAt '%s', lock wrote '%s'), not unlocking" % (user_name, None if updated_at is None else updated_at.getTime(), expected_updated_at)
return False
# Every versioned user write (config-api, SCIM, admin UI) bumps jansVersion past the lock's
if user.getVersion() != lock_version:
print "Basic (lock account). Unlock user. User '%s' was modified after the lock, not unlocking" % user_name
return False

find_user_by_uid.setStatus(GluuStatus.ACTIVE)
userService.setCustomAttribute(find_user_by_uid, self.invalidLoginCountAttribute, StringHelper.toString(0))
userService.updateUser(find_user_by_uid)
user.setStatus(GluuStatus.ACTIVE)
user.setUpdatedAt(Date())
CdiUtil.bean(UserService).setCustomAttribute(user, self.invalidLoginCountAttribute, StringHelper.toString(0))
return True

# Never unlock through an unconditional write: it could undo an admin disable racing it
if self.updateUser(user_name, change, allow_merge=False) is None:
return False

print "Basic (lock account). Unlock user. User '%s' unlocked" % user_name
return True
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,24 @@ This module has 2 properties:
3) lock_expiration_time - Specify the time in seconds when lock will be expired
Default value: 180

While an account is locked, `invalid_login_count_attribute` holds `locked:<lock time>:<updatedAt>` (epoch millis) instead of a count.
The script only unlocks inactive accounts carrying this marker that were not modified after the lock, so accounts
disabled by an administrator stay disabled, even if the administrator acted while the account was locked.
While an account is locked, `invalid_login_count_attribute` holds `locked:<epoch millis>:<jansVersion>` instead of a
count, where `jansVersion` is the user version the lock wrote. The script only unlocks inactive accounts whose marker
and version are unchanged since the lock, so accounts disabled or edited by an administrator stay locked.

On backends with versioned updates, the script's user writes are compare-and-set on `jansVersion`: a counter, lock
or unlock write that races a write which advances `jansVersion` re-reads the user and decides again instead of
overwriting it. Janssen's own user writers (auth server, Config API, SCIM, Casa, Jans Link) all advance `jansVersion`.
Custom entity classes or direct database updates on `jansPerson` must advance it too, or the script and unlock cannot
see their changes.

Config API user updates (PUT and PATCH) save conditionally on the version they read, and on a conflict re-read the
user and reapply the request, so a PATCH read before a lock keeps the account locked. Other writers that update users
with plain `merge` (for example SCIM) check only the version `merge` reads itself, not the one their own earlier read
saw. An update read before a lock and saved after it can therefore write the status it read and reactivate the account
early.

Counter and lock writes fall back to a plain update on backends without versioned updates; unlock does not, so such
accounts must be reactivated by an administrator.

Upgrade note: accounts locked by a previous version of this script have no marker and are not unlocked when their
lock expires. An administrator must reactivate them.
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,14 @@

import org.json.JSONArray;

import com.fasterxml.jackson.annotation.JsonIgnore;

import io.jans.as.model.exception.InvalidClaimException;
import io.jans.model.user.SimpleUser;
import io.jans.orm.annotation.AttributeName;
import io.jans.orm.annotation.DataEntry;
import io.jans.orm.annotation.ObjectClass;
import io.jans.orm.annotation.Version;

/**
* @author Yuriy Movchan Date: 06/11/2013
Expand All @@ -24,6 +28,30 @@ public class User extends SimpleUser {

private static final long serialVersionUID = 6634191420188575733L;

@JsonIgnore
@Version
@AttributeName(name = "jansVersion", ignoreDuringUpdate = true)
private Long version;

public Long getVersion() {
return version;
}

public void setVersion(Long version) {
this.version = version;
}

// version is concurrency metadata, not identity: keep the inherited equality
@Override
public boolean equals(Object obj) {
return super.equals(obj);
}

@Override
public int hashCode() {
return super.hashCode();
}

public Object getAttribute(String attributeName, boolean optional, boolean multivalued) throws InvalidClaimException {
Object attribute = null;

Expand Down
Loading
Loading