mirror of
https://github.com/kanidm/kanidm.git
synced 2025-02-23 12:37:00 +01:00
Add upgrade process, improve developer readme (#2635)
* Add upgrade process, improve developer readme * Rearrange some bits.
This commit is contained in:
Firstyear
GitHub
parent
4dc38e56c3
commit
e8d7010b4b
10
README.md
10
README.md
|
|
@ -24,7 +24,7 @@ If you want to host your own authentication service, then Kanidm is for you!
|
|||
Kanidm supports:
|
||||
|
||||
- Passkeys (webauthn) for secure cryptographic authentication
|
||||
- Attested Passkeys for high assurance environments
|
||||
- Attested Passkeys for high security environments
|
||||
- Oauth2/OIDC Authentication provider for web SSO
|
||||
- Application Portal allowing easy access to linked applications
|
||||
- Linux/Unix integration with TPM secured offline authentication
|
||||
|
|
@ -44,8 +44,8 @@ If you want to read more about what Kanidm can do, you should read our documenta
|
|||
- [Kanidm book (Latest stable)](https://kanidm.github.io/kanidm/stable/)
|
||||
|
||||
We also have a set of
|
||||
[support guidelines](https://github.com/kanidm/kanidm/blob/master/project_docs/RELEASE_AND_SUPPORT.md)
|
||||
for what the project team will support
|
||||
[support guidelines](https://github.com/kanidm/kanidm/blob/master/book/src/support.md) for what the
|
||||
project team will support
|
||||
|
||||
## Code of Conduct / Ethics
|
||||
|
||||
|
|
@ -54,7 +54,7 @@ All interactions with the project are covered by our [code of conduct].
|
|||
When we develop features we follow our projects guidelines on [rights and ethics]
|
||||
|
||||
[code of conduct]: https://github.com/kanidm/kanidm/blob/master/CODE_OF_CONDUCT.md
|
||||
[rights and ethics]: https://github.com/kanidm/kanidm/blob/master/project_docs/ethics/README.md
|
||||
[rights and ethics]: https://github.com/kanidm/kanidm/blob/master/book/src/developers/ethics.md
|
||||
|
||||
## Getting in Contact / Questions
|
||||
|
||||
|
|
@ -146,4 +146,4 @@ When developing the server you should refer to the latest commit documentation i
|
|||
|
||||
- [Kanidm book (Latest commit)](https://kanidm.github.io/kanidm/master/)
|
||||
|
||||
[guide for developers]: https://kanidm.github.io/kanidm/master/DEVELOPER_README.html
|
||||
[guide for developers]: https://kanidm.github.io/kanidm/stable/developers/readme.html
|
||||
|
|
|
|||
|
|
@ -1,10 +1,12 @@
|
|||
# Kanidm
|
||||
|
||||
- [Introduction to Kanidm](intro.md)
|
||||
- [Supported Features](features.md)
|
||||
|
||||
- [Evaluation Quickstart](quickstart.md)
|
||||
|
||||
- [Supported Features](features.md)
|
||||
- [Project Support](support.md)
|
||||
|
||||
- [Installing the Server](installing_the_server.md)
|
||||
- [Choosing a Domain Name](choosing_a_domain_name.md)
|
||||
- [Preparing for your Deployment](prepare_the_server.md)
|
||||
|
|
@ -65,7 +67,8 @@
|
|||
|
||||
# For Developers
|
||||
|
||||
- [Developer Guide](DEVELOPER_README.md)
|
||||
- [Developer Guide](developers/readme.md)
|
||||
- [Developer Ethics](developers/ethics.md)
|
||||
- [Frequently Asked Questions](developers/faq.md)
|
||||
- [Design Documents]()
|
||||
- [Access Profiles 2022](developers/designs/access_profiles_rework_2022.md)
|
||||
|
|
@ -81,5 +84,6 @@
|
|||
- [REST Interface](developers/designs/rest_interface.md)
|
||||
- [Python Module](developers/python.md)
|
||||
- [RADIUS Integration](developers/radius.md)
|
||||
- [Packaging](packaging.md)
|
||||
- [Debian/Ubuntu](packaging_debs.md)
|
||||
- [Release Checklist](developers/release_checklist.md)
|
||||
- [Packaging](developers/packaging.md)
|
||||
- [Debian/Ubuntu](developers/packaging_debs.md)
|
||||
|
|
|
|||
|
|
@ -56,12 +56,13 @@ continual communication.
|
|||
|
||||
To do this, we use the last 24 bits of the account or group's UUID to generate the GID number. We
|
||||
can only use the UID range `1879048192` (`0x70000000`) to `2147483647` (`0x7fffffff`) due to
|
||||
limitations of the Linux kernel and [systemd reserving other uids in the range](http://systemd.io/UIDS-GIDS/) for its exclusive
|
||||
use.
|
||||
limitations of the Linux kernel and
|
||||
[systemd reserving other uids in the range](http://systemd.io/UIDS-GIDS/) for its exclusive use.
|
||||
|
||||
A valid concern is the possibility of duplication in the lower 24 bits. Given the [birthday problem](https://en.wikipedia.org/wiki/Birthday_problem),
|
||||
if you have ~7700 groups and accounts, you have a 50% chance of duplication. With ~5000 you have a
|
||||
25% chance, ~930 you have a 1% chance and with 290 you have a 0.1% chance.
|
||||
A valid concern is the possibility of duplication in the lower 24 bits. Given the
|
||||
[birthday problem](https://en.wikipedia.org/wiki/Birthday_problem), if you have ~7700 groups and
|
||||
accounts, you have a 50% chance of duplication. With ~5000 you have a 25% chance, ~930 you have a 1%
|
||||
chance and with 290 you have a 0.1% chance.
|
||||
|
||||
We advise that if you have a site with greater than approximately 2,000 users you should use an
|
||||
external system to allocate GID numbers serially or consistently to avoid potential duplication
|
||||
|
|
|
|||
65
book/src/developers/ethics.md
Normal file
65
book/src/developers/ethics.md
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
# Statement of ethics and rights
|
||||
|
||||
Kanidm is a project that will store, process and present people's personal data. This means we have
|
||||
a responsibility to respect the data of all people who could be using our system - many who interact
|
||||
indirectly or do not have a choice in this platform.
|
||||
|
||||
## Rights of people
|
||||
|
||||
All people using this software should expect to have the right to:
|
||||
|
||||
- Self control over their data, including the ability to alter or delete at any time.
|
||||
- Free from harmful discrimination of any kind
|
||||
- Informed consent over control and privacy of their data, including access and understand data held
|
||||
and shared on their behalf
|
||||
- To be able to use and access this software regardless of ability, culture or language.
|
||||
|
||||
## Examples of situations for consideration
|
||||
|
||||
### Ability to be forgotten
|
||||
|
||||
#### Deletion is delete not flagging
|
||||
|
||||
When an account is deleted it must be truly deleted, not just flagged for future delete. Note that
|
||||
some functionality like the recycle bin, we must keep the account details, but a recycle bin purge
|
||||
does truly delete the account.
|
||||
|
||||
### Self determination and autonomy
|
||||
|
||||
#### Self name change
|
||||
|
||||
People should be able to change their own name at anytime. Consider divorce, leaving abusive
|
||||
partners or other personal decisions around why a name change is relevant.
|
||||
|
||||
This is why names are self-service writeable at any time.
|
||||
|
||||
### Free from harmful discrimination of any kind
|
||||
|
||||
#### Cultural and Social awareness of name formats
|
||||
|
||||
All name fields should be case sensitive utf8 with no max or min length limit. This is because names
|
||||
can take many forms such as.
|
||||
|
||||
- firstname middlename lastname
|
||||
- firstname lastname
|
||||
- firstname firstname lastname
|
||||
- firstname lastname lastname
|
||||
- firstname
|
||||
- lastname firstname
|
||||
|
||||
And many many more that are not listed here. This is why our names are displayName as a freetext
|
||||
UTF8 field, with case sensitivity and no limits.
|
||||
|
||||
### Informed consent and Privacy of their data
|
||||
|
||||
#### Access to legalName field
|
||||
|
||||
legalName should only be on a "need to know" basis, and only collected if required. This is to help
|
||||
people who may be stalked or harassed, or otherwise conscious of their privacy.
|
||||
|
||||
### To use and access this software regardless of ability
|
||||
|
||||
## Questions?
|
||||
|
||||
Please raise an issue with the project - we want to know if we have missed anything or can improve
|
||||
what we are doing.
|
||||
|
|
@ -1,5 +1,85 @@
|
|||
# Getting Started (for Developers)
|
||||
|
||||
## Development Principles
|
||||
|
||||
As a piece of software that stores the identities of people, the project becomes bound to social and
|
||||
political matters. The decisions we make have consequences on many people - many who never have the
|
||||
chance to choose what software is used to store their identities (think employees in a business, or
|
||||
the users of a website).
|
||||
|
||||
This means we have a responsibility to not only be aware of our impact on our direct users
|
||||
(developers, system administrators, dev ops, security and more) but also the impact on indirect
|
||||
consumers - many of who are unlikely to be in a position to contact us to ask for changes and help.
|
||||
|
||||
### Ethics / Rights
|
||||
|
||||
If you have not already, please see our documentation on [rights and ethics](ethics.md)
|
||||
|
||||
|
||||
### Humans First
|
||||
|
||||
We must at all times make decisions that put humans first. We must respect all cultures, languages,
|
||||
and identities and how they are represented.
|
||||
|
||||
We will never put a burden on the user to correct for poor designs on our part.
|
||||
|
||||
This may mean we make technical choices that are difficult or more complex, or different to "how
|
||||
things have always been done". But we do this to ensure that all people can have their identities
|
||||
stored how they choose.
|
||||
|
||||
For example, any user may change their name, display name and legal name at any time. Many
|
||||
applications will break as they primary key from name when this occurs. But this is the fault of the
|
||||
application. Name changes must be allowed. Our job as technical experts is to allow that to happen.
|
||||
|
||||
### Correct and Simple
|
||||
|
||||
As a piece of security sensitive software we must always put correctness first. All code must have
|
||||
tests. All developers must be able to run all tests on their machine and environment of choice.
|
||||
|
||||
This means that the following must always work:
|
||||
|
||||
```bash
|
||||
git clone ...
|
||||
cargo test
|
||||
```
|
||||
|
||||
If a test or change would require extra requirements or preconfiguration (such as setting up an
|
||||
external database or service), then we can no longer provide the above. Testing must be easy and
|
||||
accessible - otherwise people will not run the tests, leading to poor quality.
|
||||
|
||||
The project must be simple. Any one should be able to understand how it works and why those
|
||||
decisions were made.
|
||||
|
||||
### Hierachy of Controls
|
||||
|
||||
When a possible risk arises we should always consider the [hierachy of controls]. In descedending
|
||||
order of priority
|
||||
|
||||
- Elimination - eliminate the risk from existing
|
||||
- Substitution - replace the risk with something less dangerous
|
||||
- Engineering Controls - isolate the risk from causing harm
|
||||
- Administrative Controls - educate about the risk, add warnings
|
||||
- Personal Protection - document the risk
|
||||
|
||||
[hierachy of controls]: https://en.wikipedia.org/wiki/Hierarchy_of_hazard_controls
|
||||
|
||||
### Languages
|
||||
|
||||
The core server will (for now) always be written in Rust. This is due to the strong type guarantees
|
||||
it gives, and how that can help raise the quality of our project.
|
||||
|
||||
### Over-Configuration
|
||||
|
||||
Configuration will be allowed, but only if it does not impact the statements above. Having
|
||||
configuration is good, but allowing too much (i.e. a scripting engine for security rules) can give
|
||||
deployments the ability to violate human first principles, which reflects badly on us.
|
||||
|
||||
In addition every extra configuration item expands our testing matrix exponentially. We should
|
||||
optimally only offer one path that is correct for all users unless no other options are possible.
|
||||
|
||||
All configuration items, must be constrained to fit within our principles so that every Kanidm
|
||||
deployment, will aim to provide a positive experience to all people.
|
||||
|
||||
## Setup the Server
|
||||
|
||||
It's important before you start trying to write code and contribute that you understand what Kanidm
|
||||
|
|
@ -90,7 +170,7 @@ Tested with Ubuntu 20.04 and 22.04.
|
|||
|
||||
<!-- deno-fmt-ignore-start -->
|
||||
|
||||
{{#template templates/kani-warning.md
|
||||
{{#template ../templates/kani-warning.md
|
||||
imagepath=images
|
||||
title=NOTICE
|
||||
text=Our support for Windows is still in development, so you may encounter some compilation or build issues.
|
||||
|
|
@ -153,7 +233,7 @@ cargo test
|
|||
|
||||
<!-- deno-fmt-ignore-start -->
|
||||
|
||||
{{#template templates/kani-warning.md
|
||||
{{#template ../templates/kani-warning.md
|
||||
imagepath=images
|
||||
title=IMPORTANT
|
||||
text=Kanidm is unable to accept code that is generated by an AI for legal reasons. copilot and other tools that generate code in this way can not be used in Kanidm.
|
||||
|
|
@ -327,7 +407,7 @@ You may find it easier to modify `~/.config/kanidm` per the
|
|||
|
||||
<!-- deno-fmt-ignore-start -->
|
||||
|
||||
{{#template templates/kani-warning.md
|
||||
{{#template ../templates/kani-warning.md
|
||||
imagepath=images
|
||||
title=NOTICE
|
||||
text=It's not recommended to use these tools outside of extremely complex or advanced development requirements. These are a last resort!
|
||||
|
|
@ -1,5 +1,31 @@
|
|||
# Updating the Server
|
||||
|
||||
## General Update Notes
|
||||
|
||||
During some upgrades the Kanidm project must apply new constraints or limits on your data. If we are
|
||||
unable to migrate these without disruption, we rely on administrators to make informed choices
|
||||
before the upgrade can proceed.
|
||||
|
||||
When these are required, we will give you one release cycle ahead of time to make changes. To check
|
||||
for changes that will affect your instance you should run.
|
||||
|
||||
```bash
|
||||
kanidmd domain upgrade-check
|
||||
|
||||
# Running domain upgrade check ...
|
||||
# domain_name : localhost
|
||||
# domain_uuid : 7dcc7a71-b488-4e2c-ad4d-d89fc49678cb
|
||||
# ------------------------
|
||||
# upgrade_item : gidnumber range validity
|
||||
# status : PASS
|
||||
```
|
||||
|
||||
If _any_ task yields a `FAIL` then a future upgrade will also fail. A `FAIL` status will provide you
|
||||
a list of actions and affected entries that must be resolved before the next upgrade can complete
|
||||
successfully. If all tasks yield a `PASS` status then you can begin the upgrade process.
|
||||
|
||||
## Docker Update Procedure
|
||||
|
||||
Docker doesn't follow a "traditional" method of updates. Rather you remove the old version of the
|
||||
container and recreate it with a newer version. This document will help walk you through that
|
||||
process.
|
||||
|
|
@ -14,7 +40,23 @@ text=You should have documented and preserved your kanidm container create / run
|
|||
|
||||
<!-- deno-fmt-ignore-end -->
|
||||
|
||||
## Preserving the Previous Image
|
||||
### Upgrade Check
|
||||
|
||||
Perform the pre-upgrade check.
|
||||
|
||||
```bash
|
||||
docker exec -i -t <container name> \
|
||||
kanidmd domain upgrade-check
|
||||
|
||||
# Running domain upgrade check ...
|
||||
# domain_name : localhost
|
||||
# domain_uuid : 7dcc7a71-b488-4e2c-ad4d-d89fc49678cb
|
||||
# ------------------------
|
||||
# upgrade_item : gidnumber range validity
|
||||
# status : PASS
|
||||
```
|
||||
|
||||
### Preserving the Previous Image
|
||||
|
||||
You may wish to preserve the previous image before updating. This is useful if an issue is
|
||||
encountered in upgrades.
|
||||
|
|
@ -24,7 +66,7 @@ docker tag kanidm/server:latest kanidm/server:<DATE>
|
|||
docker tag kanidm/server:latest kanidm/server:2022-10-24
|
||||
```
|
||||
|
||||
## Update your Image
|
||||
### Update your Image
|
||||
|
||||
Pull the latest version of Kanidm.
|
||||
|
||||
|
|
@ -34,11 +76,11 @@ docker pull kanidm/radius:latest
|
|||
docker pull kanidm/tools:latest
|
||||
```
|
||||
|
||||
## Perform a backup
|
||||
### Perform a backup
|
||||
|
||||
See [backup and restore](backup_restore.md)
|
||||
|
||||
## Update your Instance
|
||||
### Update your Instance
|
||||
|
||||
<!-- deno-fmt-ignore-start -->
|
||||
|
||||
|
|
@ -80,7 +122,8 @@ Once you confirm the upgrade is successful you can delete the previous instance
|
|||
docker rm <previous instance name>
|
||||
```
|
||||
|
||||
If you encounter an issue you can revert to the previous version.
|
||||
If you encounter an issue you can revert to the previous version. Upgrades are performed in a single
|
||||
transaction and no changes to your data are made unless the upgrade was successful.
|
||||
|
||||
```bash
|
||||
docker stop <new instance name>
|
||||
|
|
@ -95,4 +138,5 @@ docker run [Your Arguments Here] -v kanidmd:/data \
|
|||
kanidm/server:<DATE>
|
||||
```
|
||||
|
||||
If the server from your previous version fails to start, you will need to restore from backup.
|
||||
In rare and exceptional cases, if the server from your previous version fails to start, you will
|
||||
need to restore from backup.
|
||||
|
|
|
|||
|
|
@ -1,9 +1,5 @@
|
|||
# Kanidm - Support and Release Processes
|
||||
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/kanidm/kanidm/master/artwork/logo-small.png" width="20%" height="auto" />
|
||||
</p>
|
||||
|
||||
# Introduction
|
||||
|
||||
This document describes the Kanidm project teams support and release version processes.
|
||||
|
|
@ -13,8 +9,8 @@ missing or if you have a question, please
|
|||
[open a discussion](https://github.com/kanidm/kanidm/discussions).
|
||||
|
||||
The version of this document found
|
||||
[on the project page](https://github.com/kanidm/kanidm/blob/master/project_docs/RELEASE_AND_SUPPORT.md)
|
||||
is considered authoritive and applies to all versions.
|
||||
[on the project page](https://github.com/kanidm/kanidm/blob/master/book/src/support.md) is
|
||||
considered authoritive and applies to all versions.
|
||||
|
||||
## Release Schedule and Versioning
|
||||
|
||||
|
|
@ -1,67 +0,0 @@
|
|||
# Developer Principles
|
||||
|
||||
As a piece of software that stores the identities of people, the project becomes bound to social and
|
||||
political matters. The decisions we make have consequences on many people - many who never have the
|
||||
chance to choose what software is used to store their identities (think employees in a business).
|
||||
|
||||
This means we have a responsibility to not only be aware of our impact on our direct users
|
||||
(developers, system administrators, dev ops, security and more) but also the impact on indirect
|
||||
consumers - many of who are unlikely to be in a position to contact us to ask for changes and help.
|
||||
|
||||
## Ethics / Rights
|
||||
|
||||
If you have not already, please see our documentation on [rights and ethics]
|
||||
|
||||
[rights and ethics]: https://github.com/kanidm/kanidm/blob/master/ethics/README.md
|
||||
|
||||
## Humans First
|
||||
|
||||
We must at all times make decisions that put humans first. We must respect all cultures, languages,
|
||||
and identities and how they are represented.
|
||||
|
||||
This may mean we make technical choices that are difficult or more complex, or different to "how
|
||||
things have always been done". But we do this to ensure that all people can have their identities
|
||||
stored how they choose.
|
||||
|
||||
For example, any user may change their name, display name and legal name at any time. Many
|
||||
applications will break as they primary key from name when this occurs. But this is the fault of the
|
||||
application. Name changes must be allowed. Our job as technical experts is to allow that to happen.
|
||||
|
||||
We will never put a burden on the user to correct for poor designs on our part. For example, locking
|
||||
an account if it logs in from a different country unless the user logs in before hand to indicate
|
||||
where they are going. This makes the user responsible for a burden (changing the allowed login
|
||||
country) when the real problem is preventing bruteforce attacks - which can be technically solved in
|
||||
better ways that don't put administrative load to humans.
|
||||
|
||||
## Correct and Simple
|
||||
|
||||
As a piece of security sensitive software we must always put correctness first. All code must have
|
||||
tests. All developers must be able to run all tests on their machine and environment of choice.
|
||||
|
||||
This means that the following must always work:
|
||||
|
||||
```bash
|
||||
git clone ...
|
||||
cargo test
|
||||
```
|
||||
|
||||
If a test or change would require extra requirements, dependencies, or preconfiguration, then we can
|
||||
no longer provide the above. Testing must be easy and accessible, else we won't do it, and that
|
||||
leads to poor software quality.
|
||||
|
||||
The project must be simple. Any one should be able to understand how it works and why those
|
||||
decisions were made.
|
||||
|
||||
## Languages
|
||||
|
||||
The core server will (for now) always be written in Rust. This is due to the strong type guarantees
|
||||
it gives, and how that can help raise the quality of our project.
|
||||
|
||||
## Over-Configuration
|
||||
|
||||
Configuration will be allowed, but only if it does not impact the statements above. Having
|
||||
configuration is good, but allowing too much (IE a scripting engine for security rules) can give
|
||||
deployments the ability to violate human first principles, which reflects badly on us.
|
||||
|
||||
All configuration items, must be constrained to fit within our principles so that every kanidm
|
||||
deployment, will always provide a positive experience to all people.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# Examples of situations for consideration
|
||||
|
||||
## Ability to be forgotten
|
||||
|
||||
### Deletion is delete not flagging
|
||||
|
||||
When an account is deleted it must be truly deleted, not just flagged for future delete. Note that
|
||||
some functionality like the recycle bin, we must keep the account details, but a recycle bin purge
|
||||
does truly delete the account.
|
||||
|
||||
## Self determination and autonomy
|
||||
|
||||
### Self name change
|
||||
|
||||
People should be able to change their own name at anytime. Consider divorce, leaving abusive
|
||||
partners or other personal decisions around why a name change is relevant.
|
||||
|
||||
This is why names are self-service writeable at any time.
|
||||
|
||||
## Free from harmful discrimination of any kind
|
||||
|
||||
### Cultural and Social awareness of name formats
|
||||
|
||||
All name fields should be case sensitive utf8 with no max or min length limit. This is because names
|
||||
can take many forms such as.
|
||||
|
||||
- firstname middlename lastname
|
||||
- firstname lastname
|
||||
- firstname firstname lastname
|
||||
- firstname lastname lastname
|
||||
- firstname
|
||||
- lastname firstname
|
||||
|
||||
And many many more that are not listed here. This is why our names are displayName as a freetext
|
||||
UTF8 field, with case sensitivity and no limits.
|
||||
|
||||
## Informed consent and Privacy of their data
|
||||
|
||||
### Access to legalName field
|
||||
|
||||
legalName should only be on a "need to know" basis, and only collected if required. This is to help
|
||||
people who may be stalked or harassed, or otherwise conscious of their privacy.
|
||||
|
||||
## To use and access this software regardless of ability
|
||||
|
|
@ -1,24 +0,0 @@
|
|||
# Statement of ethics and rights
|
||||
|
||||
Kanidm is a project that will store, process and present people's personal data. This means we have
|
||||
a responsibility to respect the data of all people who could be using our system - many who interact
|
||||
indirectly or do not have a choice in this platform.
|
||||
|
||||
## Rights of people
|
||||
|
||||
All people using this software should expect to have the right to:
|
||||
|
||||
- Self control over their data, including the ability to alter or delete at any time.
|
||||
- Free from harmful discrimination of any kind
|
||||
- Informed consent over control and privacy of their data, including access and understand data held
|
||||
and shared on their behalf
|
||||
- To be able to use and access this software regardless of ability, culture or language.
|
||||
|
||||
## More?
|
||||
|
||||
For more detailed examples, please see [EXAMPLES.md](EXAMPLES.md)
|
||||
|
||||
## Questions?
|
||||
|
||||
Please raise an issue with the project - we want to know if we have missed anything or can improve
|
||||
what we are doing.
|
||||
Loading…
Reference in a new issue