From bba5bd1a429700a18a4fd47c86a155f32537ac06 Mon Sep 17 00:00:00 2001 From: Firstyear Date: Fri, 9 Sep 2022 20:54:55 +1000 Subject: [PATCH] Add access rework doc, add domain doc (#1026) --- kanidm_book/src/SUMMARY.md | 5 +- kanidm_book/src/administrivia.md | 117 ++++++----- kanidm_book/src/choosing_a_domain_name.md | 98 +++++++++ .../designs/access_profiles_rework_2022.md | 192 ++++++++++++++++++ kanidm_book/src/glossary.md | 33 +++ 5 files changed, 384 insertions(+), 61 deletions(-) create mode 100644 kanidm_book/src/choosing_a_domain_name.md create mode 100644 kanidm_book/src/developers/designs/access_profiles_rework_2022.md create mode 100644 kanidm_book/src/glossary.md diff --git a/kanidm_book/src/SUMMARY.md b/kanidm_book/src/SUMMARY.md index 0e70a77fc..fcaff9caa 100644 --- a/kanidm_book/src/SUMMARY.md +++ b/kanidm_book/src/SUMMARY.md @@ -1,7 +1,9 @@ # Kanidm - [Introduction to Kanidm](intro.md) +- [Glossary of Technical Terms](glossary.md) - [Installing the Server](installing_the_server.md) + - [Choosing a Domain Name](choosing_a_domain_name.md) - [Server Configuration](server_configuration.md) - [Security Hardening](security_hardening.md) - [Client Tools](client_tools.md) @@ -30,7 +32,8 @@ - [Developer Guide](DEVELOPER_README.md) - [Design Documents]() - - [Access Profiles](developers/designs/access_profiles_and_security.md) + - [Access Profiles 2022](developers/designs/access_profiles_rework_2022.md) + - [Access Profiles Original](developers/designs/access_profiles_and_security.md) - [REST Interface](developers/designs/rest_interface.md) - [Python Module](developers/python.md) - [RADIUS Integration](developers/radius.md) diff --git a/kanidm_book/src/administrivia.md b/kanidm_book/src/administrivia.md index 65042a655..04f287d71 100644 --- a/kanidm_book/src/administrivia.md +++ b/kanidm_book/src/administrivia.md @@ -5,16 +5,40 @@ a Kanidm server, such as making backups and restoring from backups, testing server configuration, reindexing, verifying data consistency, and renaming your domain. +# Configuration Test + +{{#template + templates/kani-warning.md + imagepath=images + title=Take note! + text=While this is a configuration file test, it still needs to open the database so that it can check a number of internal values are consistent with the configuration. As a result, this requires the instance under config test to be stopped! +}} + +You can test that your configuration is correct, and the server should correctly start. + + docker stop + docker run --rm -i -t -v kanidmd:/data \ + kanidm/server:latest /sbin/kanidmd configtest -c /data/server.toml + docker start + # Backup and Restore -With any Identity Management (IDM) software, it's important you have the capability to restore in -case of a disaster - be that physical damage or a mistake. Kanidm supports backup +With any Identity Management (IDM) software, it's important you have the capability to restore in +case of a disaster - be that physical damage or a mistake. Kanidm supports backup and restore of the database with three methods. -## Method 1 (Preferred) +## Method 1 - Automatic Backup -Method 1 involves taking a backup of the database entry content, which is then re-indexed on restore. -This is the preferred method. +Automatic backups can be generated online by a `kanidmd server` instance +by including the `[online_backup]` section in the `server.toml`. +This allows you to run regular backups, defined by a cron schedule, and maintain +the number of backup versions to keep. An example is located in +[examples/server.toml](https://github.com/kanidm/kanidm/blob/master/examples/server.toml). + +## Method 2 - Manual Backup + +This method uses the same process as the automatic process, but is manually invoked. This can +be useful for pre-upgrade backups To take the backup (assuming our docker environment) you first need to stop the instance: @@ -35,9 +59,7 @@ To restore from the backup: /backup/kanidm.backup.json docker start -That's it! - -## Method 2 +## Method 3 - Manual Database Copy This is a simple backup of the data volume. @@ -45,39 +67,48 @@ This is a simple backup of the data volume. # Backup your docker's volume folder docker start -## Method 3 +# Rename the domain -Automatic backups can be generated online by a `kanidmd server` instance -by including the `[online_backup]` section in the `server.toml`. -This allows you to run regular backups, defined by a cron schedule, and maintain -the number of backup versions to keep. An example is located in -[examples/server.toml](https://github.com/kanidm/kanidm/blob/master/examples/server.toml). +There are some cases where you may need to rename the domain. You should have configured +this initially in the setup, however you may have a situation where a business is changing +name, merging, or other needs which may prompt this needing to be changed. -# Configuration Test +> **WARNING:** This WILL break ALL u2f/webauthn tokens that have been enrolled, which MAY cause +> accounts to be locked out and unrecoverable until further action is taken. DO NOT CHANGE +> the domain name unless REQUIRED and have a plan on how to manage these issues. -{{#template - templates/kani-warning.md - imagepath=images - title=Take note! - text=While this is a configuration file test, it still needs to open the database so that it can check a number of internal values are consistent with the configuration. As a result, this requires the instance under config test to be stopped! -}} +> **WARNING:** This operation can take an extensive amount of time as ALL accounts and groups +> in the domain MUST have their Security Principal Names (SPNs) regenerated. This WILL also cause +> a large delay in replication once the system is restarted. -You can test that your configuration is correct, and the server should correctly start. +You should make a backup before proceeding with this operation. + +When you have a created a migration plan and strategy on handling the invalidation of webauthn, +you can then rename the domain. + +First, stop the instance. docker stop + +Second, change `domain` and `origin` in `server.toml`. + +Third, trigger the database domain rename process. + docker run --rm -i -t -v kanidmd:/data \ - kanidm/server:latest /sbin/kanidmd configtest -c /data/server.toml + kanidm/server:latest /sbin/kanidmd domain rename -c /data/server.toml + +Finally, you can now start your instance again. + docker start - -# Reindexing after schema extension +# Reindexing In some (rare) cases you may need to reindex. Please note the server will sometimes reindex on startup as a result of the project changing its internal schema definitions. This is normal and expected - you may never need to start a reindex yourself as a result! -You'll likely notice a need to reindex if you add indexes to schema and you see a message in +You'll likely notice a need to reindex if you add indexes to schema and you see a message in your logs such as: Index EQUALITY name not found @@ -131,40 +162,6 @@ You can run a verification with: If you have errors, please contact the project to help support you to resolve these. -# Rename the domain - -There are some cases where you may need to rename the domain. You should have configured -this initially in the setup, however you may have a situation where a business is changing -name, merging, or other needs which may prompt this needing to be changed. - -> **WARNING:** This WILL break ALL u2f/webauthn tokens that have been enrolled, which MAY cause -> accounts to be locked out and unrecoverable until further action is taken. DO NOT CHANGE -> the domain name unless REQUIRED and have a plan on how to manage these issues. - -> **WARNING:** This operation can take an extensive amount of time as ALL accounts and groups -> in the domain MUST have their Security Principal Names (SPNs) regenerated. This WILL also cause -> a large delay in replication once the system is restarted. - -You should make a backup before proceeding with this operation. - -When you have a created a migration plan and strategy on handling the invalidation of webauthn, -you can then rename the domain. - -First, stop the instance. - - docker stop - -Second, change `domain` and `origin` in `server.toml`. - -Third, trigger the database domain rename process. - - docker run --rm -i -t -v kanidmd:/data \ - kanidm/server:latest /sbin/kanidmd domain rename -c /data/server.toml - -Finally, you can now start your instance again. - - docker start - # Raw actions The server has a low-level stateful API you can use for more complex or advanced tasks on large numbers diff --git a/kanidm_book/src/choosing_a_domain_name.md b/kanidm_book/src/choosing_a_domain_name.md new file mode 100644 index 000000000..276f9f06e --- /dev/null +++ b/kanidm_book/src/choosing_a_domain_name.md @@ -0,0 +1,98 @@ +# Choosing a Domain Name + +Through out this book, Kanidm will make reference to a "domain name". This is your +chosen DNS domain name that you intend to use for Kanidm. Choosing this domain name however +is not simple as there are a number of considerations you need to be careful of. + +{{#template + templates/kani-warning.md + imagepath=images + title=Take note! + text=Incorrect choice of the domain name *may* have security impacts on your Kanidm instance, not + limited to credential phishing, theft, session leaks and more. It is critical you follow this advice + in this chapter! +}} + +## Considerations + +### Domain Ownership + +It is recommended you use a domain name within a domain that you own. While many examples list +`example.com` throughout this book, it is not recommended to use this outside of testing. Another +example of risky domain to use is `local`. While it seems appealing to use these, because you do not +have unique ownership of these domains, if you move your machine to a foreign network, it is possible +you may leak credentials or other cookies to these domains. TLS in a majority of cases can and will +protect you from such leaks however, but it should not always be relied upon as a sole line of defence. + +Failure to use a unique domain you own, may allow DNS hijacking or other credential leaks when you are *not* on +your own network. + +### Subdomains + +Due to how web browsers and webauthn work, any matching domain name or subdomain of an effective domain +may have access to cookies within a browser session. An example is that `host.a.example.com` has access +to cookies from `a.example.com` and `example.com`. + +For this reason your kanidm host (or hosts) should be on a unique subdomain, with no other services +registered under that subdomain. For example, consider `idm.example.com` as a subdomain for exclusive +use of kanidm. This is *inverse* to Active Directory which often has it's domain name selected to be +the domain (`example.com`). + +Failure to use a unique subdomain may allow cookies to leak to other entities within your domain, and +may allow webauthn to be used on entities you did not intend for which may or may not lead to some phishing +scenarioes. + +## Examples + +### Good Example + +Consider we own `kanidm.com`. If we were to run geographical instances, and have testing environments +the following domain and hostnames could be used. + +*production* + +* origin: `https://idm.kanidm.com` +* domain name: `idm.kanidm.com` +* host names: `australia.idm.kanidm.com`, `newzealand.idm.kanidm.com` + +This allows us to have named geographical instances such as `https://australia.idm.kanidm.com` which +still works with webauthn and cookies which are transferable between instances. + +It is critical no other hosts are registered under this domain name. + +*testing* + +* origin: `https://idm.dev.kanidm.com` +* domain name: `idm.dev.kanidm.com` +* host names: `australia.idm.dev.kanidm.com`, `newzealand.idm.dev.kanidm.com` + +Note that due to the name being `idm.dev.kanidm.com` vs `idm.kanidm.com`, the testing instance is not +a subdomain of production, meaning the cookies and webauthn tokens can NOT be transferred between +them. This provides proper isolation between the instances. + +### Bad Examples + +`idm.local` - This is a bad example as `.local` is an mDNS domain name suffix which means that client +machines if they visit another network *may* try to contact `idm.local` believing they are on their +usual network. If TLS verification were disabled, this would allow leaking of credentials. + +`kanidm.com` - This is bad because the use of the top level domain means that any subdomain can +access the cookies issued by `kanidm.com`, effectively leaking them to all other hosts. + +Second instance overlap: + +*production* + +* origin: `https://idm.kanidm.com` +* domain name: `idm.kanidm.com` + +*testing* + +* origin: `https://dev.idm.kanidm.com` +* domain name: `dev.idm.kanidm.com` + +While the production instance has a valid and well defined subdomain that doesn't conflict, because the +dev instance is a subdomain of production, it allows production cookies to leak to dev. Dev instances +may have weaker security controls in some cases which can then allow compromise of the production instance. + + diff --git a/kanidm_book/src/developers/designs/access_profiles_rework_2022.md b/kanidm_book/src/developers/designs/access_profiles_rework_2022.md new file mode 100644 index 000000000..5628c7411 --- /dev/null +++ b/kanidm_book/src/developers/designs/access_profiles_rework_2022.md @@ -0,0 +1,192 @@ + +# Access Profiles Rework 2022 + +Access controls are critical for a project like Kanidm to determine who can access what on other +entries. Our access controls have to be dynamic and flexible as administrators will want to define +their own access controls. In almost every call in the server, they are consulted to determine if +the action can be carried out. We also supply default access controls so that out of the box we are +a complete and useful IDM. + +The original design of the access control system was intended to satisfy our need for flexibility, +but we have begun to discover a number of limitations. The design incorporating filter queries makes +them hard to administer as we have not often publicly talked about the filter language and how it +internally works. Because of their use of filters it is hard to see on an entry "what" access controls +will apply to entries, making it hard to audit without actually calling the ACP subsystem. Currently +the access control system has a large impact on performance, accounting for nearly 35% of the time taken +in a search operation. + +Additionally, the default access controls that we supply have started to run into limits and rough cases +due to changes as we have improved features. Some of this was due to limited design with user cases +in mind during development. + +To resolve this a number of coordinating features need implementation to improve this situation. These +features will be documented *first*, and the use cases *second* with each use case linking to the +features that satisfy it. + +## Required Features to Satisfy + +### Refactor of default access controls + +The current default privileges will need to be refactored to improve seperation of privilege +and improved delegation of finer access rights. + +### Access profiles target specifiers instead of filters + +Access profiles should target a list of groups for who the access profile applies to, and who recieves +the access it is granting. + +Alternately an access profile could target "self" so that self-update rules can still be expressed. + +An access profile could target an oauth2 definition for the purpose of allowing reads to members +of a set of scopes that can access the service. + +The access profile receiver would be group based only. This allows specifying that "X group of members +can write self" meaning that any member of that group can write to themself and only themself. + +In the future we could also create different target/receiver specifiers to allow other extended management +and delegation scenarioes. This improves the situation making things more flexible from the current +filter system. It also may allow filters to be simplified to remove the SELF uuid resolve step in some cases. + +### Filter based groups + +These are groups who's members are dynamicly allocated based on a filter query. This allows a similar +level of dynamic group management as we have currently with access profiles, but with the additional +ability for them to be used outside of the access control context. This is the "bridge" allowing us to +move from filter based access controls to "group" targetted. + +A risk of filter based groups is "infinite churn" because of recursion. This can occur if you +had a rule such a "and not memberof = self" on a dynamic group. Because of this, filters on +dynamic groups may not use "memberof" unless they are internally provided by the kanidm project so +that we can vet these rules as correct and without creating infinite recursion scenarioes. + +### Access rules extracted to ACI entries on targets + +The access control profiles are an excellent way to administer access where you can specific whom +has access to what, but it makes it harder for the reverse query which is "who has access to this +specific entity". Since this is needed for both search and auditing, by specifying our access profiles +in the current manner, but using them to generate ACE rules on the target entry will allow the search +and audit paths to answer the question of "who has access to this entity" much faster. + +### Sudo Mode + +A flag should exist on a session defining "sudo" mode which requires a special account policy membership +OR a re-authentication to enable. This sudo flag is a time window on a session token which can +allow/disallow certain behaviours. It would be necessary for all write paths to have access to this +value. + +### Account Policy + +Account policy defines rules on accounts and what they can or can't do with regard to properties and +authentication. This is required for sudo mode so that a group of accounts can be "always in sudo" +mode and this enforces rules on session expiry. + +## Access Control Use Cases + +### Default Roles / Seperation of Privilege + +By default we attempt to seperate privileges so that "no single account" has complete authority +over the system. + +Satisfied by: +* Refactor of default access controls +* Filter based groups +* Sudo Mode + +#### System Admin + +This role, also called "admins" is responsible to manage Kanidm as a service. It does NOT manage +users or accounts. + +The "admins" role is responsible to manage: + +* The name of the domain +* Configuration of the servers and replication +* Management of external integrations (oauth2) + +#### Service Account Admin + +The role would be called "sa\_admins" and would be responsible for top level management of service +accounts, and delegating authority for service account administration to managing users. + +* Create service accounts +* Delegate service account management to owners groups +* Migrate service accounts to persons + +The service account admin is capable of migrating service accounts to persons as it is "yielding" +control of the entity, rather than an idm admin "taking" the entity which may have security impacts. + +#### Service Desk + +This role manages a subset of persons. The helpdesk roles are precluded from modification of +"higher privilege" roles like service account, identity and system admins. This is due to potential +privilege escalation attacks. + +* Can create credential reset links +* Can lock and unlock accounts and their expiry. + +#### Idm Admin + +This role manages identities, or more specifically person accounts. In addition in is a +"high privilege" service desk role and can manage high privilege users as well. + +* Create persons +* Modify and manage persons +* All roles of service desk for all persons + +### Self Write / Write Privilege + +Currently write privileges are always available to any account post-authentication. Writes should +only be available after an extra "challenge" or "sudo" style extra auth, and only have a limited +time window of usage. The write window can be extended during the session. This allows extremely +long lived sessions contrast to the current short session life. It also makes it safer to provide +higher levels of privilege to persons since these rights are behind a re-authentication event. + +Some accounts should always be considered able to write, and these accounts should have limited +authentication sessions as a result of this. + +Satisfied by: + +* Access profiles target specifiers instead of filters +* Sudo Mode + +### Oauth2 Service Read (Nice to Have) + +For ux/ui integration, being able to list oauth2 applications that are accessible to the user +would be a good feature. To limit "who" can see the oauth2 applications that an account can access +a way to "allow read" but by proxy of the related users of the oauth2 service. This will require +access controls to be able to interept the oauth2 config and provide rights based on that. + +Satisfied by: + +* Access profiles target specifiers instead of filters + +### Administration + +Access controls should be easier to manage and administer, and should be group based rather than +filter based. This will make it easier for administrators to create and define their own access +rules. + +* Refactor of default access controls +* Access profiles target specifiers instead of filters +* Filter based groups + +### Service Account Access + +Service accounts should be able to be "delegated" administration, where a group of users can manage +a service account. This should not require administrators to create unique access controls for each +service account, but a method to allow mapping of the service account to "who manages it". + +* Sudo Mode +* Account Policy +* Access profiles target specifiers instead of filters +* Refactor of default access controls + +### Auditing of Access + +It should be easier to audit whom has access to what by inspecting the entry to view what can access +it. + +* Access rules extracted to ACI entries on targets +* Access profiles target specifiers instead of filters + + diff --git a/kanidm_book/src/glossary.md b/kanidm_book/src/glossary.md new file mode 100644 index 000000000..3bfdea4d6 --- /dev/null +++ b/kanidm_book/src/glossary.md @@ -0,0 +1,33 @@ +# Glossary + +This is a glossary of terms used through out this book. While we make every effort to +explains terms and acronyms when they are used, this may be a useful reference if something +feels unknown to you. + +## Domain Names + +* domain - This is the domain you "own". It is the highest level entity. An example would be `example.com` (since you do not own `.com`). +* subdomain - A subdomain is a domain name space under the domain. A subdomains of `example.com` are `a.example.com` and `b.example.com`. Each subdomain can have further subdomains. +* domain name - This is any named entity within your domain or its subdomains. This is the umbrella term, referring to all entities in the domain. `example.com`, `a.example.com`, `host.example.com` are all valid domain names with the domain `example.com`. +* origin - An origin defines a URL with a protocol scheme, optional port number and domain name components. An example is `https://host.example.com` +* effective domain - This is the extracted domain name from an origin excluding port and scheme. + +## Accounts + +* trust - A trust is when two Kanidm domains have a relationship to each other where accounts can be used between the domains. The domains retain their administration boundaries, but allow cross authentication. +* replication - This is the process where two or more Kanidm servers in a domain can synchronise their database content. +* UAT - User Authentication Token. This is a token issue by Kanidm to an account after it has authenticated. +* SPN - Security Principal Name. This is a name of an account comprising it's name and domain name. This allows distinction between accounts with identical names over a trust boundary + +## Internals + +* entity, object, entry - Any item in the database. Generally these terms are interchangeable, but internally they are referred to as Entry. +* account - An entry that may authenticate to the server, generally allowing extended permissions and actions to be undertaken. + +### Access Control + +* privilege - An expression of what actions an account may perform if granted +* target - The entries that will be affected by a privilege +* receiver - The entries that will be able to use a privilege +* acp - an Access Control Profile which defines a set of privileges that are granted to receivers to affect target entries. +* role - A term used to express a group that is the receiver of an access control profile allowing it's members to affect the target entries.