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

Book updates (#1067)

Browse source 
* blep

* more blep

* fixed book build issues, updooted some FAQ and troubleshooting things

* more random updoots

* dat yak thoe
This commit is contained in:
James Hodgkinson 2022-09-21 13:05:32 +10:00 committed by GitHub
parent 1be1ab697e
commit d14c2d2330
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
10 changed files with 231 additions and 109 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

96
examples/server_container.toml Normal file
View file

@ -0,0 +1,96 @@
# The webserver bind address. Will use HTTPS if tls_*
# is provided.
# Defaults to "127.0.0.1:8443"
bindaddress = "[::]:8443"
#
# The read-only ldap server bind address. The server
# will use LDAPS if tls_* is provided.
# Defaults to "" (disabled)
# ldapbindaddress = "[::]:3636"
#
# The path to the kanidm database.
db_path = "/data/kanidm.db"
#
# If you have a known filesystem, kanidm can tune sqlite
# to match. Valid choices are:
# [zfs, other]
# If you are unsure about this leave it as the default
# (other). After changing this
# value you must run a vacuum task.
# - zfs:
# * sets sqlite pagesize to 64k. You must set
# recordsize=64k on the zfs filesystem.
# - other:
# * sets sqlite pagesize to 4k, matching most
# filesystems block sizes.
# db_fs_type = "zfs"
#
# The number of entries to store in the in-memory cache.
# Minimum value is 256. If unset
# an automatic heuristic is used to scale this.
# db_arc_size = 2048
#
# TLS chain and key in pem format. Both must be
# commented, or both must be present
# tls_chain = "/data/chain.pem"
# tls_key = "/data/key.pem"
#
# The log level of the server. May be default, verbose,
# perfbasic, perffull
# Defaults to "default"
# log_level = "default"
#
# The DNS domain name of the server. This is used in a
# number of security-critical contexts
# such as webauthn, so it *must* match your DNS
# hostname. It is used to create
# security principal names such as `william@idm.example.com`
# so that in a (future)
# trust configuration it is possible to have unique Service
# Principal Names (spns) throughout the topology.
# ⚠️ WARNING ⚠️
# Changing this value WILL break many types of registered
# credentials for accounts
# including but not limited to webauthn, oauth tokens, and more.
# If you change this value you *must* run
# `kanidmd domain_name_change` immediately after.
domain = "idm.example.com"
#
# The origin for webauthn. This is the url to the server,
# with the port included if
# it is non-standard (any port except 443). This must match
# or be a descendent of the
# domain name you configure above. If these two items are
# not consistent, the server WILL refuse to start!
# origin = "https://idm.example.com"
origin = "https://idm.example.com:8443"
#
# The role of this server. This affects available features
# and how replication may interact.
# Valid roles are:
# - WriteReplica
# This server provides all functionality of Kanidm. It
# allows authentication, writes, and
# the web user interface to be served.
# - WriteReplicaNoUI
# This server is the same as a WriteReplica, but does NOT
# offer the web user interface.
# - ReadOnlyReplica
# This server will not writes initiated by clients. It
# supports authentication and reads,
# and must have a replication agreement as a source of
# its data.
# Defaults to "WriteReplica".
# role = "WriteReplica"
#
# [online_backup]
# The path to the output folder for online backups
# path = "/var/lib/kanidm/backups/"
# The schedule to run online backups (see https://crontab.guru/)
# every day at 22:00 UTC (default)
# schedule = "00 22 * * *"
# four times a day at 3 minutes past the hour, every 6th hours
# schedule = "03 */6 * * *"
# Number of backups to keep (default 7)
# versions = 7
#

3
kanidm_book/src/SUMMARY.md
View file

@ -16,6 +16,8 @@
- [SSH Key Distribution](ssh_key_dist.md)
- [The Recycle Bin](recycle_bin.md)
- [Why TLS?](why_tls.md)
- [Frequently Asked Questions](frequently_asked_questions.md)
- [Troubleshooting](troubleshooting.md)
# Integrations
@ -42,4 +44,3 @@
- [Packaging](packaging.md)
- [Debian/Ubuntu](packaging_debs.md)

6
kanidm_book/src/accounts_and_groups.md
View file

@ -54,7 +54,8 @@ to be "recovered" from the server that is running the kanidmd server.
{{#template
templates/kani-warning.md
imagepath=images
text=Warning: The server must not be running at this point, as it requires exclusive access to the database.
title=Warning!
text=The server must not be running at this point, as it requires exclusive access to the database.
}}
```shell
@ -131,7 +132,8 @@ kanidm account person update demo_user --legalname "initial name" --mail "initia
{{#template
templates/kani-warning.md
imagepath=images
text=Warning: Persons may change their own displayname, name, and legal name at any time. You MUST NOT use these values as primary keys in external systems. You MUST use the `uuid` attribute present on all entries as an external primary key.
title=Warning!
text=Persons may change their own displayname, name, and legal name at any time. You MUST NOT use these values as primary keys in external systems. You MUST use the `uuid` attribute present on all entries as an external primary key.
}}
## Resetting Person Account Credentials

6
kanidm_book/src/choosing_a_domain_name.md
View file

@ -6,11 +6,9 @@ is not simple as there are a number of considerations you need to be careful of.
{{#template
templates/kani-warning.md
imagepath=images
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!
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 the advice in this chapter.
}}
## Considerations

3
kanidm_book/src/developers/designs/rest_interface.md
View file

@ -1,9 +1,8 @@
# REST Interface
{{#template
../../templates/kani-warning.md
imagepath=../../images
imagepath=../../images/
text=Here begins some early notes on the REST interface - much better ones are in the repository's designs directory.
}}

19
kanidm_book/src/frequently_asked_questions.md Normal file
View file

@ -0,0 +1,19 @@
# Frequently Asked Questions
... or ones we think people *might* ask.
## Why so many crabs?
It's [a rust thing](https://rustacean.net).
## Will you implement -insert protocol here-
Probably, on an infinite time-scale! As long as it's not Kerberos. Or involves SSL or STARTTLS. Please log an issue and start the discussion!
## Why do the crabs have knives?
Don't [ask](https://www.youtube.com/watch?v=0QaAKi0NFkA). They just [do](https://www.youtube.com/shorts/WizH5ae9ozw).
## Why won't you take this FAQ thing seriously?
Look, people just haven't asked many questions yet.

3
kanidm_book/src/intro.md
View file

@ -9,8 +9,7 @@ The intent of the Kanidm project is to:
* Enable integrations to systems and services so they can authenticate accounts.
* Make system, network, application and web authentication easy and accessible.
{{#template
{{#template
templates/kani-warning.md
imagepath=images
title=NOTICE

102
kanidm_book/src/server_configuration.md
View file

@ -4,105 +4,11 @@
You need a configuration file in the volume named `server.toml`. (Within the container it should be `/data/server.toml`) Its contents should be as follows:
# The webserver bind address. Will use HTTPS if tls_*
# is provided.
# Defaults to "127.0.0.1:8443"
bindaddress = "[::]:8443"
#
# The read-only ldap server bind address. The server
# will use LDAPS if tls_* is provided.
# Defaults to "" (disabled)
# ldapbindaddress = "[::]:3636"
#
# The path to the kanidm database.
db_path = "/data/kanidm.db"
#
# If you have a known filesystem, kanidm can tune sqlite
# to match. Valid choices are:
# [zfs, other]
# If you are unsure about this leave it as the default
# (other). After changing this
# value you must run a vacuum task.
# - zfs:
# * sets sqlite pagesize to 64k. You must set
# recordsize=64k on the zfs filesystem.
# - other:
# * sets sqlite pagesize to 4k, matching most
# filesystems block sizes.
# db_fs_type = "zfs"
#
# The number of entries to store in the in-memory cache.
# Minimum value is 256. If unset
# an automatic heuristic is used to scale this.
# db_arc_size = 2048
#
# TLS chain and key in pem format. Both must be
# commented, or both must be present
# tls_chain = "/data/chain.pem"
# tls_key = "/data/key.pem"
#
# The log level of the server. May be default, verbose,
# perfbasic, perffull
# Defaults to "default"
# log_level = "default"
#
# The DNS domain name of the server. This is used in a
# number of security-critical contexts
# such as webauthn, so it *must* match your DNS
# hostname. It is used to create
# security principal names such as `william@idm.example.com`
# so that in a (future)
# trust configuration it is possible to have unique Service
# Principal Names (spns) throughout the topology.
# ⚠️ WARNING ⚠️
# Changing this value WILL break many types of registered
# credentials for accounts
# including but not limited to webauthn, oauth tokens, and more.
# If you change this value you *must* run
# `kanidmd domain_name_change` immediately after.
domain = "idm.example.com"
#
# The origin for webauthn. This is the url to the server,
# with the port included if
# it is non-standard (any port except 443). This must match
# or be a descendent of the
# domain name you configure above. If these two items are
# not consistent, the server WILL refuse to start!
# origin = "https://idm.example.com"
origin = "https://idm.example.com:8443"
#
# The role of this server. This affects available features
# and how replication may interact.
# Valid roles are:
# - WriteReplica
# This server provides all functionality of Kanidm. It
# allows authentication, writes, and
# the web user interface to be served.
# - WriteReplicaNoUI
# This server is the same as a WriteReplica, but does NOT
# offer the web user interface.
# - ReadOnlyReplica
# This server will not writes initiated by clients. It
# supports authentication and reads,
# and must have a replication agreement as a source of
# its data.
# Defaults to "WriteReplica".
# role = "WriteReplica"
#
# [online_backup]
# The path to the output folder for online backups
# path = "/var/lib/kanidm/backups/"
# The schedule to run online backups (see https://crontab.guru/)
# every day at 22:00 UTC (default)
# schedule = "00 22 * * *"
# four times a day at 3 minutes past the hour, every 6th hours
# schedule = "03 */6 * * *"
# Number of backups to keep (default 7)
# versions = 7
#
```
{{#rustdoc_include ../../examples/server_container.toml}}
```
An example is located in [examples/server.toml](https://github.com/kanidm/kanidm/blob/master/examples/server.toml).
This example is located in [examples/server_container.toml](https://github.com/kanidm/kanidm/blob/master/examples/server_container.toml).
{{#template
templates/kani-warning.md

62
kanidm_book/src/troubleshooting.md Normal file
View file

@ -0,0 +1,62 @@
# Troubleshooting
Some things to try.
## Is the server started?
If you don't see "ready to rock! 🪨" in your logs, it's not started. Scroll back and look for errors!dd
## Can you connect?
If the server's running on `idm.example.com:8443` then a simple connectivity test is done using [curl](https://curl.se).
Run the following command:
```shell
curl -k https://idm.example.com:8443/status
```
This is similar to what you *should* see:
```shell
{{#rustdoc_include troubleshooting/curl_connection_test.txt}}
```
This means:
1. you've successfully connected to a host (10.0.0.14),
2. TLS worked
3. Received the status response "true"
If you see something like this:
```
➜ curl -v https://idm.example.com:8443
* Trying 10.0.0.1:8443...
* connect to 10.0.0.1 port 8443 failed: Connection refused
* Failed to connect to idm.example.com port 8443 after 5 ms: Connection refused
* Closing connection 0
curl: (7) Failed to connect to idm.example.com port 8443 after 5 ms: Connection refused
```
Then either your DNS is wrong (it's pointing at 10.0.0.1) or you can't connect to the server for some reason.
If you get errors about certificates, try adding `-k` to skip certificate verification checking and just test connectivity:
```
curl -vk https://idm.example.com:8443
```
## Server things to check
* Has the config file got `bindaddress = "127.0.0.1:8443"` ? Change it to `bindaddress = "[::]:8443"`, so it listens on all interfaces.
* Is there a firewall on the server?
* If you're running in docker, did you expose the port? (`-p 8443:8443`)
## Client things to check
Try running commands with `RUST_LOG=debug` to get more information:
```
RUST_LOG=debug kanidm login --name anonymous
```

40
kanidm_book/src/troubleshooting/curl_connection_test.txt Normal file
View file

@ -0,0 +1,40 @@
➜ curl -vk https://idm.example.com:8443/status
* Trying 10.0.0.14:8443...
* Connected to idm.example.com (10.0.0.14) port 8443 (#0)
* successfully set certificate verify locations:
* CAfile: /etc/ssl/cert.pem
* CApath: none
* (304) (OUT), TLS handshake, Client hello (1):
* (304) (IN), TLS handshake, Server hello (2):
* TLSv1.2 (IN), TLS handshake, Certificate (11):
* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
* TLSv1.2 (IN), TLS handshake, Server finished (14):
* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
* TLSv1.2 (OUT), TLS change cipher, Change cipher spec (1):
* TLSv1.2 (OUT), TLS handshake, Finished (20):
* TLSv1.2 (IN), TLS change cipher, Change cipher spec (1):
* TLSv1.2 (IN), TLS handshake, Finished (20):
* SSL connection using TLSv1.2 / ECDHE-ECDSA-AES256-GCM-SHA384
* Server certificate:
* subject: C=AU; ST=Queensland; L=Brisbane; O=INSECURE EXAMPLE; OU=kanidm; CN=idm.example.com
* start date: Sep 20 09:28:18 2022 GMT
* expire date: Oct 21 09:28:18 2022 GMT
* SSL certificate verify result: self signed certificate in certificate chain (19), continuing anyway.
> GET /status HTTP/1.1
> Host: idm.example.com:8443
> User-Agent: curl/7.79.1
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< cache-control: no-store, max-age=0
< content-length: 4
< content-type: application/json
< date: Tue, 20 Sep 2022 11:52:23 GMT
< pragma: no-cache
< set-cookie: kanidm-session=+LQJKwL0UdAEMoTc0Zrgne2hU+N2nB+Lcf+J1OoI9n4%3DNE7xuL9yCq7B0Ai+IM3gq5T+YZ0ckDuDoWZKzhPMHmSk3oFSscp9vy9n2a5bBFjWKgeNwdLzRbYc4rvMqYi11A%3D%3D; HttpOnly; SameSite=Strict; Secure; Path=/; Expires=Wed, 21 Sep 2022 11:52:23 GMT
< x-content-type-options: nosniff
< x-kanidm-opid: 8b25f050-7f6e-4ce1-befe-90be3c4f8a98
<
* Connection #0 to host localhost left intact
true