Version: 2.4

Users

Users are individual entries in tSM that represent people or system/service accounts. They are the foundation of the application and are used for:

Task assignments — assigning work to individuals
Reporting and auditing — tracking who did what and when
Access control — determining permissions via roles and privileges
Collaboration — comments, attachments, notifications

1. User Creation and Synchronization

tSM supports multiple methods for creating and managing users:

1.1 Manual Creation (Internal Database)

You can create and manage users directly via the tSM interface or API. This is useful for:

Smaller setups without external identity providers
"Technical" or "API" service accounts
Testing and development environments

Steps:

Navigate to User Management module
Click "Add User"
Fill in required fields (username, email, name)
Set authentication method (password, SSO, LDAP)
Assign roles and groups
Save

1.2 Synchronization with External Directories

Typically, users are synced from an LDAP/AD or other directory services on a scheduled job.

Synchronization behavior:

New users found in the directory are automatically created in tSM
Authentication method is set to "LDAP" or "AD"
User attributes (name, email, groups) are updated on each sync
Users no longer in the external directory can be automatically deactivated (configurable)

Configuration:

tsm:
  ldap:
    enabled: true
    url: "ldap://your-ldap-server:389"
    baseDn: "dc=example,dc=com"
    userSearchBase: "ou=users"
    userSearchFilter: "(objectClass=person)"
    groupSearchBase: "ou=groups"
    syncSchedule: "0 0 2 * * ?" # Daily at 2 AM
    autoDeactivate: true

2. Authentication Methods

tSM supports multiple authentication methods that can be configured per user or globally.

Supported Protocols:

SAML 2.0
OAuth2 / OpenID Connect (OIDC)
Custom SSO solutions (via adapter)

Users authenticate against an LDAP or Active Directory server using their domain credentials.

Authentication Flow:

User enters username and password
tSM attempts to bind to LDAP with provided credentials
If successful, user is authenticated
User attributes are updated from LDAP
Session is created

2.3 Internal Passwords

A purely local authentication method where passwords are stored (hashed) in the tSM database.

Use Cases:

Small deployments without external identity providers
Technical/API accounts
Emergency access accounts
Development and testing

Password Policy Configuration:

Configured in tsm-user-management under the security.password-policy prefix (note: no tsm. prefix). The values below are the shipped defaults:

security:
  password-policy:
    # Minimum and maximum password length
    min-length: 8
    max-length: 64
    # List of disallowed weak passwords (lowercased for matching)
    weak-passwords:
      - "1234"
      - "12345"
      - "123456"
      - "password"
      - "qwerty"
      - "admin"
      - "111111"
    # Password composition requirements (set to false to disable specific checks)
    require-uppercase: true       # true → at least one uppercase letter required
    require-lowercase: true       # true → at least one lowercase letter required
    require-digit: true           # true → at least one digit required
    require-special-char: true    # true → at least one special character required
    disallow-whitespace: true     # true → whitespace is not allowed in passwords

The policy covers composition and length only. tSM has no built-in password expiration or password-history enforcement, so there are no expirationDays / historyCount equivalents.

3. API Authentication

For API (machine-to-machine) scenarios, service accounts can authenticate using:

3.1 Basic Authentication

Username and password encoded in the Authorization header.

Example:

curl -X 'GET' \
  'https://your-tsm.com/api/tsm-user-management/api/v1/users' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='

// JavaScript example
const username = 'api-user';
const password = 'api-password';
const credentials = btoa(`${username}:${password}`);

fetch('https://your-tsm.com/api/tsm-user-management/api/v1/users', {
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Accept': 'application/json'
  }
});

3.2 Bearer Token Authentication

Using JWT tokens from SSO or IAM systems.

3.3 API Key Authentication

API Keys provide long-lived, revocable credentials for machine-to-machine integrations without the need to manage token refresh flows.

Creating an API Key:

Navigate to User Management → Users
Select the user (typically a service account)
Open the API Keys tab
Click Generate API Key
Set a description and optional expiration date
Copy the generated key — it is shown only once

API Endpoint:

POST /api/token
Content-Type: application/json

{
  "grant_type": "api_key",
  "client_id": "tsm-microservice",
  "api_key": "tsm_ak_7f3a92c1e8b04d5f..."
}

Response:

{
  "access_token": "eyJhbGc...",
  "expires_in": 3600,
  "claims": ["Um.User.View", "Um.User.Edit"]
}

Using the API Key directly in a request header:

curl -X 'GET' \
  'https://your-tsm.com/api/tsm-ticket/api/v1/tickets' \
  -H 'accept: application/json' \
  -H 'X-API-Key: tsm_ak_7f3a92c1e8b04d5f...'

Key Properties:

Bound to a specific user — inherits that user's roles and privileges
Can have an optional expiration date
Can be revoked at any time without affecting the user account
Multiple API keys can be created per user
All API activity is logged and auditable under the associated user

Security: Treat API keys like passwords. Store them in a secrets manager (e.g., HashiCorp Vault, AWS Secrets Manager) and never commit them to source control.

4. User Attributes

Core Attributes

Field	Type	Required	Read-only	Description
`id`	UUID	–	–	Unique identifier / primary key in UUID format (auto-generated or UUIDv4). Not displayed to end users.
`code`	String	Yes	–	User unique identifier / business key in readable format.
`type`	Enum	Yes	–	Type of user resource. Values: `INDIVIDUAL`, `WORK_GROUP`, `ORGANIZATION`, `EXTERNAL`.
`givenName`	String	–	–	User's given (first) name.
`familyName`	String	–	–	User's family (last) name.
`name`	String	Yes	–	Full name. Defaults to "$givenName $familyName". Required for WORK_GROUP and ORGANIZATION types.
`email`	String	–	–	User's email address.
`phoneNumber`	String	–	–	User's phone number.
`webSite`	String	–	–	URL of the user's web page or blog.
`status`	Enum	Yes	–	User status. Values: `ENABLE` (default), `DISABLE`.
`authentication`	Enum	–	–	Authentication method. Values: `LDAP`, `PKI`, `AD`, `PASSWORD` (default), `NIA`, `EMPTY`.
`description`	String	–	–	User description.

