From 060c7b22c01609ed68cbccbf03da4831167a5af0 Mon Sep 17 00:00:00 2001 From: Firstyear Date: Thu, 25 Mar 2021 10:34:29 +1000 Subject: [PATCH] Draft document (#382) --- DEVELOPER_README.md | 101 +++++++++++++++ GETTING_STARTED.md | 9 -- README.md | 155 ++++------------------- kanidm_book/src/installing_the_server.md | 22 ++++ kanidm_book/src/intro.md | 83 +++++++++++- project_docs/RELEASE_AND_SUPPORT.md | 13 ++ 6 files changed, 243 insertions(+), 140 deletions(-) create mode 100644 DEVELOPER_README.md delete mode 100644 GETTING_STARTED.md diff --git a/DEVELOPER_README.md b/DEVELOPER_README.md new file mode 100644 index 000000000..eecfbacbb --- /dev/null +++ b/DEVELOPER_README.md @@ -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:/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 +git checkout +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 +``` + +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 +``` + +Rebasing: + +If you are asked to rebase your change, follow these steps: + +``` +git checkout master +git pull +git checkout +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 diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md deleted file mode 100644 index 5c24708c5..000000000 --- a/GETTING_STARTED.md +++ /dev/null @@ -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. diff --git a/README.md b/README.md index 6a1ec076d..17c50387e 100644 --- a/README.md +++ b/README.md @@ -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:/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 -git checkout -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 -``` - -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 -``` - -Rebasing: - -If you are asked to rebase your change, follow these steps: - -``` -git checkout master -git pull -git checkout -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. - - diff --git a/kanidm_book/src/installing_the_server.md b/kanidm_book/src/installing_the_server.md index 95eccc547..8d46c88cc 100644 --- a/kanidm_book/src/installing_the_server.md +++ b/kanidm_book/src/installing_the_server.md @@ -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: diff --git a/kanidm_book/src/intro.md b/kanidm_book/src/intro.md index f82f3e46e..8bf15ae38 100644 --- a/kanidm_book/src/intro.md +++ b/kanidm_book/src/intro.md @@ -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. + diff --git a/project_docs/RELEASE_AND_SUPPORT.md b/project_docs/RELEASE_AND_SUPPORT.md index 5ca1a9cdc..207fc6984 100644 --- a/project_docs/RELEASE_AND_SUPPORT.md +++ b/project_docs/RELEASE_AND_SUPPORT.md @@ -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. +