# 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, separately for each way a model can be opened.

## 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 Types

A permission is not a single access level. It is granted separately for each way a model can be opened, so a group can be allowed to view a model in the browser without being allowed to download it, and vice versa.

| Name | Grants |
|------|--------|
| **Streaming** | Opening the model in the locally installed UDiTH application. The model data is streamed from Portal and is not stored on the client. |
| **Cache** | Caching the model locally in UDiTH, so it can be opened again without a connection to Portal. |
| **BrowserBasedViewing** | Opening the model in the browser. Requires a render server and a browser-based-viewing licence. |
| **Visibility** | Not granted directly. A folder and the models in it become visible as soon as a group holds at least one of the permissions above. |

The permission types are independent. Granting **Cache** without **Streaming** is a valid configuration, and each type can be granted to a different set of groups.


### How Permissions Are Resolved

1. **Admins** always have full access to all folders and models.
2. For other users, Portal determines which groups the user belongs to and, for the permission type the requested action needs, whether any of those groups holds that permission on the folder.
3. Each permission type is resolved on its own. A user who only holds **BrowserBasedViewing** on a folder sees its models and can open them in the browser, but cannot open or cache them locally.
4. 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 → Access**.
2. Select the folder for which you want to manage permissions in the folder tree.
3. Add a permission for a group and select which of the permission types it should hold.

The folder tree shows the permission types currently assigned per folder and group, so an existing configuration can be reviewed without opening each entry.

> **Upgrading from a release before 2026.4.0:** permissions used to be a single access level. During the update, every group that had access to a folder receives **Streaming**, **Cache** and **BrowserBasedViewing** on that folder, so nobody loses access. Review the result here if a more restrictive setup is wanted. See [Breaking Changes](/UDiTH%20Portal/Breaking%20Changes).

## Model Access

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

- A user can **see** a model if they hold any permission on the model's folder.
- Which options are offered for opening the model depends on the permission types the user holds: **BrowserBasedViewing** for opening it in the browser, **Streaming** for opening it in the local UDiTH application, **Cache** for downloading it for offline use.
- 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.