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 Packages Projects Releases Wiki Activity

minor corrections, line breaks, capitalization, expand abbreviations (#802)

Browse source 
* minor corrections, line breaks, capitalization, expand abbreviations
This commit is contained in:
Carla Schroder 2022-06-02 15:05:01 -07:00 committed by GitHub
parent e5b37dfe20
commit 55d76cd7dc
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 66 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

89
DEVELOPER_README.md
View file

@ -12,7 +12,8 @@ cargo doc --document-private-items --open --no-deps
### Rust Documentation
A list of links to the library documentation is [here](https://kanidm.com/documentation/).
A list of links to the library documentation is at
[kanidm.com/documentation](https://kanidm.com/documentation/).
### Minimum Supported Rust Version
@ -22,15 +23,13 @@ The MSRV is specified in the package `Cargo.toml` files.
#### MacOS
You will need [rustup](https://rustup.rs/) to install a rust toolchain.
If you plan to work on the web-ui, you may also need npm for setting up some parts.
brew install npm
You will need [rustup](https://rustup.rs/) to install a Rust toolchain.
#### SUSE
You will need [rustup](https://rustup.rs/) to install a rust toolchain. If you're using the Tumbleweed release, it's packaged in `zypper`.
You will need [rustup](https://rustup.rs/) to install a Rust toolchain. If
you're
using the Tumbleweed release, it's packaged in `zypper`.
You will also need some system libraries to build this:
@ -38,7 +37,7 @@ You will also need some system libraries to build this:
#### Fedora
You will need to install the rust toolchain packages.
You need to install the Rust toolchain packages:
rust cargo
@ -46,13 +45,13 @@ You will also need some system libraries to build this:
systemd-devel sqlite-devel openssl-devel pam-devel
Building the web ui requires additional packages:
Building the Web UI requires additional packages:
perl-FindBin perl-File-Compare rust-std-static-wasm32-unknown-unknown
#### Ubuntu
You will need [rustup](https://rustup.rs/) to install a rust toolchain.
You need [rustup](https://rustup.rs/) to install a Rust toolchain.
You will also need some system libraries to build this, which can be installed by running:
@ -62,9 +61,10 @@ sudo apt-get install libsqlite3-dev libudev-dev libssl-dev
Tested with Ubuntu 20.04.
### Get involved
### Get Involved
To get started, you'll need to fork or branch, and we'll merge based on PR's.
To get started, you'll need to fork or branch, and we'll merge based on pull
requests.
If you are a contributor to the project, simply clone:
@ -80,7 +80,8 @@ cd kanidm
git remote add myfork git@github.com:<YOUR USERNAME>/kanidm.git
```
Select an issue (always feel free to reach out to us for advice!), and create a branch to start working:
Select an issue (always feel free to reach out to us for advice!), and create a
branch to start working:
```shell
git branch <feature-branch-name>
@ -88,11 +89,13 @@ git checkout <feature-branch-name>
cargo test
```
When you are ready for review (even if the feature isn't complete and you just want some advice)
When you are ready for review (even if the feature isn't complete and you just
want some advice):
1. Run the test suite: `cargo test --workspace`
2. Ensure rust formatting standards are followed: `cargo fmt --check`
3. Try following the suggestions from clippy, after running `cargo clippy`. This is not a blocker on us accepting your code!
3. Try following the suggestions from clippy, after running `cargo clippy`.
This is not a blocker on us accepting your code!
4. Then commit your changes:
```shell
@ -100,8 +103,9 @@ git commit -m 'Commit message' change_file.rs ...
git push <myfork/origin> <feature-branch-name>
```
If you receive advice or make further 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 clean up your branch.
If you receive advice or make further 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 clean up your branch.
```
git checkout master
@ -120,7 +124,8 @@ git checkout <feature-branch-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:
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
@ -128,13 +133,18 @@ git rebase --abort
### Development Server Quickstart for Interactive Testing
After getting the code, you will need a rust environment. Please investigate [rustup](https://rustup.rs) for your platform to establish this.
After getting the code, you will need a rust environment. Please investigate
[rustup](https://rustup.rs) for your platform to establish this.
Once you have the source code, you need certificates to use with the server, because without certificates, authentication will fail.
Once you have the source code, you need encryption certificates to use with the server,
because without certificates, authentication will fail.
We recommend using [Let's Encrypt](https://letsencrypt.org), but if this is not possible, please use our insecure cert tool (`insecure_generate_tls.sh`). The insecure cert tool creates `/tmp/kanidm` and puts some self-signed certificates there.
We recommend using [Let's Encrypt](https://letsencrypt.org), but if this is not
possible, please use our insecure certificate tool (`insecure_generate_tls.sh`). The
insecure certificate tool creates `/tmp/kanidm` and puts some self-signed certificates there.
You can now build and run the server with the commands below. It will use a database in `/tmp/kanidm.db`.
You can now build and run the server with the commands below. It will use a database
in `/tmp/kanidm.db`.
Create the initial database and generate an `admin` username:
@ -160,25 +170,30 @@ In a new terminal, you can now build and run the client tools with:
### Building the Web UI
__NOTE:__ There is a pre-packaged version of the Web UI at `/kanidmd_web_ui/pkg/`, which can be used directly. This means you don't need to build the Web UI yourself
__NOTE:__ There is a pre-packaged version of the Web UI at `/kanidmd_web_ui/pkg/`,
which can be used directly. This means you don't need to build the Web UI yourself.
The web UI uses rust wasm rather than javascript. To build this you need to set up the environment.
The Web UI uses Rust WebAssembly rather than Javascript. To build this you need
to set up the environment:
cargo install wasm-pack
npm install --global rollup
Then you are able to build the UI.
Then you are able to build the UI:
cd kanidmd_web_ui/
./build_wasm.sh
The "developer" profile for kanidmd will automatically use the pkg output in this folder.
Setting different developer profiles while building is done by setting the environment variable KANIDM_BUILD_PROFILE to one of the bare filename of the TOML files in `/profiles`.
Setting different developer profiles while building is done by setting the
environment
variable KANIDM_BUILD_PROFILE to one of the bare filename of the TOML files in
`/profiles`.
For example: `KANIDM_BUILD_PROFILE=release_suse_generic cargo build --release --bin kanidmd`
### Build a kanidm container
### Build a Kanidm Container
Build a container with the current branch using:
@ -198,7 +213,7 @@ The following environment variables control the build:
|`CONTAINER_TOOL`|Use an alternative container build tool.|`docker`|
|`BOOK_VERSION`|Sets version used when building the documentation book.|`master`|
#### Container build examples
#### Container Build Examples
Build a `kanidm` container using `podman`:
@ -208,15 +223,21 @@ Build a `kanidm` container and use a redis build cache:
CONTAINER_BUILD_ARGS='--build-arg "SCCACHE_REDIS=redis://redis.dev.blackhats.net.au:6379"' make build/kanidmd
#### Automatically built containers
#### Automatically Built Containers
To speed up testing across platforms, we're leveraging GitHub actions to build containers for test use.
To speed up testing across platforms, we're leveraging GitHub actions to build
containers for test use.
Whenever code is merged with the `master` branch of Kanidm, containers are automatically built for `kanidmd` and `radius`. Sometimes they fail to build, but we'll try and keep them avilable.
Whenever code is merged with the `master` branch of Kanidm, containers are automatically
built for `kanidmd` and `radius`. Sometimes they fail to build, but we'll try to
keep them avilable.
To find information on the packages, [visit the Kanidm packages page here](https://github.com/orgs/kanidm/packages?repo_name=kanidm).
To find information on the packages,
[visit the Kanidm packages page](https://github.com/orgs/kanidm/packages?repo_name=kanidm).
An example command for pulling and running the radius container is below. You'll need to [authenticate with the GitHub container registry first](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry).
An example command for pulling and running the radius container is below. You'll
need to
[authenticate with the GitHub container registry first](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry).
```shell
docker pull ghcr.io/kanidm/radius:devel

23
kanidm_book/src/why_tls.md
View file

@ -2,31 +2,30 @@
# Why TLS?
You may have noticed that Kanidm requires you to configure TLS in
your container - or that you provide something *with* TLS in front like haproxy.
your container - or that you provide something *with* TLS in front, like haproxy.
This is due to a single setting on the server - `secure_cookies`
## What are Secure Cookies?
`secure-cookies` is a flag set in cookies that "asks" a client to transmit them
back to the origin site if and only if https is present in the URL.
`secure-cookies` is a flag set in cookies that asks a client to transmit them
back to the origin site if and only if HTTPS is present in the URL.
CA verification is *not* checked - you can use invalid, out of date certificates,
or even certificates where the `subjectAltName` does not match, but the client
must see https:// as the destination else it *will not* send the cookies.
Certificate authority (CA) verification is *not* checked - you can use invalid,
out of date certificates, or even certificates where the `subjectAltName` does
not match, but the client must see https:// as the destination else it *will not*
send the cookies.
## How does that affect Kanidm?
## How Does That Affect Kanidm?
Kanidm's authentication system is a stepped challenge response design, where you
initially request an "intent" to authenticate. Once you establish this intent,
the server sets up a session-id into a cookie, and informs the client of
what authentication methods can proceed.
When you then go to continue the authentication, if you do NOT have a https url,
the cookie with the session-id is not transmitted. The server detects this as
an invalid-state request in the authentication design and immediately disconnects
you from attempting to continue the authentication as you may be using an insecure
channel.
If you do NOT have a HTTPS URL, the cookie with the session-id is not transmitted.
The server detects this as an invalid-state request in the authentication design,
and immediately breaks the connection, because it appears insecure.
Simply put, we are trying to use settings like secure_cookies to add constraints
to the server so that you *must* perform and adhere to best practices - such