From fa363256189c14f6b32c88e8d60ffd2f66659e3e Mon Sep 17 00:00:00 2001 From: William Brown <william@blackhats.net.au> Date: Sat, 29 Mar 2025 14:58:45 +1000 Subject: [PATCH 1/4] Ideas about service accounts --- .../developers/designs/service_accounts.md | 119 ++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 book/src/developers/designs/service_accounts.md diff --git a/book/src/developers/designs/service_accounts.md b/book/src/developers/designs/service_accounts.md new file mode 100644 index 000000000..e960d9d4d --- /dev/null +++ b/book/src/developers/designs/service_accounts.md @@ -0,0 +1,119 @@ +# Service Account Improvements - 2025 + +Initially when service accounts were added to Kanidm they were simply meant to be "detached" +accounts that could be used for some API access to Kani, or some other background tasks. + +But as the server has evolved we need to consider how we can use these in other ways. + +We have extented the OAuth2 client types to now almost act like a service account, especially +with the behaviour of things like a client credentials grant. + +At this point we need to decide how to proceed with service accounts and what shape they could +take in the future. + +## Prior Art + +* (Microsoft AD-DS Service Accounts)[https://learn.microsoft.com/en-us/windows-server/identity/ad-ds/manage/understand-service-accounts] +* (FreeIPA Service Principals)[https://www.freeipa.org/page/Administrators_Guide#managing-service-principals] + +Note that both of these have some kerberos centric ideas as KRB requires service accounts to mutually +authenticate to clients, which means they need to maintain credentials. This is different to our needs, +but there are still some ideas in these docs worth knowing about and considering like group managed +service accounts (gMSA). + +## High Level Suggestions + +There are the ideas today that I have - there may be others! + +* Service Accounts can have attached roles. +* Keep concerns separate. +* Bit of A, bit of B, cleanup. + +## Current state of affairs + +We have: + +* Break glass accounts are service accounts, may not have delegated management. +* OAuth2 is not a service account, supports delegated management. +* Service accounts can be group or user managed. +* Applications (To Be Introduced) is an extension of a Service account. + +From this we can see that we have some separation, but also some cross over of functionality. +break glass isn't delegated, but service account is, OAuth2 isn't an SA, but Applications are. + +## Attach roles to service accounts. + +In this approach we centre the service account, and allow optional extension of other concerns. This +would make OAuth2 applications an extension of a service account. Similar Application as well. + +This would mean that we create a service account first, then need a way to extend it with the +application or oauth2 types. + +PROS: + +* OAuth2 applications get the ability to have api tokens to kani for other functionality +* Fullstacks like a mail server get a single SA that does everything +* These whole stack service accounts get access to every auth type and feature available + +CONS: + +* Makes the API around service accounts a bit messier +* Compromise of the SA or SA Manager may lead to higher impact due to more features in one place +* May be confusing to administrators +* More "inheritance" of schema classes, when we may want to try to simplify to single classes in line with SCIM. +* Harder to audit capabilities + +## Separate Concerns + +In this approach we split our concerns. This is similar to today, but taken a bit further. + +In this example, we would split Application to *just* be about the concern of an authentication +domain for LDAP applications. OAuth2 stays as *just* a configuration of the client and it's behaviour. + +We would change the break glass accounts to be a separate type to Service Account. Service Account +becomes closer to the concept of a pure api access account. The break glass accounts become a +dedicated "emergency access account" type. + +PROS: + +* Similar to today, only small cleanup needed +* Separation of concerns and credentials limit's blast radius of a possible compromise. +* Easier auditing of capabilities of each account + +CONS: + +* More administrative overhead to manage the multiple accounts +* Stacked applications will need mulitple configurations for a role - OAuth2, LDAP application, Service accounts for example in an email server with a WebUI. + +## Bit of A, bit of B, cleanup + +Rather than fully merge all the types, or fully split them, have a *little* merge of some bits, allowing +some limited extension of actions to specific actors. + +OAuth2 and Applications would gain the ability to have API tokens associated for some tasks and +could act on Kanidm, but they wouldn't be fully fleshed service accounts. + +| | Api Token | OAuth2 Sessions | Interactive Login | +|-----------------|------------------|------------------------------|---------------------| +| OAuth2 | Yes | Via Client Credentials Grant | No | +| Application | Yes | No | No | +| Service Account | Yes (rw capable) | Yes (via session grant (TBD) | Yes (to be removed) | +| Break Glass | No | No | Yes | + +PROS: + +* Minimises changes to existing deployments +* Grants some new abilities within limits to other roles +* While not as locked down as separate concern proposal, still minimises the risk of compromise of an SA + + +CONS: + +* Requires admins to have multiple accounts in some contexts (as above). +* Auditing requires knowledge of what each roles capabilities are + + + + + + From e35d4fddc1874b646de1e93a9db4ccf5ad33c792 Mon Sep 17 00:00:00 2001 From: William Brown <william@blackhats.net.au> Date: Sat, 29 Mar 2025 15:25:23 +1000 Subject: [PATCH 2/4] Update --- book/src/developers/designs/service_accounts.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/book/src/developers/designs/service_accounts.md b/book/src/developers/designs/service_accounts.md index e960d9d4d..7935dff6d 100644 --- a/book/src/developers/designs/service_accounts.md +++ b/book/src/developers/designs/service_accounts.md @@ -87,15 +87,18 @@ CONS: ## Bit of A, bit of B, cleanup +AKA Capabilities + Rather than fully merge all the types, or fully split them, have a *little* merge of some bits, allowing -some limited extension of actions to specific actors. +some limited extension of actions to specific actors. Effectively we end up granting *capabilities* +to different roles, and we can add extra capabilities later if we want. OAuth2 and Applications would gain the ability to have API tokens associated for some tasks and could act on Kanidm, but they wouldn't be fully fleshed service accounts. -| | Api Token | OAuth2 Sessions | Interactive Login | +| Capabilities | Api Token | OAuth2 Sessions | Interactive Login | |-----------------|------------------|------------------------------|---------------------| -| OAuth2 | Yes | Via Client Credentials Grant | No | +| OAuth2 | No | Via Client Credentials Grant | No | | Application | Yes | No | No | | Service Account | Yes (rw capable) | Yes (via session grant (TBD) | Yes (to be removed) | | Break Glass | No | No | Yes | @@ -106,11 +109,10 @@ PROS: * Grants some new abilities within limits to other roles * While not as locked down as separate concern proposal, still minimises the risk of compromise of an SA - CONS: * Requires admins to have multiple accounts in some contexts (as above). -* Auditing requires knowledge of what each roles capabilities are +* Auditing requires knowledge of what each roles capabilities are, and what the capabilities do From d89fad3f4207ca524418bf43265454f952aa3dd5 Mon Sep 17 00:00:00 2001 From: William Brown <william@blackhats.net.au> Date: Sat, 29 Mar 2025 15:50:02 +1000 Subject: [PATCH 3/4] Update --- .../developers/designs/service_accounts.md | 70 +++++++++++++++---- 1 file changed, 55 insertions(+), 15 deletions(-) diff --git a/book/src/developers/designs/service_accounts.md b/book/src/developers/designs/service_accounts.md index 7935dff6d..9d36bed5a 100644 --- a/book/src/developers/designs/service_accounts.md +++ b/book/src/developers/designs/service_accounts.md @@ -21,14 +21,6 @@ authenticate to clients, which means they need to maintain credentials. This is but there are still some ideas in these docs worth knowing about and considering like group managed service accounts (gMSA). -## High Level Suggestions - -There are the ideas today that I have - there may be others! - -* Service Accounts can have attached roles. -* Keep concerns separate. -* Bit of A, bit of B, cleanup. - ## Current state of affairs We have: @@ -41,7 +33,58 @@ We have: From this we can see that we have some separation, but also some cross over of functionality. break glass isn't delegated, but service account is, OAuth2 isn't an SA, but Applications are. -## Attach roles to service accounts. +## Capabilities + +In order to properly handle this, we don't want to grant unbounded abilities to types, we don't +want to fully merge them, but we want to be able to mix-match what they require. + +This also makes it possible in the future that we can more easily assign (or remove) a capability +from an account type. + +To achieve this we should introduce the idea of capabilities - capabilities can act via schema +classes, and we can extend the schema such that only the parent class needs to know that the +capabilities class is required. + +This allows us to nominate more carefully what each role type can or can't do, and keeps things + +| Capabilities | Api Token | OAuth2 Sessions | Interactive Login | +|-----------------|------------------|------------------------------|---------------------| +| OAuth2 | No | Via Client Credentials Grant | No | +| Application | Yes (ro) | No | No | +| Service Account | Yes (rw capable) | Yes (via session grant (TBD) | Yes (to be removed) | +| Machine Account | Yes (ro) | No | No | +| Break Glass | No | No | Yes | +| Person | No | Yes | Yes | + +A key requirement of this is that we want each role to have a defined intent - it shouldn't be +the everything role, it still needs to be focused and administered in it's own right. + +| | Intent | +|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| OAuth2 | An OAuth2 client (external server/service) that is treating Kani as the IDP it trusts to validate user authorisation to it's resources. | +| Application | An LDAP application password context, allowing per-user/per-device/per-application passwords to validated, as well as defining group based authorisation of whom may use this application | +| Service Account | An account that belongs to a process or automation that needs to read from or write to Kanidm, or a Kanidm related service. | +| Machine Account | A domain joined machine that is reads user posix or login information. May be used to configure machine service accounts in future. | +| Break Glass | An emergency access account used in disaster recovery. | +| Person | A humans owned account that needs to authenticate day to day, and self manage their own credentials. A person may need to manage other accounts and resource types | + +This has the benefit that it makes it easier to assign the permissions via ACP (since we can filter +on the Target class *and* capability type). + +### Example + +An Email service has an SMTP gateway and OAuth2 web ui. + +Although this is "the email service" it is made up of multiple parts that each have their own intents. + +The Webui has an Oauth2 client created to define the relationship of who may access the webui. + +An LDAP application is made to allow IMAP/SMTP processes to authenticate users with application passwords and +to read users PII via LDAP. + +## Below was the drafting process of some ideas + +### Attach roles to service accounts. In this approach we centre the service account, and allow optional extension of other concerns. This would make OAuth2 applications an extension of a service account. Similar Application as well. @@ -62,8 +105,9 @@ CONS: * May be confusing to administrators * More "inheritance" of schema classes, when we may want to try to simplify to single classes in line with SCIM. * Harder to audit capabilities +* The administration UI becomes a shitshow as the Service Account is now a kitchen sink. -## Separate Concerns +### Separate Concerns In this approach we split our concerns. This is similar to today, but taken a bit further. @@ -85,7 +129,7 @@ CONS: * More administrative overhead to manage the multiple accounts * Stacked applications will need mulitple configurations for a role - OAuth2, LDAP application, Service accounts for example in an email server with a WebUI. -## Bit of A, bit of B, cleanup +### Bit of A, bit of B, cleanup AKA Capabilities @@ -115,7 +159,3 @@ CONS: * Auditing requires knowledge of what each roles capabilities are, and what the capabilities do - - - - From 71039cf0698a29599d787ca3784943b2b90ee72d Mon Sep 17 00:00:00 2001 From: William Brown <william@blackhats.net.au> Date: Sat, 5 Apr 2025 14:00:56 +1000 Subject: [PATCH 4/4] Updahte --- .../src/developers/designs/service_accounts.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/book/src/developers/designs/service_accounts.md b/book/src/developers/designs/service_accounts.md index 9d36bed5a..cff4e40ba 100644 --- a/book/src/developers/designs/service_accounts.md +++ b/book/src/developers/designs/service_accounts.md @@ -25,7 +25,7 @@ service accounts (gMSA). We have: -* Break glass accounts are service accounts, may not have delegated management. +* Break glass accounts (`admin`/`idm_admin`) are service accounts, may not have delegated management. * OAuth2 is not a service account, supports delegated management. * Service accounts can be group or user managed. * Applications (To Be Introduced) is an extension of a Service account. @@ -45,7 +45,10 @@ To achieve this we should introduce the idea of capabilities - capabilities can classes, and we can extend the schema such that only the parent class needs to know that the capabilities class is required. -This allows us to nominate more carefully what each role type can or can't do, and keeps things +This allows us to nominate more carefully what each role type can or can't do. More importantly +within the server, we don't have to hardcode that "service accounts and applications" can use +api tokens vs every other capability type. We only need look for the capability on the entry. + | Capabilities | Api Token | OAuth2 Sessions | Interactive Login | |-----------------|------------------|------------------------------|---------------------| @@ -62,7 +65,7 @@ the everything role, it still needs to be focused and administered in it's own r | | Intent | |-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | OAuth2 | An OAuth2 client (external server/service) that is treating Kani as the IDP it trusts to validate user authorisation to it's resources. | -| Application | An LDAP application password context, allowing per-user/per-device/per-application passwords to validated, as well as defining group based authorisation of whom may use this application | +| Application | An application password context, allowing per-user/per-device/per-application passwords to validated, as well as defining group based authorisation of whom may use this application | | Service Account | An account that belongs to a process or automation that needs to read from or write to Kanidm, or a Kanidm related service. | | Machine Account | A domain joined machine that is reads user posix or login information. May be used to configure machine service accounts in future. | | Break Glass | An emergency access account used in disaster recovery. | @@ -87,11 +90,18 @@ to read users PII via LDAP. ### Attach roles to service accounts. In this approach we centre the service account, and allow optional extension of other concerns. This -would make OAuth2 applications an extension of a service account. Similar Application as well. +would make OAuth2 applications an extension of a service account. Similar application would become +an extension of service account. This would mean that we create a service account first, then need a way to extend it with the application or oauth2 types. +This would mean that a service account could potentially be everything - an application password +provider, an oauth2 client, and more. This would make the administration very difficult and deeply +nested on the single service account type, and could encourage bad administration practices as +admins can "shovel in" every possible role to single accounts. + + PROS: * OAuth2 applications get the ability to have api tokens to kani for other functionality