From 2031461349bc948927e7830c149e44cbe67074e2 Mon Sep 17 00:00:00 2001 From: Ralf Haferkamp Date: Tue, 8 Feb 2022 13:26:48 +0100 Subject: [PATCH 1/6] ADR: Add first draft for readonly external user management --- .../ocis/adr/0003-external-user-management.md | 5 +- ...llow-read-only-external-user-management.md | 96 +++++++++++++++++++ 2 files changed, 99 insertions(+), 2 deletions(-) create mode 100644 docs/ocis/adr/0017-allow-read-only-external-user-management.md diff --git a/docs/ocis/adr/0003-external-user-management.md b/docs/ocis/adr/0003-external-user-management.md index 025c2ec210..7cdb66dda1 100644 --- a/docs/ocis/adr/0003-external-user-management.md +++ b/docs/ocis/adr/0003-external-user-management.md @@ -7,9 +7,9 @@ geekdocEditPath: edit/master/docs/ocis/adr geekdocFilePath: 0003-external-user-management.md --- -* Status: accepted +* Status: superseded by [17. Allow read only external User Management]({{< ref "0017-allow-read-only-external-user-management.md" >}}) * Deciders: @butonic, @micbar, @dragotin, @hodyroff, @pmaier1 -* Date: 2020-12-09 +* Date: 2022-02-08 Technical Story: [Skip account-service by talking to CS3 user-api](https://github.com/owncloud/ocis/pull/1020) @@ -112,3 +112,4 @@ We should use an existing LDAP server and make GLAuth a drop in replacement for ## Links * supersedes [ADR-0001]({{< ref "0001-introduce-accounts-service.md" >}}) +* superseded by [17. Allow read only external User Management]({{< ref "0017-allow-read-only-external-user-management.md" >}}) diff --git a/docs/ocis/adr/0017-allow-read-only-external-user-management.md b/docs/ocis/adr/0017-allow-read-only-external-user-management.md new file mode 100644 index 0000000000..3660f95991 --- /dev/null +++ b/docs/ocis/adr/0017-allow-read-only-external-user-management.md @@ -0,0 +1,96 @@ +--- +title: "17. Allow read only external User Management" +--- + +* Status: proposed +* Deciders: @butonic, @micbar, @rhafer +* Date: 2022-02-08 + +## Context and Problem Statement + +oCIS needs to be integrated with various external Authentication and Identity Management System. We +settled on Open ID Connect (OIDC) as the central authentication protocol for OCIS. + +OCIS internally relies on a stable and persistent identifier (e.g. a UUID) for accounts in order to +implement permissions and sharing. Unfortunately, some deployments are unable to deliver this kind +of stable identifier for users: + +- In OIDC itself the only stable identifier that is guaranteed to be provided by the IDP is + combination of the sub and iss claims. IDPs can optionally return other claims, but we might not + be able to rely on a specific claim being present. +- When no other services (LDAP, SCIM, ...) is available that could be used look up a user UUID + +Furthermore, there is a difference between users, identities and accounts: A user may have multiple +identities whith which he can authenticate, e.g. his facebook, twitter, microsoft or google +identity. Multiple identities can be linked to an account in ocis, allowing to fall back to another +identity provider should one of them shut down. This also allows migrating from one identity +provider to another. + +There are three cases that require access to users:a + +1. During authentication we neet to build a user object with at least an account uuid (to identify + the account) and the email (for display purposes) +2. When searching for recipients we need to be able to query existing users in the external identity + management system +3. When listing files we need to be able to look up a users display properties (username, email, + avatar...) based on the account uuid + +## Decision Drivers + +* 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. +* oCIS should be able to be easily integrated with external standard identity mangement systems + +## Considered Options + +* External identity management system is writeable and has all necessary APIs +* External identity management system is read only and provides an interface to query users (e.g. +* IdP is read only and does not provide an API to query users + +## Decision Outcome + +tbd + +### Positive Consequences: + + +### Negative consequences: + + +## Pros and Cons of the Options + +### External identity management system is writeable and has all necessary APIs + +IdP sends all necessary claims: uuid, username, email, displayname, avatar url IdP allows lookup of +display properties by the uuid or email/username + +* Good, because we can fully rely on the external identity management system +* Bad, because we need write access to provision guest accounts + +### External identity management system is read only and provides an interface to query users (e.g. Coporate Active Directy) + +IdP ends sub & iss and mail or username claims, Identity Management System provides Interfaces (e.g. +LDAP) to lookup additional user information. All services use the CS3 API to look up the account for +the given email or username, where CS3 provides backends for LDAP, SCIM, REST ... + +* Good, because we can rely on the external identity management +* Bad, because the Identity managment needs to provide a stable, persistent, non-reussignable user + identifier to identify the account, e.g. owncloudUUID or ms-DS-ConsistencyGuid +* Bad, because we need to implment tools that can change the account id when it did change anyway +* Bad, because we will hammer the identity management system with lookup requests (can mostly be + mitigated with caching) + +### IdP is read only and does not provide an API to query users + +Idp sends sub & iss and mail or username claims. We need to provision an internal account mapping to +look up user properties by account id. + +* Good, because this has very little external requirements +* Bad, because we have to provide the user lookup APIs + +## Links + +* [Link type] [Link to ADR] +* … +* supersedes [3. Use external User Management]({{< ref "0003-external-user-management.md" >}}) From 5a390baaa1bb8a2c35ebeff9f1e9a632bdf2ca3b Mon Sep 17 00:00:00 2001 From: Ralf Haferkamp Date: Tue, 8 Feb 2022 15:19:27 +0100 Subject: [PATCH 2/6] Typo fixes and clarifications MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jörn Friedrich Dreyer --- ...llow-read-only-external-user-management.md | 34 +++++++++++-------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/docs/ocis/adr/0017-allow-read-only-external-user-management.md b/docs/ocis/adr/0017-allow-read-only-external-user-management.md index 3660f95991..a43713bac2 100644 --- a/docs/ocis/adr/0017-allow-read-only-external-user-management.md +++ b/docs/ocis/adr/0017-allow-read-only-external-user-management.md @@ -1,5 +1,10 @@ --- title: "17. Allow read only external User Management" +weight: 17 +date: 2022-02-08T10:53:00+01:00 +geekdocRepo: https://github.com/owncloud/ocis +geekdocEditPath: edit/master/docs/ocis/adr +geekdocFilePath: 0017-allow-read-only-external-user-management.md --- * Status: proposed @@ -8,7 +13,7 @@ title: "17. Allow read only external User Management" ## Context and Problem Statement -oCIS needs to be integrated with various external Authentication and Identity Management System. We +oCIS needs to be integrated with various external Authentication and Identity Management Systems. We settled on Open ID Connect (OIDC) as the central authentication protocol for OCIS. OCIS internally relies on a stable and persistent identifier (e.g. a UUID) for accounts in order to @@ -26,27 +31,27 @@ identity. Multiple identities can be linked to an account in ocis, allowing to f identity provider should one of them shut down. This also allows migrating from one identity provider to another. -There are three cases that require access to users:a +There are three cases that require access to users: -1. During authentication we neet to build a user object with at least an account uuid (to identify +1. During authentication we need to build a user object with at least an account UUID (to identify the account) and the email (for display purposes) 2. When searching for recipients we need to be able to query existing users in the external identity management system 3. When listing files we need to be able to look up a users display properties (username, email, - avatar...) based on the account uuid + avatar...) based on the account UUID ## Decision Drivers * 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. -* oCIS should be able to be easily integrated with external standard identity mangement systems +* oCIS should be easy to integrate with standard external identity mangement systems ## Considered Options * External identity management system is writeable and has all necessary APIs -* External identity management system is read only and provides an interface to query users (e.g. -* IdP is read only and does not provide an API to query users +* External identity management system is read only and provides an interface to query users +* External identity management system is read only and does NOT provide an API to query users ## Decision Outcome @@ -70,18 +75,17 @@ display properties by the uuid or email/username ### External identity management system is read only and provides an interface to query users (e.g. Coporate Active Directy) -IdP ends sub & iss and mail or username claims, Identity Management System provides Interfaces (e.g. -LDAP) to lookup additional user information. All services use the CS3 API to look up the account for -the given email or username, where CS3 provides backends for LDAP, SCIM, REST ... +IdP sends sub & iss and mail or username claims, Identity Management System provides APIs (e.g. +LDAP, SCIM, REST ...) to lookup additional user information. All services use the CS3 API to look up the account for +the given email or username, where CS3 then uses a backend that relies on the APIs provided by the IdM``` * Good, because we can rely on the external identity management -* Bad, because the Identity managment needs to provide a stable, persistent, non-reussignable user - identifier to identify the account, e.g. owncloudUUID or ms-DS-ConsistencyGuid +* Bad, because the identity managment needs to provide a stable, persistent, non-reassignable user + identifier for an account, e.g. `owncloudUUID` or `ms-DS-ConsistencyGuid` * Bad, because we need to implment tools that can change the account id when it did change anyway -* Bad, because we will hammer the identity management system with lookup requests (can mostly be - mitigated with caching) +* Bad, because without caching we will hammer the identity management system with lookup requests -### IdP is read only and does not provide an API to query users +### External identity management system is read only and does NOT provide an API to query users Idp sends sub & iss and mail or username claims. We need to provision an internal account mapping to look up user properties by account id. From 6a4af40d524a28c7c8ec2c715d7a7ddc817dbaf5 Mon Sep 17 00:00:00 2001 From: Ralf Haferkamp Date: Tue, 8 Feb 2022 15:20:26 +0100 Subject: [PATCH 3/6] Collect more pros and cons for the different options MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jörn Friedrich Dreyer --- ...llow-read-only-external-user-management.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/ocis/adr/0017-allow-read-only-external-user-management.md b/docs/ocis/adr/0017-allow-read-only-external-user-management.md index a43713bac2..4526b294d9 100644 --- a/docs/ocis/adr/0017-allow-read-only-external-user-management.md +++ b/docs/ocis/adr/0017-allow-read-only-external-user-management.md @@ -71,15 +71,22 @@ IdP sends all necessary claims: uuid, username, email, displayname, avatar url I display properties by the uuid or email/username * Good, because we can fully rely on the external identity management system -* Bad, because we need write access to provision guest accounts +* Bad, because we need write access to provision guest accounts (very few customers are willing to + provide that) ### External identity management system is read only and provides an interface to query users (e.g. Coporate Active Directy) IdP sends sub & iss and mail or username claims, Identity Management System provides APIs (e.g. -LDAP, SCIM, REST ...) to lookup additional user information. All services use the CS3 API to look up the account for -the given email or username, where CS3 then uses a backend that relies on the APIs provided by the IdM``` +LDAP, SCIM, REST ...) to lookup additional user information. All services use the CS3 API to look up +the account for the given email or username, where CS3 then uses a backend that relies on the APIs +provided by the IdM. * Good, because we can rely on the external identity management +* Good, because ocis services only need to know about the CS3 user provider API, which acts as an + abstraction layer for different identitiy management systems +* Good, because there is only an single source of truth (the external IdM) and we don't need to + implement a synchronization mechanism to maintain an internal user database (we will likely need + some form of caching though, see below) * Bad, because the identity managment needs to provide a stable, persistent, non-reassignable user identifier for an account, e.g. `owncloudUUID` or `ms-DS-ConsistencyGuid` * Bad, because we need to implment tools that can change the account id when it did change anyway @@ -87,11 +94,13 @@ the given email or username, where CS3 then uses a backend that relies on the AP ### External identity management system is read only and does NOT provide an API to query users -Idp sends sub & iss and mail or username claims. We need to provision an internal account mapping to -look up user properties by account id. +Idp sends sub & iss and mail or username claims. We need to provision an internal account mapping +upon first login of a user to be able to look up user properties by account id. * Good, because this has very little external requirements +* Good, because we have accounts fully under our control * Bad, because we have to provide the user lookup APIs +* Bad, because users will only a visible after the first login ## Links From 5c59bf7b59ad4d9c15f33c07d35df589b1ebdd76 Mon Sep 17 00:00:00 2001 From: Ralf Haferkamp Date: Tue, 8 Feb 2022 16:05:47 +0100 Subject: [PATCH 4/6] Rearrange Context and Problem Statement a bit --- ...llow-read-only-external-user-management.md | 35 ++++++++++--------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/docs/ocis/adr/0017-allow-read-only-external-user-management.md b/docs/ocis/adr/0017-allow-read-only-external-user-management.md index 4526b294d9..f051848b02 100644 --- a/docs/ocis/adr/0017-allow-read-only-external-user-management.md +++ b/docs/ocis/adr/0017-allow-read-only-external-user-management.md @@ -13,33 +13,34 @@ geekdocFilePath: 0017-allow-read-only-external-user-management.md ## Context and Problem Statement -oCIS needs to be integrated with various external Authentication and Identity Management Systems. We -settled on Open ID Connect (OIDC) as the central authentication protocol for OCIS. +oCIS needs to be integrated with various external Authentication and Identity Management Systems. -OCIS internally relies on a stable and persistent identifier (e.g. a UUID) for accounts in order to -implement permissions and sharing. Unfortunately, some deployments are unable to deliver this kind -of stable identifier for users: - -- In OIDC itself the only stable identifier that is guaranteed to be provided by the IDP is - combination of the sub and iss claims. IDPs can optionally return other claims, but we might not - be able to rely on a specific claim being present. -- When no other services (LDAP, SCIM, ...) is available that could be used look up a user UUID - -Furthermore, there is a difference between users, identities and accounts: A user may have multiple +Sidenote: There is a difference between users, identities and accounts: A user may have multiple identities whith which he can authenticate, e.g. his facebook, twitter, microsoft or google identity. Multiple identities can be linked to an account in ocis, allowing to fall back to another identity provider should one of them shut down. This also allows migrating from one identity provider to another. -There are three cases that require access to users: +There are different cases where oCIS requires access to users: -1. During authentication we need to build a user object with at least an account UUID (to identify - the account) and the email (for display purposes) -2. When searching for recipients we need to be able to query existing users in the external identity - management system +1. While we settled on using OpenID Connect (OIDC) as the authentication protocol for oCIS, we + we need to build a user object during authentication with at least an account UUID (to identify + the account) and the email or a name (for display purposes). +2. When searching for share recipients we need to be able to query existing users in the external + identity management system 3. When listing files we need to be able to look up a users display properties (username, email, avatar...) based on the account UUID +oCIS internally relies on a stable and persistent identifier (e.g. a UUID) for accounts in order to +implement permissions and sharing. Unfortunately, some deployments are unable to deliver this kind +of stable identifier for users: + +- In OIDC itself the only stable identifier that is guaranteed to be provided by the IDP is + combination of the sub and iss claims. IDPs can optionally return other claims, but we cannot + rely on a specific claim being present. +- When no other services (LDAP, SCIM, ...) is available that could be used look up a user UUID + + ## Decision Drivers * oCIS should be a single binary that can run out of the box without external dependencies like an From 22ca7e62238625a51672cbdbd7e062288be3451d Mon Sep 17 00:00:00 2001 From: Ralf Haferkamp Date: Thu, 10 Feb 2022 15:54:19 +0100 Subject: [PATCH 5/6] removed the "identity management system is writeable" This ADR is supposed to be about the read-only case. --- ...llow-read-only-external-user-management.md | 37 ++++++++++--------- 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/docs/ocis/adr/0017-allow-read-only-external-user-management.md b/docs/ocis/adr/0017-allow-read-only-external-user-management.md index f051848b02..a6c2c719a1 100644 --- a/docs/ocis/adr/0017-allow-read-only-external-user-management.md +++ b/docs/ocis/adr/0017-allow-read-only-external-user-management.md @@ -14,6 +14,9 @@ geekdocFilePath: 0017-allow-read-only-external-user-management.md ## Context and Problem Statement oCIS needs to be integrated with various external Authentication and Identity Management Systems. +Usually oCIS will no have administrative access to such a system and we will not be allowed to +reconfigure it suite our needs (e.g. we will not be able to enhance the schema of an already existing +LDAP Directory). In most case our access will be read-only. Sidenote: There is a difference between users, identities and accounts: A user may have multiple identities whith which he can authenticate, e.g. his facebook, twitter, microsoft or google @@ -50,37 +53,32 @@ of stable identifier for users: ## Considered Options -* External identity management system is writeable and has all necessary APIs -* External identity management system is read only and provides an interface to query users -* External identity management system is read only and does NOT provide an API to query users +There are two case to consider: +* External identity management system provides an OIDC IdP and an interface to query users +* External identity management system provides just an OIDC IdP with no possibility to query users ## Decision Outcome -tbd +It's not really possible single out any of the options for this ADR. In the end we will likely need +to support both scenarios. ### Positive Consequences: +* Very flexible integration with a wide range of external systems ### Negative consequences: +* configuration complexity, high support efforts +* Increasingly complex code in oCIS ## Pros and Cons of the Options -### External identity management system is writeable and has all necessary APIs - -IdP sends all necessary claims: uuid, username, email, displayname, avatar url IdP allows lookup of -display properties by the uuid or email/username - -* Good, because we can fully rely on the external identity management system -* Bad, because we need write access to provision guest accounts (very few customers are willing to - provide that) - ### External identity management system is read only and provides an interface to query users (e.g. Coporate Active Directy) IdP sends sub & iss and mail or username claims, Identity Management System provides APIs (e.g. -LDAP, SCIM, REST ...) to lookup additional user information. All services use the CS3 API to look up -the account for the given email or username, where CS3 then uses a backend that relies on the APIs -provided by the IdM. +LDAP, SCIM, REST ...) to lookup additional user information. All oCIS services use the CS3 API to +look up the account for the given email or username, where CS3 then uses a backend that relies on +the APIs provided by the IdM. * Good, because we can rely on the external identity management * Good, because ocis services only need to know about the CS3 user provider API, which acts as an @@ -95,13 +93,16 @@ provided by the IdM. ### External identity management system is read only and does NOT provide an API to query users -Idp sends sub & iss and mail or username claims. We need to provision an internal account mapping -upon first login of a user to be able to look up user properties by account id. +Idp sends sub & iss and mail or username claims. We need to provision an internal account mapping, +creating a unique ID, upon the first login of a user to be able to look up user properties by account +id. * Good, because this has very little external requirements * Good, because we have accounts fully under our control * Bad, because we have to provide the user lookup APIs * Bad, because users will only a visible after the first login +* Bad, because our internal account mapping might get out of date when user attribute (e.g. name or + mail) change. At least until the next time that user logs in ## Links From 7d511eabb94c683d12da9b7c0a9c3431d318e891 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rn=20Friedrich=20Dreyer?= Date: Thu, 24 Feb 2022 12:44:18 +0100 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Michael Barz --- .../0017-allow-read-only-external-user-management.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/ocis/adr/0017-allow-read-only-external-user-management.md b/docs/ocis/adr/0017-allow-read-only-external-user-management.md index a6c2c719a1..879171b370 100644 --- a/docs/ocis/adr/0017-allow-read-only-external-user-management.md +++ b/docs/ocis/adr/0017-allow-read-only-external-user-management.md @@ -14,12 +14,12 @@ geekdocFilePath: 0017-allow-read-only-external-user-management.md ## Context and Problem Statement oCIS needs to be integrated with various external Authentication and Identity Management Systems. -Usually oCIS will no have administrative access to such a system and we will not be allowed to -reconfigure it suite our needs (e.g. we will not be able to enhance the schema of an already existing -LDAP Directory). In most case our access will be read-only. +Usually oCIS will have no administrative access to such a system and we will not be allowed to +reconfigure it to suit our needs (e.g. we will not be able to enhance the schema of an already existing +LDAP Directory). In most of the cases our access will be read-only. Sidenote: There is a difference between users, identities and accounts: A user may have multiple -identities whith which he can authenticate, e.g. his facebook, twitter, microsoft or google +identities which he can authenticate with, e.g. his facebook, twitter, microsoft or google identity. Multiple identities can be linked to an account in ocis, allowing to fall back to another identity provider should one of them shut down. This also allows migrating from one identity provider to another. @@ -41,7 +41,7 @@ of stable identifier for users: - In OIDC itself the only stable identifier that is guaranteed to be provided by the IDP is combination of the sub and iss claims. IDPs can optionally return other claims, but we cannot rely on a specific claim being present. -- When no other services (LDAP, SCIM, ...) is available that could be used look up a user UUID +- When no other services (LDAP, SCIM, ...) are available that could be used look up a user UUID ## Decision Drivers @@ -83,7 +83,7 @@ the APIs provided by the IdM. * Good, because we can rely on the external identity management * Good, because ocis services only need to know about the CS3 user provider API, which acts as an abstraction layer for different identitiy management systems -* Good, because there is only an single source of truth (the external IdM) and we don't need to +* Good, because there is only a single source of truth (the external IdM) and we don't need to implement a synchronization mechanism to maintain an internal user database (we will likely need some form of caching though, see below) * Bad, because the identity managment needs to provide a stable, persistent, non-reassignable user