mirror of
https://github.com/kanidm/kanidm.git
synced 2025-02-23 20:47:01 +01:00
Add access rework doc, add domain doc (#1026)
This commit is contained in:
Firstyear
GitHub
parent
ecfb25c0e5
commit
bba5bd1a42
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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 <container name>
|
||||
docker run --rm -i -t -v kanidmd:/data \
|
||||
kanidm/server:latest /sbin/kanidmd configtest -c /data/server.toml
|
||||
docker start <container name>
|
||||
|
||||
# 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
|
||||
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 <container name>
|
||||
|
||||
That's it!
|
||||
|
||||
## Method 2
|
||||
## Method 3 - Manual Database Copy
|
||||
|
||||
This is a simple backup of the data volume.
|
||||
|
||||
|
|
@ -45,32 +67,41 @@ This is a simple backup of the data volume.
|
|||
# Backup your docker's volume folder
|
||||
docker start <container name>
|
||||
|
||||
## 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 <container name>
|
||||
|
||||
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 <container name>
|
||||
|
||||
|
||||
# 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
|
||||
|
|
@ -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 <container name>
|
||||
|
||||
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 <container name>
|
||||
|
||||
# Raw actions
|
||||
|
||||
The server has a low-level stateful API you can use for more complex or advanced tasks on large numbers
|
||||
|
|
|
|||
98
kanidm_book/src/choosing_a_domain_name.md
Normal file
98
kanidm_book/src/choosing_a_domain_name.md
Normal file
|
|
@ -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.
|
||||
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
|
||||
33
kanidm_book/src/glossary.md
Normal file
33
kanidm_book/src/glossary.md
Normal file
|
|
@ -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.
|
||||
Loading…
Reference in a new issue