> For the complete documentation index, see [llms.txt](https://au-dohp.gitbook.io/au-dohp-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://au-dohp.gitbook.io/au-dohp-docs/au-dohp-user-manual/access-management.md).

# Access Management

This section outlines the Identity Access Management (IAM) framework for AU-DOHP, ensuring secure, scalable, and controlled access to resources. The IAM system leverages **Keycloak** for authentication and authorization, utilizing users, groups, subgroups, and roles to manage access effectively.

***

#### **1. IAM Components**

IAM in AU-DOHP is built around three core components:

* **Users**: Individual accounts representing people accessing the platform.
* **Groups and Subgroups**:
  * **Groups**: Represent organizations or countries (e.g., "Tunisia").
  * **Subgroups**: Represent teams or institutes within an organization (e.g., "Minister of Human Health").
* **Roles**: Define permissions and access levels for users, groups, or subgroups.

***

#### **2. Roles and Permissions**

Roles in AU-DOHP are categorized into **Position-Related Roles** (organizational hierarchy) and **Resource Access-Related Roles** (specific resource permissions). Each role comes with defined permissions, as detailed below.

**2.1 Position-Related Roles**

These roles reflect a user's administrative responsibilities within the platform's hierarchy.

| **Role**                | **Description**                                 | **Permissions**                                                                                                    |
| ----------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **super\_admin**        | Manages the entire platform.                    | - Create/delete organizations\<br>- Assign organization admins\<br>- View platform insights\<br>- Add super admins |
| **organization\_admin** | Manages a specific organization.                | - Create/delete teams within the organization\<br>- Assign team admins\<br>- View organization insights            |
| **team\_admin**         | Manages a specific team within an organization. | - Manage team members\<br>- Manage team resources (e.g., data products)                                            |

**2.2 Resource Access-Related Roles**

These roles govern access to specific resources (e.g., data products) and are composite, inheriting permissions from lower-level roles. Each role is prefixed with the resource's ID (e.g., \<resource\_id>\_viewer).

| **Role**                      | **Includes**             | **Permissions**                                                                                                               |
| ----------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| **\<resource\_id>\_viewer**   | -                        | - View the resource                                                                                                           |
| **\<resource\_id>\_consumer** | Viewer                   | - View the resource\<br>- Consume the resource (e.g., use in another data product)                                            |
| **\<resource\_id>\_editor**   | Consumer, Viewer         | - View the resource\<br>- Consume the resource\<br>- Edit the resource (e.g., update metadata)                                |
| **\<resource\_id>\_owner**    | Editor, Consumer, Viewer | - View the resource\<br>- Consume the resource\<br>- Edit the resource\<br>- Delete the resource\<br>- Manage access requests |

***

#### **3. Access Types for Resources**

Resources in AU-DOHP have an **access\_type** attribute that dictates visibility and default role assignments.

| **Access Type** | **Description**                               | **Default Role Assignments**                                                                                                |
| --------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **PRIVATE**     | Visible only to the creator.                  | - Creator: \<resource\_id>\_owner                                                                                           |
| **TEAMONLY**    | Visible to all members of the creator's team. | - Team members: \<resource\_id>\_consumer\<br>- Team admin: \<resource\_id>\_owner                                          |
| **PUBLIC**      | Visible to all platform users.                | - All users: \<resource\_id>\_viewer\<br>- Team members: \<resource\_id>\_consumer\<br>- Team admin: \<resource\_id>\_owner |

***

#### **4. Permissions Matrix**

The table below summarizes permissions for resource-related actions across roles.

| **Action**             | **Owner** | **Editor** | **Consumer** | **Viewer** |
| ---------------------- | --------- | ---------- | ------------ | ---------- |
| View Resource          | ✅         | ✅          | ✅            | ✅          |
| Edit Resource          | ✅         | ✅          | ❌            | ❌          |
| Consume Resource       | ✅         | ✅          | ✅            | ❌          |
| Delete Resource        | ✅         | ❌          | ❌            | ❌          |
| Manage Access Requests | ✅         | ❌          | ❌            | ❌          |

***

#### **5. Access Requests**

Users can request access to resources they lack permissions for, following this workflow:

* **Request Submission**: A user requests access for themselves or their team via a UI (e.g., an "IT shop" for resources).
* **Approval/Denial**:
  * **Approved**: The requester's team (subgroup) is granted the \<resource\_id>\_consumer role.
  * **Denied**: No changes are made.
* **Notification**: The requester is notified of the decision via email.
* **Implementation**: Access requests are stored in a backend database, as Keycloak does not natively support this feature.

***

#### **6. Keycloak Integration**

Keycloak underpins the IAM system with the following functionalities:

* **User Management**: Create, update, and delete users.
* **Group and Subgroup Management**: Organize users into hierarchical groups (organizations) and subgroups (teams).
* **Role Assignment**: Assign roles to users or groups based on responsibilities and resource needs.
* **Permission Checks**: A middleware intercepts API requests, querying Keycloak to verify user groups, subgroups, and roles before processing.

***

#### **7. Best Practices for Endpoint Development**

To ensure secure and consistent API endpoints, adhere to these guidelines:

1. **Check Authentication**: Use get\_current\_user(request) to authenticate users and retrieve their ID, teams, and roles.
2. **Check Authorization**: Validate permissions for the requested action using role-based checks.
3. **Response Status**: Return appropriate HTTP status codes (e.g., 200 for success, 401 for unauthorized).
4. **Error Handling**: Implement try-except blocks to manage errors gracefully.

***

#### **8. Summary**

The IAM framework in AU-DOHP provides a robust, secure, and scalable access control system. By integrating Keycloak's authentication and authorization capabilities with a custom access request workflow, AU-DOHP ensures fine-grained control over resources while supporting collaboration across organizations and teams. The use of roles, groups, and access types simplifies administration and enhances user experience.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://au-dohp.gitbook.io/au-dohp-docs/au-dohp-user-manual/access-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.