mart-w/kanidm
1
0
Fork 0
mirror of https://github.com/kanidm/kanidm.git synced 2025-02-23 12:37:00 +01:00
Code Issues Actions 16 Packages Projects Releases Wiki Activity

Draft document (#382)

Browse source
This commit is contained in:
Firstyear 2021-03-25 10:34:29 +10:00 committed by GitHub
parent a22c8efe9e
commit 060c7b22c0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 243 additions and 140 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

101
DEVELOPER_README.md Normal file
View file

@ -0,0 +1,101 @@
## Getting Started (for Developers)
### Designs
See the [designs] folder, and compile the private documentation locally:
```
cargo doc --document-private-items --open --no-deps
```
[designs]: https://github.com/kanidm/kanidm/tree/master/designs
### Get involved
To get started, you'll need to fork or branch, and we'll merge based on PR's.
If you are a contributor to the project, simply clone:
```
git clone git@github.com:kanidm/kanidm.git
```
If you are forking, then Fork in github and clone with:
```
git clone https://github.com/kanidm/kanidm.git
cd kanidm
git remote add myfork git@github.com:<YOUR USERNAME>/kanidm.git
```
Select and issue (and always feel free to reach out to us for advice!), and create a branch to
start working:
```
git branch <feature-branch-name>
git checkout <feature-branche-name>
cargo test
```
When you are ready for review (even if the feature isn't complete and you just want some advice)
```
cargo test
git commit -m 'Commit message' change_file.rs ...
git push <myfork/origin> <feature-branch-name>
```
If you get advice or make changes, just keep commiting to the branch, and pushing to your branch.
When we are happy with the code, we'll merge in github, meaning you can now cleanup your branch.
```
git checkout master
git pull
git branch -D <feature-branch-name>
```
Rebasing:
If you are asked to rebase your change, follow these steps:
```
git checkout master
git pull
git checkout <feature-branche-name>
git rebase master
```
Then be sure to fix any merge issues or other comments as they arise. If you have issues, you can
always stop and reset with:
```
git rebase --abort
```
### Development Server Quickstart for Interactive Testing
After getting the code, you will need a rust environment. Please investigate rustup for your platform
to establish this.
Once you have the source code, you need certificates to use with the server. I recommend using
let's encrypt, but if this is not possible, please use our insecure cert tool. Without certificates
authentication will fail.
mkdir insecure
cd insecure
../insecure_generate_tls.sh
You can now build and run the server with the commands below. It will use a database in /tmp/kanidm.db
cd kanidmd
cargo run -- recover_account -c ./server.toml -n admin
cargo run -- server -c ./server.toml
In a new terminal, you can now build and run the client tools with:
cd kanidm_tools
cargo run -- --help
cargo run -- login -H https://localhost:8443 -D anonymous -C ../insecure/ca.pem
cargo run -- self whoami -H https://localhost:8443 -D anonymous -C ../insecure/ca.pem
cargo run -- login -H https://localhost:8443 -D admin -C ../insecure/ca.pem
cargo run -- self whoami -H https://localhost:8443 -D admin -C ../insecure/ca.pem

9
GETTING_STARTED.md
View file

@ -1,9 +0,0 @@
## Getting Started (for Administrators)
If you want to deploy kanidm, or to see what it can do, you should read the [kanidm book]
[kanidm book]: https://github.com/kanidm/kanidm/blob/master/kanidm_book/src/SUMMARY.md
## Getting Started (for Developers)
See the README.md file.

155
README.md
View file

@ -16,6 +16,15 @@ Today the project is still under heavy development to achieve these goals - We h
parts in place, and many of the required security features, but it is still an Alpha, and should be
treated as such.
## Documentation / Getting Started / Install
If you want to deploy kanidm to see what it can do, you should read the [kanidm book]
We also publish limited [support guidelines].
[kanidm book]: https://github.com/kanidm/kanidm/blob/master/kanidm_book/src/SUMMARY.md
[support guidelines]: https://github.com/kanidm/kanidm/blob/master/project_docs/RELEASE_AND_SUPPORT.md
## Code of Conduct / Ethics
See our [code of conduct]
@ -25,12 +34,6 @@ See our documentation 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/ethics/README.md
## Documentation / Getting Started / Install
If you want to deploy kanidm, or to see what it can do, you should read the [kanidm book]
[kanidm book]: https://github.com/kanidm/kanidm/blob/master/kanidm_book/src/SUMMARY.md
## Getting in Contact / Questions
We have a [gitter community channel] where we can talk. Firstyear is also happy to
@ -38,6 +41,14 @@ answer questions via email, which can be found on their github profile.
[gitter community channel]: https://gitter.im/kanidm/community
## Developer Getting Started
If you want to develop on the server, there is a getting started [guide for developers]. IDM
is a diverse topic and we encourage contributions of many kinds in the project, from people of
all backgrounds.
[guide for developers]: https://github.com/kanidm/kanidm/blob/master/DEVELOPER_README.md
## Features
### Implemented
@ -47,154 +58,44 @@ answer questions via email, which can be found on their github profile.
* MFA - TOTP
* Highly concurrent design (MVCC, COW)
* RADIUS integration
* MFA - Webauthn
### Currently Working On
* CLI for administration
* MFA - Webauthn
* WebUI for self service with wifi enrollment, claim management and more.
* RBAC/Claims/Policy (limited by time and credential scope)
### Upcoming Focus Areas
* WebUI for self service with wifi enrollment, claim management and more.
* RBAC/Claims (limited by time and credential scope)
* OIDC/Oauth
* Replication (async multiple active write servers, read only servers)
### Future
* SSH CA management
* Sudo rule distribution via nsswitch
* WebUI for administration
* Account impersonation
* Synchronisation to other IDM services
### Features We Want to Avoid
* Auditing: This is better solved by SIEM software, so we should generate data they can consume.
* Fully synchronous behaviour: This prevents scaling and our future ability to expand.
* Generic database: We don't want to be another NoSQL database, we want to be an IDM solution.
* Being LDAP/GSSAPI/Kerberos: These are all legacy protocols that are hard to use and confine our thinking - we should avoid "being like them".
## Some key ideas
## Some key project ideas
* All people should be respected and able to be respresented securely.
* Devices represent users and their identities - they are part of the authentication.
* Human error occurs - we should be designed to minimise human mistakes and empower people.
* The system should be easy to understand and reason about for users and admins.
## Development and Testing
### Features We Want to Avoid
### Designs
* Auditing: This is better solved by SIEM software, so we should generate data they can consume.
* Fully synchronous behaviour: This prevents scaling and our future ability to expand.
* Generic database: We don't want to be another NoSQL database, we want to be an IDM solution.
* Being like LDAP/GSSAPI/Kerberos: These are all legacy protocols that are hard to use and confine our thinking - we should avoid "being like them" or using them as models.
See the [designs] folder, and compile the private documentation locally:
```
cargo doc --document-private-items --open --no-deps
```
[designs]: https://github.com/kanidm/kanidm/tree/master/designs
### Get involved
To get started, you'll need to fork or branch, and we'll merge based on PR's.
If you are a contributor to the project, simply clone:
```
git clone git@github.com:kanidm/kanidm.git
```
If you are forking, then Fork in github and clone with:
```
git clone https://github.com/kanidm/kanidm.git
cd kanidm
git remote add myfork git@github.com:<YOUR USERNAME>/kanidm.git
```
Select and issue (and always feel free to reach out to us for advice!), and create a branch to
start working:
```
git branch <feature-branch-name>
git checkout <feature-branche-name>
cargo test
```
When you are ready for review (even if the feature isn't complete and you just want some advice)
```
cargo test
git commit -m 'Commit message' change_file.rs ...
git push <myfork/origin> <feature-branch-name>
```
If you get advice or make changes, just keep commiting to the branch, and pushing to your branch.
When we are happy with the code, we'll merge in github, meaning you can now cleanup your branch.
```
git checkout master
git pull
git branch -D <feature-branch-name>
```
Rebasing:
If you are asked to rebase your change, follow these steps:
```
git checkout master
git pull
git checkout <feature-branche-name>
git rebase master
```
Then be sure to fix any merge issues or other comments as they arise. If you have issues, you can
always stop and reset with:
```
git rebase --abort
```
### Development Server Quickstart for Interactive Testing
After getting the code, you will need a rust environment. Please investigate rustup for your platform
to establish this.
Once you have the source code, you need certificates to use with the server. I recommend using
let's encrypt, but if this is not possible, please use our insecure cert tool. Without certificates
authentication will fail.
mkdir insecure
cd insecure
../insecure_generate_tls.sh
You can now build and run the server with the commands below. It will use a database in /tmp/kanidm.db
cd kanidmd
cargo run -- recover_account -c ./server.toml -n admin
cargo run -- server -c ./server.toml
In a new terminal, you can now build and run the client tools with:
cd kanidm_tools
cargo run -- --help
cargo run -- self whoami -H https://localhost:8080 -D anonymous -C ../insecure/ca.pem
cargo run -- self whoami -H https://localhost:8080 -D admin -C ../insecure/ca.pem
### Using curl with anonymous:
Sometimes you may want to check the json of an endpoint. Before you can do this, you need
a valid session and cookie jar established. To do this with curl and anonymous:
curl -b /tmp/cookie.jar -c /tmp/cookie.jar --cacert ../insecure/ca.pem -X POST -d "{\"step\":{\"Init\":[\"anonymous\",null]}}" https://localhost:8080/v1/auth
curl -b /tmp/cookie.jar -c /tmp/cookie.jar --cacert ../insecure/ca.pem -X POST -d "{\"step\":{\"Creds\":[\"Anonymous\"]}}" https://localhost:8080/v1/auth
## Why do I see rsidm references?
## What does Kanidm mean?
The original project name was rsidm while it was a thought experiment. Now that it's growing
and developing, we gave it a better project name. Kani is Japanese for "crab". Rust's mascot is a crab.
Idm is the common industry term for identity management services.

22
kanidm_book/src/installing_the_server.md
View file

@ -12,6 +12,28 @@ You can fetch these with:
There are a number of configuration steps you must perform before you can run this container.
## System Requirements
### CPU
You must have a CPU that is from 2013 or newer (Haswell, Ryzen). This is due to the usage of
SIMD for a number of internal components.
Older or unsupported CPU's may raise a SIGIL (Illegal Instruction) on hardware that is not supported
by the project.
### Memory
Kanidm extensively uses memory caching, trading memory consumption to improve parallel throughput.
You should expect to see 64KB of ram per entry in your database, depending on cache tuning and settings.
### Disk
You should expect to use up to 8KB of disk per entry you plan to store. At an estimate 10,000 entry
databases will consume 40MB, 100,000 entry will consume 400MB.
For best performance, you should use NVME or other Flash media.
## TLS
You'll need a volume where you can place configuration, certificates, and the database:

83
kanidm_book/src/intro.md
View file

@ -3,14 +3,89 @@
Kanidm is an identity management server, acting as an authority on accounts and authorisation
within a technical environment.
> **NOTICE:**
> This is a pre-release project. While all effort has been made to ensure no dataloss
> or security flaws, you should still be careful when using this in your environment.
The intent of the Kanidm project is:
* To provide a single truth source for accounts, groups and privileges.
* To enable integrations to systems and services so they can authenticate accounts.
* To make system, network, application and web authentication easy and accessible.
> **NOTICE:**
> This is a pre-release project. While all effort has been made to ensure no dataloss
> or security flaws, you should still be careful when using this in your environment.
## Why do I want Kanidm?
Whether you work in a business, a volunteer organisation, or an enthusiast who manages some
of their own personal services, we need methods of authenitcating and identifying ourselves
to these systems, and subsequently a way a determine what authorisation and privieleges we have
while accessing these systems.
We've probably all been in work places where you end up with multiple accounts on various
systems - one for a workstation, different ssh keys for different tasks, maybe some shared
account passwords. Not only is it difficult for people to manage all these different credentials
and what they have access to, but it also means that sometimes these credentials have more
access or privelege than they require.
Kanidm acts as a central authority of accounts in your organisation, and allows each account to associate
many devices and credentials with different privileges. An example of how this looks:
┌──────────────────┐
┌┴─────────────────┐│
│ ││
┌───────────────────┬───▶│ Kanidm │◀──────┬─────────────────────────┐
│ │ │ ├┘ │ │
│ │ └──────────────────┘ │ Verify
Account Data │ ▲ │ Radius
References │ │ │ Password
│ │ │ │ │
│ │ │ │ ┌────────────┐
│ │ │ │ │ │
│ │ │ Verify │ RADIUS │
┌────────────┐ │ Retrieve SSH Application │ │
│ │ │ Public Keys Password └────────────┘
│ Database │ │ │ │ ▲
│ │ │ │ │ │
└────────────┘ │ │ │ ┌─────────┴──────────┐
▲ │ │ │ │ │
│ │ │ │ │ │
┌────────────┐ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
│ │ │ │ │ │ │ │ │ │ │
│ Web Site │ │ │ SSH │ │ Email │ │ WIFI │ │ VPN │
│ │ │ │ │ │ │ │ │ │ │
└────────────┘ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘
▲ │ ▲ ▲ ▲ ▲
│ │ │ │ │ │
│ │ │ │ │ │
│ Login To │ │ │ │
SSO/Oauth Oauth/SSO SSH Keys Application Radius Radius
│ │ │ Password Password Password
│ │ │ │ │ │
│ │ │ │ │ │
│ │ │ │ │ │
│ │ ┌──────────┐ │ │ │
│ │ │ │ │ │ │
└──────────────────┴────────│ Laptop │───────────┴───────────────┴────────────────────┘
│ │
└──────────┘
▲
│
│
┌──────────┐
│ You │
└──────────┘
A key design goal is that you authenticate to your device in some manner, and then your device will
continue to authenticate you in the future. Each of these different types of credential from ssh keys,
application passwords, radius passwords and others, are "things your device knows". Each password
has limited capability, and can only access that exact service or resource.
This helps improve security as a compromise of the service or the network tranmission does not
grant you unlimited access to your account and all it's privileges. As the credentials are specific
to a device, if a device is compromised you are able to revoke it's associated credentials. If a
specific service is compromised, only the credentials for that service need to be revoked.
Due to this model, and the design of Kanidm to centre the device and to have more per-service credentials,
workflows and automations are added or designed to reduce human handling of these. An example of this
is the use of qr codes with deployment profiles to automatically enroll wireless credentials.

13
project_docs/RELEASE_AND_SUPPORT.md
View file

@ -25,3 +25,16 @@ In the case these issues are found, an out of band alpha snapshot will be made.
Alpha releases are "best effort", and are trial releases, to help get early feedback and improvements
from the community, while still allowing us to make large, breaking changes that may be needed.
## API stability
There are a number of "surfaces" that can be considered as "API" in Kanidm.
* JSON HTTP end points of kanidmd
* unix domain socket API of kanidm_unixd resolver
* CLI interface of kanidm admin command
During the Alpha, there is no guarantee that *any* of these APIs will remain stable. Only elements from "the same release" are guaranteed to work with each other.
Once an official release is made, only the JSON API will be declared stable. The unix domain socket API is internal, and the CLI is *not* an API and can change with the interest of human interaction during any release.