lmxopcua/gr_security.md

# Galaxy Repository — Security, Users, Roles & Permissions

## Overview

The Galaxy Repository uses a role-based access control (RBAC) system with three layers:
1. **Users** — individual accounts in `user_profile`
2. **Roles** — assigned to users, control what operations they can perform
3. **Security Groups** — assigned to objects/packages, control which users can see/modify them
4. **Security Classification** — per-attribute write protection levels (0-6)

## 1. Users (`user_profile` table)

| Column | Type | Description |
|---|---|---|
| `user_profile_id` | int | Primary key |
| `user_profile_name` | nvarchar | Username (e.g., SystemEngineer, Administrator) |
| `user_guid` | uniqueidentifier | Unique identifier for check-out tracking |
| `password_hash` | int | Legacy password hash |
| `crypto_secure_hashed_pwd` | ntext | Encrypted password |
| `default_security_group` | nvarchar | Default security group for new objects |
| `roles` | ntext | Serialized role assignments (binary) |
| `intouch_access_level` | int | InTouch HMI access level |
| `user_full_name` | nvarchar | Display name |
| `default_platform_tag_name` | nvarchar | Default platform for deployments |
| `default_app_engine_tag_name` | nvarchar | Default engine for new objects |
| `default_history_engine_tag_name` | nvarchar | Default historian engine |
| `default_area_tag_name` | nvarchar | Default area for new objects |

### Current Users

| ID | Name | Security Group | Roles | Notes |
|---|---|---|---|---|
| 1 | SystemEngineer | Default | (none) | Built-in engineering account |
| 2 | Administrator | Default | Administrator | Has password, admin role |
| 3 | DefaultUser | Default | (assigned) | Default runtime user |

### User Preferences (`user_preferences` table)

Stores per-user UI preferences as binary blobs, keyed by `user_profile_id` and `preference_type` (GUID).

## 2. Roles & Permissions

Roles are managed through Galaxy runtime attributes, not SQL tables. The Galaxy platform object exposes:

### Role Management Attributes

| Attribute | Description |
|---|---|
| `RoleList` | Array of defined role names |
| `AddRole` | Command: create a new role |
| `DeleteRole` | Command: remove a role |
| `CurrentRole` | The active role for the current session |
| `RolePermission` | Array of permission flags per role |
| `TogglePermission` | Command: toggle a permission flag |

### User-Role Assignment Attributes

| Attribute | Description |
|---|---|
| `SetUserRole` | Command: assign a role to a user |
| `DelUserRole` | Command: remove a role from a user |
| `ListUserRole` | Command: list roles for a user |

### Operation Permissions

| Attribute | Description |
|---|---|
| `OpPermission` | Operation permission list |
| `OpPermissionSGList` | Operation permissions per security group |
| `ToggleOpPermission` | Command: toggle operation permission |

## 3. Security Groups

Security groups control which users can access which objects. Each `package` (object version) belongs to a security group.

### `package.security_group` column

- Type: nvarchar
- Default: `"Default"`
- All packages in the current Galaxy use the `"Default"` security group

### Key Stored Procedures

| Procedure | Description |
|---|---|
| `list_object_by_security_group` | Lists all objects in a given security group |
| `internal_change_objects_security_group` | Bulk-changes security groups for objects |
| `is_package_visible_to_user` | Checks if a user can see a specific package version |

### Visibility Rules

- Objects checked out by a user are only visible to that user (exclusive edit)
- `gobject.checked_out_by_user_guid` tracks who has the object checked out
- `is_package_visible_to_user` determines which package version (checked-in vs checked-out) a user sees

## 4. Security Classification (Attribute-Level)

Each attribute has a `security_classification` value controlling write access:

| Value | Level | OPC UA Access | Description |
|---|---|---|---|
| 0 | FreeAccess | ReadWrite | No restrictions |
| 1 | Operate | ReadWrite | Normal operating level (default) |
| 2 | SecuredWrite | ReadOnly | Elevated write access required |
| 3 | VerifiedWrite | ReadOnly | Verified/confirmed write required |
| 4 | Tune | ReadWrite | Tuning-level access |
| 5 | Configure | ReadWrite | Configuration-level access |
| 6 | ViewOnly | ReadOnly | Read-only, no writes |

### Distribution in Database

| Classification | Count | Example Attributes |
|---|---|---|
| -1 | 15,905 | Most system attributes (no restriction) |
| 0 | 2,194 | Basic attributes |
| 1 | 1,420 | Description fields, standard attributes |
| 4 | 1,392 | Tune-level (e.g., `_ChangePassword`) |
| 5 | 969 | Configure-level attributes |
| 6 | 2,250 | ViewOnly (e.g., `_ExternalName`) |

### Lock Types (`dynamic_attribute.lock_type`)

| Value | Description |
|---|---|
| 0 | Standard (unlocked) |
| Other | Locked by template or system |

## 5. Authentication

The Galaxy supports multiple authentication modes, configured via the `AuthenticationMode` attribute on the platform:

| Mode | Description |
|---|---|
| Galaxy Only | Users authenticate against Galaxy's internal user_profile table |
| OS Group Only | Users authenticate via Windows domain groups |
| Windows Integrated Security | Users authenticate via Windows credentials (SSO) |

### Related Attributes

| Attribute | Description |
|---|---|
| `AuthenticationMode` | Active authentication method |
| `SecurityEnabled` | Boolean: whether security enforcement is active |
| `_SecuritySchema` | XML security schema definition (binary) |
| `_MasterSecuritySchema` | Master security schema (binary) |

## 6. Check-Out/Check-In Security

Galaxy objects use an exclusive check-out model for editing:

| `gobject` Column | Description |
|---|---|
| `checked_out_by_user_guid` | GUID of user who has the object checked out |
| `checked_out_package_id` | Package version created for the check-out |
| `checked_in_package_id` | Last checked-in package version |

Only the user who checked out an object can modify it. Other users see the last checked-in version.

## 7. Protected Objects

The `gobject_protected` table lists objects that cannot be modified:
- Contains only `gobject_id` column
- Protects system-critical objects from accidental changes

## 8. Operation/Workflow Groups

| Table | Description |
|---|---|
| `ow_group_def` | Operation/workflow group definitions |
| `ow_group_id` | Group ID tracking |
| `ow_group_override` | Group overrides with `property_bitmask` |

## Summary

The Galaxy security model operates at four levels:

```
Authentication (Galaxy/OS/Windows)
  └─ Users (user_profile)
       └─ Roles (RoleList, RolePermission)
            └─ Security Groups (package.security_group)
                 └─ Attribute Security Classification (0-6)
```

- **Authentication** determines who can connect
- **Roles** determine what operations a user can perform
- **Security Groups** determine which objects a user can access
- **Security Classification** determines per-attribute write permissions

For the OPC UA server, the most relevant layer is **Security Classification** (already implemented — maps to OPC UA AccessLevel). The server currently uses anonymous access and does not enforce user/role/security-group checks.