# Permission Management

UDiTH Portal uses a role-based and folder-based permission system. Users are managed through Keycloak and synchronised into Portal. Access to models and content is controlled by assigning groups to folders with specific permission levels.

## Roles

Roles are defined in Keycloak and synchronised to Portal. Each user can have one or more of the following roles:

| Role | Description |
|------|-------------|
| **Admin** | Full access to all features, folders, and models. Can manage users, groups, permissions, and system settings. Admins bypass all folder-level permission checks. |
| **Browser Maintainer** | Can create, edit, and delete models and model versions. Required for model management operations. |
| **Group Maintainer** | Can manage group memberships and assignments. |

Users without any of these roles are regular users. They can view and interact with models based on the folder permissions assigned to their groups.

## Groups (Organisations)

Groups are the primary unit for assigning permissions. Users are assigned to one or more groups, and permissions are granted to groups on a per-folder basis.

Groups can be managed in two ways:

- **Manually** through the Portal administration interface at **Administration → Groups**.
- **Automatically** through federated identity providers (e.g. Azure AD). See the [federated accounts guide](/UDiTH%20Portal/Using%20federated%20accounts) for details on group synchronisation.

Groups can be organised in a tree structure, allowing hierarchical organisation management.

> ⚠️ **Important:** Group assignments are inherited **upwards**. If a user is assigned to a child group, they are also considered a member of all parent groups in the hierarchy. Keep this in mind when structuring your group tree and assigning folder permissions.

## Folder-Based Permissions

Access to models is controlled through **folders**. Each model is placed in a folder, and permissions are assigned to groups at the folder level.

### Permission Levels

| Name | Description |
|------|-------------|
| **Denied** | No access. The folder and its contents are not visible. |
| **Full Read** | Full access to the folder and its contents. |

### How Permissions Are Resolved

1. **Admins** always have full access to all folders and models.
2. For other users, Portal checks which groups the user belongs to and whether any of those groups have **Full Read** permission on the relevant folder.
3. Permissions are inherited along the folder hierarchy. A permission set on a parent folder applies to all child folders unless overridden.

### Assigning Permissions

Permissions are managed in the Portal administration interface:

1. Navigate to **Administration → Folders**.
2. Select the folder for which you want to manage permissions.
3. Assign a group and select the desired permission level.

## Model Access

Model access is derived from the folder in which the model is placed:

- A user can **view** a model if they have at least **Read** permission on the model's folder.
- A user can **modify or delete** a model if they have the **Browser Maintainer** role.
- **Model import** is restricted to users with the **Admin** role.

## Testing Permissions

Portal provides an **Open Access test page** under **Administration → Access** that allows administrators to verify the effective permissions for each user. Use this page to confirm that folder and model access is configured as expected before rolling out changes.

## User Management

Users are managed through Keycloak and synchronised to Portal. The synchronisation happens automatically when users sign in, or it can be triggered manually through the administration interface using **Force Synchronize**.

In the Portal administration interface at **Administration → Users**, administrators can:

- Create new users.
- Reset user passwords.
- View all synchronised users.
- Assign or remove roles.
- Assign users to groups.
- Delete users from Portal.

> **Note:** Users can also be created and managed directly in Keycloak. Changes are synchronised to Portal when users sign in or when **Force Synchronize** is triggered.