Organizational Attributes

Field	Type	Required	Read-only	Description
`supervisorId`	UUID	–	–	Supervisor or manager of the user (UUID reference).
`groups`	List<String>	–	Yes	User groups assigned to the user. Populated from `umt_user_user_group` table.
`roles`	List<String>	–	Yes	User roles assigned to the user. Populated from `umt_user_role` table.
`regions`	List<UserRegion>	–	–	Regional assignments with coefficients and validity periods.
`modulesIds`	List<UUID>	–	–	Module IDs assigned to the user.

The supervisorId relationship also provides automatic calendar access: a user's calendars are included in their direct supervisor's viewing and write selections. This rule covers one level of direct reports and does not recursively include indirect reports. Other privileges and calendar settings can still limit individual actions. See Automatic calendar access.

Configuration Attributes

Field	Type	Description
`dataTags`	List<String>	Additional data tags (aka labels) for categorization.
`chars`	TsmChars	Custom characteristics/attributes map.
`notificationConfig`	UserNotificationConfig	Notification configuration (templates, user groups, preferences).

System/Audit Fields

Field	Type	Read-only	Description
`validFrom`	Date	–	User valid date from (format: yyyy-MM-dd). Default: current date.
`validTo`	Date	–	User valid date to (format: yyyy-MM-dd).
`auditInfo`	AuditInfo	Yes	Standard audit fields (createdBy, createdAt, updatedBy, updatedAt).

Enum Values

Type

INDIVIDUAL — Individual person
WORK_GROUP — Work group or team
ORGANIZATION — Organization
EXTERNAL — External user

Status

ENABLE — User is active and can log in
DISABLE — User is disabled and cannot log in

Authentication

LDAP — LDAP authentication
PKI — PKI/certificate authentication
AD — Active Directory authentication
PASSWORD — Internal password authentication (default)
NIA — National Identity Authority authentication
EMPTY — No authentication method

Nested Objects

UserRegion

Field	Type	Required	Description
`regionId`	UUID	Yes	Region ID from Address Management.
`coefficient`	Integer	–	Region coefficient.
`validFrom`	Date	–	Regional assignment valid from.
`validTo`	Date	–	Regional assignment valid to.

UserNotificationConfig

Field	Type	Description
`ignoredTemplateCodes`	List<String>	Template codes to ignore for notifications.
`ignoredUserGroups`	List<String>	User groups to ignore for notifications.
`user`	UserNotificationConfigModel	User-specific notification settings.
`userGroups`	List<UserGroupNotificationConfigModel>	Group-specific notification settings.

UserPhoto

Field	Type	Required	Description
`userId`	UUID	Yes	The user ID.
`photoData`	String	–	Base64-encoded photo image.

5. User States and Lifecycle

User States

ENABLE — User is active and can log in (default state)
DISABLE — User is disabled and cannot log in, but data is preserved

Users can also be in validity-based states:

Valid — Current date is within validFrom and validTo period
Invalid — Current date is outside the validity period

State Transitions

User Type Transitions

User types define the nature of the user entity:

INDIVIDUAL — Single person user
WORK_GROUP — Team or group of users
ORGANIZATION — Organization entity
EXTERNAL — External user (partner, customer)

Note: User type should be set at creation and typically doesn't change.

6. User Groups

Users can belong to multiple groups for organizational and access control purposes.

Group Types:

Functional Teams — Based on job function (e.g., Helpdesk, Engineering)
Organizational Units — Based on company structure (e.g., departments, regions)
Security Groups — For access control purposes
Dynamic Groups — Membership based on user attributes or rules

Assignment:

Manual assignment via UI or API
Automatic assignment via LDAP/AD group sync
Rule-based assignment via expressions

Read-only Fields: The groups and roles fields in the User entity are read-only and are populated from:

groups — Populated from umt_user_user_group table
roles — Populated from umt_user_role table

For more details on group management, see User Groups documentation.

7. Best Practices

Recommendation	Description
Use external identity providers	Leverage SSO or LDAP for centralized user management
Implement least privilege	Grant only necessary roles to each user
Regular sync schedule	Keep user data in sync with authoritative sources
Service accounts	Use dedicated accounts for API access, not personal users
Password policies	Enforce strong passwords for internal authentication
Audit logging	Monitor user creation, role changes, and access patterns via SIEM
Deactivate unused accounts	Regularly review and disable inactive users

1. User Creation and Synchronization​

1.1 Manual Creation (Internal Database)​

1.2 Synchronization with External Directories​

2. Authentication Methods​

2.1 SSO / Federated Login​

2.2 LDAP/AD-based Login​

2.3 Internal Passwords​

3. API Authentication​

3.1 Basic Authentication​

3.2 Bearer Token Authentication​

3.3 API Key Authentication​

4. User Attributes​

Core Attributes​

Organizational Attributes​

Configuration Attributes​

System/Audit Fields​

Enum Values​

Type​

Status​

Authentication​

Nested Objects​

UserRegion​

UserNotificationConfig​

UserPhoto​

5. User States and Lifecycle​

User States​

State Transitions​

User Type Transitions​

6. User Groups​

7. Best Practices​