transferred ADRs from 'ucsschool' repo

iam/guardian/0001-guardian-deployment.md

@@ -0,0 +1,135 @@
+# Deployment of the Guardian components
+
+---
+
+- status: accepted
+- date: 2023-07-17
+- deciders: UCS@school RAM subteam
+- consulted: PM
+- informed: UCS@school team, PM
+
+---
+
+## Context and Problem Statement
+
+The Guardian will be one of the central components of the role and rights management in UCS, and it will be deployed
+in varied environments; from single server UCS domains to distributed kubernetes deployments with the SWP project.
+
+Because of this, the composition of the components making up the Guardian should be chosen carefully.
+
+The Guardian consists of the following components:
+
+### Policy Repository
+
+This component stores any information that is related to the management of the Guardian. This includes
+roles, namespaces, conditions, mappings and custom policy code. Not included are the attributes of objects policies act
+on (actors and targets).
+
+### Management API
+
+An API for manipulating the Policy Repository. With this component namespaces, conditions, mappings, etc. can be created
+and modified.
+
+### Policy Evaluation component
+
+This component will be supplied with information from the Policy Repository and is capable of calculating the results
+of policy requests.
+
+### Authorization API
+
+This component provides an API to interact with the Policy Evaluation component and constitutes the Policy Decision Point.
+
+### Data layer
+
+This component allows the authorization API to fetch actors and targets on the clients behalf to pass their attributes
+on to the Policy Evaluation component.
+
+---
+
+The architecture of the Guardian should follow [ADR 0014](0014-component-deployments.md) and should ensure
+maximum flexibility, scalability and separation of concerns.
+
+## Decision Drivers
+
+- ease of maintenance
+- suitability for Kubernetes environments
+- scalability
+- compatibility with our UCS concepts
+- Adhering to [ADR 0014](0014-component-deployments.md)
+
+## Considered Options
+
+This ADR documents the agreed upon decision, rather than comparing different solutions and weighing them
+against each other.
+
+## Decision Outcome
+
+It was chosen to make each component of the guardian deployable on its own as a docker container,
+independent of the others.
+
+This allows for maximum flexibility in a kubernetes environment and maximises the separation of concerns.
+It also decreases the coupling between each component and minimizes the risk on each component if another might
+be breached.
+
+This means the [Guardian project](https://git.knut.univention.de/univention/components/authorization-engine/)
+will produce the following docker images:
+
+- Guardian Management API
+- Guardian Authorization API
+- Guardian Policy Evaluation Component (OPA)
+- Guardian Management UI
+
+The images will have the following properties:
+
+- Each image will provide one service only
+- None of the images will expose HTTPS. It is expected to be handled by a proxy.
+- All images will be [semantically versioned](https://semver.org/).
+- All images will implement a [healthcheck](https://docs.docker.com/engine/reference/builder/#healthcheck)
+- All images shall be fully configurable as to where to connect to for dependencies. This allows for injecting
+external load balancing mechanisms as well as easy setups with one container for each service.
+- All images will be based on a debian image with the s6 init system. This might change if the SWP team
+  defines a standard process of creating images.
+
+Notably absent are the **Policy Repository** and the **Data Layer**. The **Data Layer** is already implemented
+in the UCS product as the UDM REST API and thus does not need to be created by the Guardian project.
+
+The policy repository will most likely be some kind of relational database, which is implemented and published
+as docker images already.
+
+While Kubernetes will be able to utilize those images to set up a working environment, UCS is currently based on the
+Appcenter, and thus we have to bundle the images as apps in a sensitive way. The following apps will be created
+in the Appcenter:
+
+### Guardian Authorization
+
+A docker compose app that includes the Guardian Authorization API as well as the Guardian Policy Evaluation Component
+in form of an OPA service.
+
+### Guardian Management API
+
+A docker compose app, which contains the management API as well as the policy repository.
+The repository has to be synced within the UCS domain using the tools the chosen technology will offer.
+
+### Guardian Management UI
+
+A docker app, which contains the management UI. It will be served via HTTP on a specified port.
+
+## Additional points
+
+### Scaling/load balancing in the Appcenter
+
+The apps itself will not be concerned about load balancing or scaling. Since the component is split into three
+different apps (which should be configurable as to where they have to connect to find each other), scaling and load
+balancing can be done on the operators discretion.
+
+### UDM as Policy Repository
+
+Using UDM as the policy repository for the management API is not yet excluded. If chosen the Guardian Management API App might
+not have to be a docker compose app.
+
+### Policy distribution
+
+One component not mentioned here is the distribution of the data needed by the evaluation point from the policy repository.
+There are multiple possible solutions from some static bundle repository to using UDM and pushing compiled data via listeners
+to the OPA instances. The chosen option will influence the details of this decision, but not impact the central point
+of one image per service. If a decision is made a new ADR in form of an addendum to this one shall be created.

ucsschool-core/0000-use-markdown-any-decision-records.md

@@ -0,0 +1,26 @@
+# Use Markdown Any Decision Records
+
+## Context and Problem Statement
+
+We want to record any decisions made in this project independent whether decisions concern the architecture ("architectural decision record"), the code, or other fields.
+Which format and structure should these records follow?
+
+## Considered Options
+
+* [MADR](https://adr.github.io/madr/) 3.0.0 – The Markdown Any Decision Records
+* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
+* [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements
+* Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
+* Formless – No conventions for file format and structure
+
+## Decision Outcome
+
+Chosen option: "MADR 3.0.0", because
+
+* Implicit assumptions should be made explicit.
+  Design documentation is important to enable people understanding the decisions later on.
+  See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
+* MADR allows for structured capturing of any decision.
+* The MADR format is lean and fits our development style.
+* The MADR structure is comprehensible and facilitates usage & maintenance.
+* The MADR project is vivid.

ucsschool-core/0001-new-ui-architecture.md

@@ -0,0 +1,69 @@
+
+# New UI architecture for UCS(@school) frontend modules
+
+---
+
+- status: accepted
+- deciders: Ingo, Marie
+- consulted: UCS@school team
+
+---
+
+## Context and Problem Statement
+
+We want to get rid of the UMC modules architecture, which uses a deprecated JavaScript framework version, a proprietary network protocol, is stateful and does not scale to high concurrent user counts.
+In its current version it also makes a lot of work to improve accessibility aspects.
+
+The new frontend architecture should follow modern principals that are known to most frontend developers.
+
+## Decision Drivers
+
+- Accessibility requirements.
+- High scalability requirements.
+- Make recruitment and integration of new frontend developers easier, as they will be presented with a modern, non-proprietary architecture.
+- Improve development speed and reusability through separation of frontend and backend development.
+
+## Considered Options
+
+- Change Python backend: Keep the old UMC architecture, and just call REST APIs from the Python backend.
+- Call REST APIs from UMC frontend: Keep the old UMC fronend, reduce the Python backend and call REST APIs directly from JavaScript.
+- Complete rewrite: Complete rewrite of the frontend using a new JS framework and calling REST APIs directly from JS.
+
+## Decision Outcome
+
+Chosen option: "Complete rewrite", because
+it is the only solution that will attract new developers and scales.
+
+### Positive Consequences
+
+- Improved UI development speed.
+- Reduced memory footprint (no Python backend process per session).
+- REST backends are easy to benchmark.
+- Easier recruitment.
+
+### Negative Consequences
+
+- Current UI developers have to learn new framework.
+- Existing UI modules cannot be reused.
+- Lots of details (like deployment, l18n etc) have to be clarified and stabilized, which are already known for the old system.
+- Because of the unknowns, there are higher risks for the first implementations.
+
+## Validation
+
+- Retro regarding development process (separation of UI and BFF).
+- Benchmark concurrent users.
+- Validate accessibility features.
+- Feedback of HR to changed recruitment requirements.
+
+## More Information
+
+Diagrams:
+
+![Components and layers of RAM Architecture](../architecture-graphs/Role_and_Access_Model/RAM-Architecture.png "Components and layers of RAM Architecture") *Components and layers of RAM Architecture*
+
+![Sequence diagram](../architecture-graphs/Role_and_Access_Model/RAM_Sequence.png "Sequence diagram of an example page access") *Sequence diagram of an example page access*
+
+Links to related decisions and resources:
+
+- [ADR 0002 js-framework](0002-js-framework.md)
+- [ADR 0003 rest-service-dedicated-to-ui](0003-rest-service-dedicated-to-ui.md)

ucsschool-core/0002-js-framework.md

@@ -0,0 +1,60 @@
+
+# JavaScript framework for the UI of the new UCS@school frontend modules
+
+---
+
+- status: accepted
+- deciders: Ingo, Marie, Johannes
+- consulted: UCS@school team
+
+---
+
+## Context and Problem Statement
+
+- We want to replace the old "Dojo Toolkit" JavaScript UI framework with a modern UI framework.
+- In its current version it makes a lot of work to improve accessibility aspects.
+- It is also not a very popular amongst frontend developers, which makes current employees unhappy and recruitment difficult.
+- The new JS framework will have to implement the architecture decided upon in [ADR 0001 change-ui-architecture](0001-change-ui-architecture.md):
+  Instead of communicating with a UMC Python backend, it'll call REST APIs.
+
+## Decision Drivers
+
+- UI framework is very old and must be updated.
+- Accessibility requirements.
+- Make recruitment of new frontend developers easier, as they will be presented with a modern framework.
+
+## Considered Options
+
+- [Vue](https://vuejs.org/)
+- [Dojo Toolkit](https://dojotoolkit.org/)
+- [Dojo](https://dojo.io/home) (the rewrite of Dojo Toolkit)
+
+## Decision Outcome
+
+Chosen option: "Vue", because
+In the Phoenix project the Univention Portal were to be reimplemented with accessibility in mind.
+For that we chose [Vue](https://vuejs.org/) as framework to address the same issues and decision drivers as above.
+We had time with rewriting the Portal in Vue to evaluate that decision. There are no major hurdles with working with
+Vue, and it is also a popular modern framework which makes requiting easier.
+
+We additionally chose Vue for this project also because we don't want to use multiple frontend frameworks for different
+projects which would make development and consistency between the implementations unnecessarily harder.
+
+### Positive Consequences
+
+- Vue is currently popular amongst frontend developers, which will make Univention a desirable employer.
+- Vue is already used in the Univention Portal.
+
+### Negative Consequences
+
+- Using Vue instead of Dojo means, that the currently employed developers must learn a new web framework.
+- Using Vue instead of Dojo means, that existing widgets etc. cannot be reused, but must be newly created.
+
+## More Information
+
+Links to related decisions and resources:
+
+- [ADR 0001 change-ui-architecture](0001-change-ui-architecture.md)
+- [ADR 0003 rest-service-dedicated-to-ui](0003-rest-service-dedicated-to-ui.md)
+- [Epic "Widget library for portal modules"](https://git.knut.univention.de/groups/univention/-/epics/262)
+- [Epic "Create UI Design for (UCS@school) portal modules"](https://git.knut.univention.de/groups/univention/-/epics/261)

ucsschool-core/0003-rest-service-dedicated-to-ui.md

@@ -0,0 +1,84 @@
+
+# REST service dedicated to the UI
+
+---
+
+- status: accepted
+- deciders: Ingo, Marie
+- consulted: UCS@school team
+
+---
+
+## Context and Problem Statement
+
+In  [ADR 0001 change-ui-architecture](0001-change-ui-architecture.md) we decided for an architecture where the JavaScript frontend gets data from REST APIs.
+
+Existing REST APIs for UCS@school domain objects lack required information:
+
+- UI layout
+- Data types (although it may be possible to extract it from the OpenAPI schema)
+- Attribute access permissions
+- Action permissions
+- Sorting
+- Pagination
+- User preferences (columns, filters, …)
+
+## Decision Drivers
+
+- Layout and behavior of the UI is highly configurable (layout, attributes, permissions, preferences).
+- High scalability requirements.
+- Make recruitment and integration of new frontend and backend developers easier, using a modern, non-proprietary software architecture.
+- Improve development speed through separation of frontend and backend development.
+
+## Considered Options
+
+- Very smart frontend:
+  - Retrieve data types from the OpenAPI schema of the Kelvin REST API and the UDM REST API.
+  - Access [Open Policy Agent](https://www.openpolicyagent.org/) (OPA) directly to get permission and attribute information.
+  - Sort and paginate lists of users and groups in the frontend.
+  - Access the [Configuration database for distributed Systems](https://git.knut.univention.de/groups/univention/dev-issues/-/epics/19) to retrieve user preferences and layout information.
+- Less smart frontend plus "Backend for frontend" (BFF) API:
+  - One or more dedicated REST API services offer the above data in a format specifically adapted to the requirements of each UI module.
+  - The BFF service(s) contact further backend services (Kelvin REST API, UDM REST API, OPA, Configuration database), collect, sort, merge and transform the data according to the requests from the UI.
+
+## Decision Outcome
+
+Chosen option: "Less smart frontend plus BFF", because
+
+- It is easier to contact, collect, sort, merge and transform data in Python.
+- The backend services do not need to be exposed to the public internet (the UI is running in an endusers browser).
+  This reduces the authentication and authorization requirements of those services. (A "zero trust" security model would still be better.)
+- Changing the interfaces of backend services does not affect the UI, as only the BFF must be adapted.
+- The BFF can be written by both frontend and backend developers.
+
+The BFF for the "Users" and "Groups" modules for the RAM/BSB project will be called "Rankine API".
+
+The Rankine API will be implemented according to the [REST API stack for Univention](https://git.knut.univention.de/univention/internal/research-library/-/blob/main/personal/dtroeder/api_stack.md) using FastAPI, Gunicorn etc.
+
+Access to the Rankine API must be authenticated by an external service (see [ADR 0005 authentication-in-the-new-UI-architecture](0005-authentication-in-the-new-UI-architecture)).
+
+### Positive Consequences
+
+- If a second UI (e.g. native mobile client) would be created, adapted BFF routed could be created for it, reusing the bulk of the business logic.
+- Improved UI development speed, as the business logic (in the BFF) can be written in parallel to the fronend.
+- REST backend are easy to benchmark.
+- When the requirements of the UI change, frontend developers can adapt the BFF themselves, making frontend teams more independent of backend teams.
+
+### Negative Consequences
+
+- The additional REST API intermediary adds request latency.
+- Single point of failure.
+
+## Validation
+
+- Retro regarding development process (separation of UI and BFF).
+- Benchmark concurrent users.
+
+## More Information
+
+Links to related decisions and resources:
+
+- [ADR 0001 change-ui-architecture](0001-change-ui-architecture.md)
+- [ADR 0002 js-framework](0002-js-framework.md)
+- [Epic "BFF for school portal modules"](https://git.knut.univention.de/groups/univention/-/epics/279)
+- [Configuration database for distributed Systems](https://git.knut.univention.de/groups/univention/dev-issues/-/epics/19)