diff --git a/book/src/developers/designs/service_accounts.md b/book/src/developers/designs/service_accounts.md new file mode 100644 index 000000000..cff4e40ba --- /dev/null +++ b/book/src/developers/designs/service_accounts.md @@ -0,0 +1,171 @@ +# 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). + +## Current state of affairs + +We have: + +* 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. + +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. + +## 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. 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 | +|-----------------|------------------|------------------------------|---------------------| +| 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 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 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 +* 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 +* The administration UI becomes a shitshow as the Service Account is now a kitchen sink. + +### 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 + +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. 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. + +| Capabilities | Api Token | OAuth2 Sessions | Interactive Login | +|-----------------|------------------|------------------------------|---------------------| +| 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 | + +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, and what the capabilities do + +