Introduce ADR

changelog/unreleased/introduce-adr.md

@@ -0,0 +1,5 @@
+Enhancement: Introduce ADR
+
+We will keep track of [Architectual Decision Records using Markdown](https://adr.github.io/madr/) in `/docs/adr`.
+
+https://github.com/owncloud/ocis/pull/1042

docs/adr/0001-introduce-accounts-service.md

@@ -0,0 +1,43 @@
+# 1. Introduce an accounts service
+
+* Status: superseded by [ADR-0003](0003-outsource-user-management.md) <!-- optional -->
+* Deciders: @butonic, @felixboehm, @mbarz, @pmaier1 <!-- optional -->
+* Date: [2020-06-15](https://github.com/owncloud/ocis-accounts/pull/34/commits/2fd05e2b6fe2a47c687bd0c0bc5e1b5c48a585b2) <!-- optional -->
+
+Technical Story: [persist accounts](https://github.com/owncloud/ocis-accounts/pull/34) <!-- optional -->
+
+## Context and Problem Statement
+
+To attach metadata like shares to users ownCloud relies on persistent, non-reassignable, unique identifiers for users (and files). Email und username can change when a user changes his name. But even the OIDC sub+iss combination may change when the IdP changes. While there is [an account porting protocol](https://openid.net/specs/openid-connect-account-porting-1_0.html) that describes how a relying party such as ownCloud should should behave, it still requires the RP to maintain its own user identifiers.
+
+## Decision Drivers <!-- optional -->
+
+* OCIS should be a single binary that can run out of the box without external dependencies like an LDAP server.
+* Time: we want to build a release candidate asap.
+* Firewalls need access to guests, typically via LDAP.
+* Not all external LDAPs are writebale for us to provision Guest accounts.
+* We see multiple LDAP servers in deployments. Being able to handle them is important and should be coveredy by using OIDC + being able to query multiple LDAP servers.
+
+## Considered Options
+
+* Accounts service wraps LDAP
+* GLauth wraps accounts service
+
+## Decision Outcome
+
+Chosen option: "GLauth wraps accounts service", because we need write access to provision guest accounts and [GLauth](https://github.com/glauth/glauth) currently has no write support.
+
+### Positive Consequences <!-- optional -->
+
+* We can build a self contained user management in the accounts service and can adjust it to our requirements.
+* We do not rely on an LDAP server which would only be possible by implementing write support in the LDAP libraries used by GLauth which (hard to estimate effort, when will that be merged upstream).
+
+### Negative Consequences <!-- optional -->
+
+* We need to spend time on implementing user management
+
+## Pros and Cons of the Options <!-- optional -->
+
+### Accounts service wraps LDAP
+
+* Bad, because not all external LDAPs are writebale for us to provision Guest accounts.

docs/adr/0002-persist-accounts-using-cs3-storage.md

@@ -0,0 +1,29 @@
+# 2. Persist accounts in a CS3 storage
+
+* Status: accepted <!-- optional -->
+* Deciders: @butonic, @felixboehm <!-- optional -->
+* Date: 2020-08-21 <!-- optional -->
+
+Technical Story: [File system based indexing](https://github.com/owncloud/ocis-accounts/pull/92) <!-- optional -->
+
+## Context and Problem Statement
+
+To set up HA or a geo replicated setup we need to persist accounts in a distributed way. Furthermore, the bleve index makes the accounts service stateful, which we wand to avoid for a scale out deployment.
+
+## Considered Options
+
+* Look into distributed bleve
+* Persist users in a CS3 storage
+
+## Decision Outcome
+
+Chosen option: "Persist users in a CS3 storage", because we have one service less running and can rely on the filesystem for geo replication and HA.
+
+### Positive Consequences <!-- optional -->
+
+* We can store accounts on the storage using the CS3 API, pushing geo-distribution to the storage layer.
+* Backups of users and storage can be implemented without inconsistencies between using snapshots.
+
+### Negative Consequences <!-- optional -->
+
+* We need to spend time on implementing a reverse index based on files, and symlinks.

docs/adr/0003-outsource-user-management.md

@@ -0,0 +1,91 @@
+# 3. Outsource Usermanagement
+
+* Status: accepted <!-- optional -->
+* Deciders: @butonic, @mbarz, @kfreitag, @hd, @pmaier1 <!-- optional -->
+* Date: 2020-12-09 <!-- optional -->
+
+Technical Story: [Skip account-service by talking to CS3 user-api](https://github.com/owncloud/ocis/pull/1020) <!-- optional -->
+
+## Context and Problem Statement
+
+To attach metadata like shares to users ownCloud relies on persistent, non-reassignable, unique identifiers for users (and files). Email und username can change when a user changes his name. But even the OIDC sub+iss combination may change when the IdP changes. While there is [an account porting protocol](https://openid.net/specs/openid-connect-account-porting-1_0.html) that describes how a relying party such as ownCloud should should behave, it still requires the RP to maintain its own user identifiers.
+
+## Decision Drivers <!-- optional -->
+
+* OCIS should be a single binary that can run out of the box without external dependencies like an LDAP server.
+* Time: we want to build a release candiddate asap.
+
+## Considered Options
+
+* Accounts service wraps LDAP
+* GLauth wraps accounts service
+
+## Decision Outcome
+
+Chosen option: "Move accounts functionality to GLauth and name it accounts", by moving the existing accounts service file based persistence to glauth and use it as a drop in replacement for an LDAP server. The reverse index and web ui existing in the accounts service will move as well in order to make glauth a standalone, small scale user management with write capabilities.
+
+### Product summary
+- GLauth is a drop in user management for small scale deployments.
+- OCIS admins can either use the web ui to manage users in glauth or use existing tools in their IDM.
+- We hide the complexity by embedding OpenID Provider, an LDAP server and a user management web ui.
+
+### Resulting deployment options
+- Single binary: admin can manage users, groups and roles using the built in web ui (glauth)
+- External LDAP: OCIS admin needs do use existing tool to manage users
+- Separate OCIS and LDAP admin: OCIS admin relies on the LDAP admin to manage users
+
+### Resulting technical implications
+- add graphapi to glauth so the ocis web ui can use it to manage users
+- make graphapi service to directly talk to an LDAP server so our web ui can use it
+- keep the accounts service but embed glauth
+- add graph api to the accounts service?
+
+### Positive Consequences <!-- optional -->
+
+* The accounts service (which is our drop in LDAP solution) can be disabled.
+* No sync
+
+### Negative Consequences <!-- optional -->
+
+* If users want to store users in their IDM and at the same time guests in a seperate user management we need to implement ldap backends that support more than one LDAP server.
+
+## Pros and Cons of the Options <!-- optional -->
+
+### GLauth wraps accounts service
+
+Currently, the accounts service is the source of truth and we use it to implement user management. <!-- optional -->
+
+* Good, because it solves the problem of storing and looking up an owncloud uuid for a user (and group)
+* Good, because we can manage users out of the box
+* Good, because we can persist accounts in a CS3 storage provider
+* Bad, because it maintains a separate user repository: it needs to either learn or sync users.
+* … <!-- numbers of pros and cons can vary -->
+
+### Move accounts functionality to GLauth and name it accounts
+
+We should use an existing ldap server and make GLauth a drop in replacement for it. <!-- optional -->
+
+* Good, because we can use an existing user repository (an LDAP server), no need to sync or learn users.
+* Good, because admins can rely on existing user managemen tools.
+* Good, because we would have a clear seperation of concerns:
+  - users reside in whatever repository, typically an LDAP server
+    - could be an existing LDAP server or AD
+    - could be our embeddable drop in glauth server
+  - we use a service to wrap the LDAP server with other APIs:
+    - graph API - ODATA based restful api,
+    - [SCIM](http://www.simplecloud.info/) - designed to manage user identities, supported by some IDPs,
+    - the current accounts API (which is a protobuf spec following the graph api)
+  - our account management ui can use the graph api service which can have different backends
+    - an existing ldap server
+    - our drop in glauth server (which might serve the graph api itself)
+    - the cs3 api + a future guest provisioning api + a future cs3 user provisioning api 
+  - all ocis services can use the service registry to look up the accounts service that provides an internal api
+    - could be the CS3 user provider (and API)
+    - could be the internal protobuf accounts API
+  - introduce a new guest provisioning api to CS3 which properly captures our requirement to have them in the user repository
+    - guests need to be made available to the firewall
+    - storages like eos that integrate with the os for acl based file permissions need a numeric user and group id
+* Good, because we can use the CS3 user proviter with the existing ldap / rest driver.
+* Bad, because OCIS admins may not have the rights to manage role assignments. (But this is handled at a different department.) 
+* Bad, because OCIS admins may not have the rights to disable users if an external LDAP is used instead of the drop in GLauth.
+* … <!-- numbers of pros and cons can vary -->