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

Docs update (#400)

Browse source 
* I couldn't help it - minor spelling fixes
This commit is contained in:
James Hodgkinson 2021-04-06 10:08:36 +10:00 committed by GitHub
parent 0ac5da855f
commit f466e2a521
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
12 changed files with 183 additions and 178 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
README.md
View file

@ -63,13 +63,13 @@ all backgrounds.
### Currently Working On ### Currently Working On
* CLI for administration * CLI for administration
* WebUI for self service with wifi enrollment, claim management and more. * WebUI for self-service with wifi enrollment, claim management and more.
* RBAC/Claims/Policy (limited by time and credential scope) * RBAC/Claims/Policy (limited by time and credential scope)
### Upcoming Focus Areas ### Upcoming Focus Areas
* OIDC/Oauth * OIDC/Oauth
* Replication (async multiple active write servers, read only servers) * Replication (async multiple active write servers, read-only servers)
### Future ### Future
@ -81,7 +81,7 @@ all backgrounds.
## Some key project ideas ## Some key project ideas
* All people should be respected and able to be respresented securely. * All people should be respected and able to be represented securely.
* Devices represent users and their identities - they are part of the authentication. * 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. * 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. * The system should be easy to understand and reason about for users and admins.
@ -97,5 +97,5 @@ all backgrounds.
The original project name was rsidm while it was a thought experiment. Now that it's growing 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. 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. IDM is the common industry term for identity management services.

15
kanidm_book/src/administrivia.md
View file

@ -71,7 +71,7 @@ you can then rename the domain with the commands as follows:
In some (rare) cases you may need to reindex. In some (rare) cases you may need to reindex.
Please note the server will sometimes reindex on startup as a result of the project Please note the server will sometimes reindex on startup as a result of the project
changing it's internal schema definitions. This is normal and expected - you may never need changing its internal schema definitions. This is normal and expected - you may never need
to start a reindex yourself as a result! to start a reindex yourself as a result!
You'll likely notice a need to reindex if you add indexes to schema and you see a message in your logs such as: You'll likely notice a need to reindex if you add indexes to schema and you see a message in your logs such as:
@ -80,8 +80,8 @@ You'll likely notice a need to reindex if you add indexes to schema and you see
Index {type} {attribute} not found Index {type} {attribute} not found
This indicates that an index of type equality has been added for name, but the indexing process This indicates that an index of type equality has been added for name, but the indexing process
has not been run - the server will continue to operate and the query execution code will correctly has not been run. The server will continue to operate and the query execution code will correctly
process the query however it will not be the optimal method of delivering the results as we need to process the query - however it will not be the optimal method of delivering the results as we need to
disregard this part of the query and act as though it's un-indexed. disregard this part of the query and act as though it's un-indexed.
Reindexing will resolve this by forcing all indexes to be recreated based on their schema Reindexing will resolve this by forcing all indexes to be recreated based on their schema
@ -96,9 +96,10 @@ Generally, reindexing is a rare action and should not normally be required.
# Vacuum # Vacuum
Vacuuming is the process of reclaiming un-used pages from the sqlite freelists, as well as performing [Vacuuming](https://www.sqlite.org/lang_vacuum.html) is the process of reclaiming un-used pages
some data reordering tasks that may make some queries more efficient . It is recommended that you from the sqlite freelists, as well as performing some data reordering tasks that may make some
vacuum after a reindex is performed or when you wish to reclaim space in the database file. queries more efficient . It is recommended that you vacuum after a reindex is performed or
when you wish to reclaim space in the database file.
Vacuum is also able to change the pagesize of the database. After changing db\_fs\_type (which affects Vacuum is also able to change the pagesize of the database. After changing db\_fs\_type (which affects
pagesize) in server.toml, you must run a vacuum for this to take effect. pagesize) in server.toml, you must run a vacuum for this to take effect.
@ -129,7 +130,7 @@ If you have errors, please contact the project to help support you to resolve th
# Raw actions # Raw actions
The server has a low-level stateful API you can use for more complex or advanced tasks on large numbers The server has a low-level stateful API you can use for more complex or advanced tasks on large numbers
of entries at once. Some examples are below, but generally we advise you to use the apis as listed of entries at once. Some examples are below, but generally we advise you to use the APIs as listed
above. above.
# Create from json (group or account) # Create from json (group or account)

54
kanidm_book/src/client_tools.md
View file

@ -1,34 +1,15 @@
# Interacting with the Server # Interacting with the Server
To interact with Kanidm as an administration, you'll need to use our command line tools To interact with Kanidm as an administrator, you'll need to use our command line tools.
## From (experimental) packages ## From (experimental) packages
Kanidm currently supports: Kanidm currently supports:
* Fedora 33 * Fedora 33
* OpenSUSE leap 15.2 * OpenSUSE Leap 15.2
* Tumbleweed * OpenSUSE Tumbleweed
### OpenSUSE Tumbleweed
Kanidm is part of OpenSUSE Tumbleweed since October 2020. This means you can install
the clients with:
zypper ref
zypper in kanidm-clients
### OpenSUSE Leap 15.2
Leap 15.2 is still not fully supported with Kanidm. For an experimental client, you can
try the development repository. Using zypper you can add the repository with:
zypper ar obs://home:firstyear:kanidm home_firstyear_kanidm
zypper mr -f home_firstyear_kanidm
Then you need to referesh your metadata and install the clients.
zypper ref
zypper in kanidm-clients
### Fedora ### Fedora
@ -41,14 +22,35 @@ You can then install with:
dnf install kanidm-clients dnf install kanidm-clients
### OpenSUSE Leap 15.2
Leap 15.2 is still not fully supported with Kanidm. For an experimental client, you can
try the development repository. Using zypper you can add the repository with:
zypper ar obs://home:firstyear:kanidm home_firstyear_kanidm
zypper mr -f home_firstyear_kanidm
Then you need to refresh your metadata and install the clients.
zypper ref
zypper in kanidm-clients
### OpenSUSE Tumbleweed
Kanidm is part of OpenSUSE Tumbleweed since October 2020. This means you can install
the clients with:
zypper ref
zypper in kanidm-clients
## From source ## From source
After you check out the source (see github), navigate to: After you check out the source (see [GitHub](https://github.com/kanidm/kanidm)), navigate to:
cd kanidm_tools cd kanidm_tools
cargo install --path . cargo install --path .
## Check the tools work ## Checking that the tools work
Now you can check your instance is working. You may need to provide a CA certificate for verification Now you can check your instance is working. You may need to provide a CA certificate for verification
with the -C parameter: with the -C parameter:
@ -57,7 +59,7 @@ with the -C parameter:
kanidm self whoami -C ../path/to/ca.pem -H https://localhost:8443 --name anonymous kanidm self whoami -C ../path/to/ca.pem -H https://localhost:8443 --name anonymous
kanidm self whoami -H https://localhost:8443 --name anonymous kanidm self whoami -H https://localhost:8443 --name anonymous
Now you can take some time to look at what commands are available - please ask for help at anytime. Now you can take some time to look at what commands are available - please [ask for help at any time](https://github.com/kanidm/kanidm#getting-in-contact--questions).
## Authenticating a user with the command line ## Authenticating a user with the command line

2
kanidm_book/src/installing_the_server.md
View file

@ -114,7 +114,7 @@ in place you can use a shell container that mounts the volume such as:
## Configuration ## Configuration
You will also need a config file in the volume named `server.toml` (Within the container it should be You will also need a config file in the volume named `server.toml` (Within the container it should be
`/data/server.toml`). It's contents should be as follows: `/data/server.toml`). Its contents should be as follows:
# The webserver bind address. Will use HTTPS if tls_* is provided. # The webserver bind address. Will use HTTPS if tls_* is provided.
# Defaults to "127.0.0.1:8443" # Defaults to "127.0.0.1:8443"

42
kanidm_book/src/intro.md
View file

@ -3,30 +3,30 @@
Kanidm is an identity management server, acting as an authority on accounts and authorisation Kanidm is an identity management server, acting as an authority on accounts and authorisation
within a technical environment. within a technical environment.
The intent of the Kanidm project is: The intent of the Kanidm project is to:
* To provide a single truth source for accounts, groups and privileges. * Provide a single truth source for accounts, groups and privileges.
* To enable integrations to systems and services so they can authenticate accounts. * Enable integrations to systems and services so they can authenticate accounts.
* To make system, network, application and web authentication easy and accessible. * Make system, network, application and web authentication easy and accessible.
> **NOTICE:** > **NOTICE:**
> This is a pre-release project. While all effort has been made to ensure no dataloss > This is a pre-release project. While all effort has been made to ensure no data loss
> or security flaws, you should still be careful when using this in your environment. > or security flaws, you should still be careful when using this in your environment.
## Why do I want Kanidm? ## Why do I want Kanidm?
Whether you work in a business, a volunteer organisation, or an enthusiast who manages some Whether you work in a business, a volunteer organisation, or are an enthusiast who manages
of their own personal services, we need methods of authenitcating and identifying ourselves their personal services, we need methods of authenticating and identifying ourselves
to these systems, and subsequently a way a determine what authorisation and privieleges we have to these systems and subsequently, ways to determine what authorisation and privileges we have
while accessing these systems. while accessing these systems.
We've probably all been in work places where you end up with multiple accounts on various We've probably all been in workplaces where you end up with multiple accounts on various
systems - one for a workstation, different ssh keys for different tasks, maybe some shared 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 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 and what they have access to, but it also means that sometimes these credentials have more
access or privelege than they require. access or privilege than they require.
Kanidm acts as a central authority of accounts in your organisation, and allows each account to associate 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: many devices and credentials with different privileges. An example of how this looks:
┌──────────────────┐ ┌──────────────────┐
@ -74,18 +74,16 @@ many devices and credentials with different privileges. An example of how this l
│ You │ │ You │
└──────────┘ └──────────┘
A key design goal is that you authenticate to your device in some manner, and then your device will A key design goal is that you authenticate with 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, 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 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. 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 This helps improve security; a compromise of the service or the network transmission does not
grant you unlimited access to your account and all it's privileges. As the credentials are specific grant you unlimited access to your account and all its 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 to a device, if a device is compromised you can revoke its associated credentials. If a
specific service is compromised, only the credentials for that service need to be revoked. 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, 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 workflows and automation are added or designed to reduce human handling. An example of this
is the use of qr codes with deployment profiles to automatically enroll wireless credentials. is the use of QR codes with deployment profiles to automatically enrol wireless credentials.

33
kanidm_book/src/ldap.md
View file

@ -3,7 +3,7 @@
While many applications can support systems like SAML or OAuth, many do not. LDAP While many applications can support systems like SAML or OAuth, many do not. LDAP
has been the "lingua franca" of authentication for many years, with almost has been the "lingua franca" of authentication for many years, with almost
every application in the world being able to search and bind to LDAP. As there every application in the world being able to search and bind to LDAP. As there
are still many of these in the world, Kanidm has the ability to host a read-only are still many of these in the world, Kanidm can host a read-only
LDAP interface. LDAP interface.
> **WARNING** The LDAP server in Kanidm is not RFC compliant. This > **WARNING** The LDAP server in Kanidm is not RFC compliant. This
@ -21,20 +21,19 @@ many applications - an IDM just like Kanidm!
## Data Mapping ## Data Mapping
Kanidm is not able to be mapped 100% to LDAP's objects. This is because LDAP Kanidm is not able to be mapped 100% to LDAP's objects. This is because LDAP
types are simple key-values on objects which are all UTF8 strings or subsets types are simple key-values on objects which are all UTF8 strings (or subsets
of based on validation (matching) rules. Kanidm internally implements complex thereof) based on validation (matching) rules. Kanidm internally implements complex
datatypes such as taging on SSH keys, or multi-value credentials. These can not data types such as tagging on SSH keys, or multi-value credentials. These can not
be represented in LDAP. be represented in LDAP.
As well many of the structures in Kanidm don't correlate closely to LDAP. For example As well many of the structures in Kanidm don't correlate closely to LDAP. For example
Kanidm only has a gidnumber, where LDAP's schema's define uidnumber and gidnumber. Kanidm only has a gidnumber, where LDAP's schema's define uidnumber and gidnumber.
Entries in the database also have a specific name in LDAP, related to their path Entries in the database also have a specific name in LDAP, related to their path
in the directory tree. Kanidm is a flat model, so we have to emulate some tree like in the directory tree. Kanidm is a flat model, so we have to emulate some tree-like
elements, and ignore others. elements, and ignore others.
For this reason, when you search the ldap interface, Kanidm will make some mappinng For this reason, when you search the LDAP interface, Kanidm will make some mapping decisions.
decisions.
* Queries requesting objectClass/EntryUUID will be mapped to class/uuid * Queries requesting objectClass/EntryUUID will be mapped to class/uuid
* Entry attributes to LDAP may be renamed for presentation to LDAP clients (ie class to ObjectClass) * Entry attributes to LDAP may be renamed for presentation to LDAP clients (ie class to ObjectClass)
@ -45,7 +44,7 @@ decisions.
* The Kanidm domain name is used to generate the basedn. * The Kanidm domain name is used to generate the basedn.
These decisions were made to make the path as simple and effective as possible, These decisions were made to make the path as simple and effective as possible,
relying more on the kanidm query and filter system than attempting to generate a tree like relying more on the kanidm query and filter system than attempting to generate a tree-like
representation of data. As almost all clients can use filters for entry selection representation of data. As almost all clients can use filters for entry selection
we don't believe this is a limitation for consuming applications. we don't believe this is a limitation for consuming applications.
@ -62,15 +61,15 @@ of the Kanidm system to secure data and authentication.
### Access Controls ### Access Controls
LDAP only supports password authentication. As LDAP is used heavily in posix environments LDAP only supports password authentication. As LDAP is used heavily in posix environments
the LDAP bind for any DN will use it's configured posix password. the LDAP bind for any DN will use its configured posix password.
As the posix password is not eqivalent in strength to the primary credentials of Kanidm As the posix password is not equivalent in strength to the primary credentials of Kanidm
(which may be MFA), the LDAP bind does not grant rights to elevated read permissions. (which may be MFA), the LDAP bind does not grant rights to elevated read permissions.
All binds, have the permissions of "Anonymous" (even if the anonymous account is locked). All binds have the permissions of "Anonymous" (even if the anonymous account is locked).
## Server Configuration ## Server Configuration
To configure Kanidm to provide LDAP you add the argument to the server.toml configuration: To configure Kanidm to provide LDAP you add the argument to the `server.toml` configuration:
ldapbindaddress = "127.0.0.1:3636" ldapbindaddress = "127.0.0.1:3636"
@ -79,7 +78,7 @@ material.
## Example ## Example
Given a default install with domain "example.com" the configured LDAP dn will be "dc=example,dc=com". Given a default install with domain "example.com" the configured LDAP DN will be "dc=example,dc=com".
This can be queried with: This can be queried with:
cargo run -- server -D kanidm.db -C ca.pem -c cert.pem -k key.pem -b 127.0.0.1:8443 -l 127.0.0.1:3636 cargo run -- server -D kanidm.db -C ca.pem -c cert.pem -k key.pem -b 127.0.0.1:8443 -l 127.0.0.1:3636
@ -100,9 +99,9 @@ This can be queried with:
It is recommended that client applications filter accounts that can login with '(class=account)' It is recommended that client applications filter accounts that can login with '(class=account)'
and groups with '(class=group)'. If possible, group membership is defined in rfc2307bis or and groups with '(class=group)'. If possible, group membership is defined in rfc2307bis or
Active Directory style. This means groups are determined from the "memberof" attribute which contains Active Directory style. This means groups are determined from the "memberof" attribute which contains
a dn to a group. a DN to a group.
LDAP binds can use any unique identifier of the account. The following are all valid bind dn's for LDAP binds can use any unique identifier of the account. The following are all valid bind DN's for
the object listed above (if it was a posix account that is). the object listed above (if it was a posix account that is).
ldapwhoami ... -x -D 'name=test1' ldapwhoami ... -x -D 'name=test1'
@ -127,8 +126,8 @@ All give the same error:
This is despite the fact: This is despite the fact:
* The first command is a certificate validation error * The first command is a certificate validation error
* The second is a missing ldaps on a TLS port * The second is a missing LDAPS on a TLS port
* The third is an incorrect port * The third is an incorrect port
To diganose errors like this you may need "-d 1" for your ldap commands or client. To diagnose errors like this, you may need to add "-d 1" to your LDAP commands or client.

37
kanidm_book/src/pam_and_nsswitch.md
View file

@ -1,6 +1,6 @@
# Pam and nsswitch # PAM and nsswitch
Pam and nsswitch are the core mechanisms used by Linux and Bsd clients PAM and nsswitch are the core mechanisms used by Linux and BSD clients
to resolve identities from an IDM service like kanidm into accounts that to resolve identities from an IDM service like kanidm into accounts that
can be used on the machine for various interactive tasks. can be used on the machine for various interactive tasks.
@ -11,10 +11,11 @@ and nsswitch integration. This is provided as the daemon can cache the accounts
for users who have unreliable networks or leave the site where kanidm is. The for users who have unreliable networks or leave the site where kanidm is. The
cache is also able to cache missing-entry responses to reduce network traffic cache is also able to cache missing-entry responses to reduce network traffic
and main server load. and main server load.
Additionally, the daemon means that the pam and nsswitch integration libraries Additionally, the daemon means that the pam and nsswitch integration libraries
can be small, helping to reduce the attack surface of the machine. can be small, helping to reduce the attack surface of the machine.
Similar, a tasks daemon is also provided that can create home directories on first Similarly, a tasks daemon is available that can create home directories on first
login, and supports a number of features related to aliases and links to these login and supports several features related to aliases and links to these
home directories. home directories.
We recommend you install the client daemon from your system package manager. We recommend you install the client daemon from your system package manager.
@ -32,6 +33,7 @@ You can check the privileged tasks daemon is running with
systemctl status kanidm-unixd-tasks systemctl status kanidm-unixd-tasks
> **NOTE** The `kanidm_unixd_tasks` daemon is not required for pam and nsswitch functionality. > **NOTE** The `kanidm_unixd_tasks` daemon is not required for pam and nsswitch functionality.
> If disabled, your system will function as usual. It is however recommended due to the features > If disabled, your system will function as usual. It is however recommended due to the features
> it provides supporting kanidm's capabilities. > it provides supporting kanidm's capabilities.
@ -115,16 +117,16 @@ You can also do the same for groups.
> **WARNING:** Modifications to pam configuration *may* leave your system in a state > **WARNING:** Modifications to pam configuration *may* leave your system in a state
> where you are unable to login or authenticate. You should always have a recovery > where you are unable to login or authenticate. You should always have a recovery
> shell open while making changes (ie root), or have access to single-user mode > shell open while making changes (ie root), or have access to single-user mode
> at the machines console. > at the machine's console.
PAM (Pluggable Authentication Modules) is how a unix like system allows users to authenticate PAM (Pluggable Authentication Modules) is how a unix-like system allows users to authenticate
and be authorised to start interactive sessions. This is configured through a stack of modules and be authorised to start interactive sessions. This is configured through a stack of modules
that are executed in order to evaluate the request. This is done through a series of steps that are executed in order to evaluate the request. This is done through a series of steps
where each module may request or reused authentication token information. where each module may request or reuse authentication token information.
### Before you start ### Before you start
You *should* backup your /etc/pam.d directory from it's original state as you *may* change the You *should* backup your /etc/pam.d directory from its original state as you *may* change the
pam config in a way that will cause you to be unable to authenticate to your machine. pam config in a way that will cause you to be unable to authenticate to your machine.
cp -a /etc/pam.d /root/pam.d.backup cp -a /etc/pam.d /root/pam.d.backup
@ -167,8 +169,8 @@ Each of these controls one of the four stages of pam. The content should look li
session optional pam_umask.so session optional pam_umask.so
session optional pam_env.so session optional pam_env.so
> **WARNING:** Ensure that `pam_mkhomedir` or `pam_oddjobd` are *not* present in your pam configuration > **WARNING:** Ensure that `pam_mkhomedir` or `pam_oddjobd` are *not* present in your
> these interfer with the correct operation of the kanidm tasks daemon. > pam configuration, as they interfere with the correct operation of the kanidm tasks daemon.
### Fedora 33 ### Fedora 33
@ -176,7 +178,7 @@ Each of these controls one of the four stages of pam. The content should look li
> run the daemon with permissive mode for the unconfined_service_t daemon type. To do this run: > run the daemon with permissive mode for the unconfined_service_t daemon type. To do this run:
> `semanage permissive -a unconfined_service_t`. To undo this run `semanage permissive -d unconfined_service_t`. > `semanage permissive -a unconfined_service_t`. To undo this run `semanage permissive -d unconfined_service_t`.
> >
> You may also need to run "audit2allow" for sshd and other types to be able to access the unix daemon sockets. > You may also need to run `audit2allow` for sshd and other types to be able to access the unix daemon sockets.
These files are managed by authselect as symlinks. You will need to remove the symlinks first, then These files are managed by authselect as symlinks. You will need to remove the symlinks first, then
edit the content. edit the content.
@ -286,10 +288,11 @@ You should have:
In some high latency environments, you may need to increase the connection timeout. We set In some high latency environments, you may need to increase the connection timeout. We set
this low to improve response on LANs, but over the internet this may need to be increased. this low to improve response on LANs, but over the internet this may need to be increased.
By increasing the conn timeout, you will be able to operate on higher latency links, but By increasing the conn timeout, you will be able to operate on higher latency links, but
some operations may take longer to complete causing a degree of latency. By increasing the some operations may take longer to complete causing a degree of latency.
cache_timeout, you will need to refresh "less" but it may mean on an account lockout or
group change, that you need up to cache_timeout to see the effect (this has security By increasing the cache_timeout, you will need to refresh "less" but it may mean on an
implications) account lockout or group change, that you need to wait until cache_timeout to see the effect
(this has security implications)
# /etc/kanidm/unixd # /etc/kanidm/unixd
# Seconds # Seconds
@ -307,11 +310,11 @@ You can clear (wipe) the cache with:
$ kanidm_cache_clear $ kanidm_cache_clear
There is an important distinction between these two - invalidate cache items may still There is an important distinction between these two - invalidated cache items may still
be yielded to a client request if the communication to the main kanidm server is not be yielded to a client request if the communication to the main kanidm server is not
possible. For example, you may have your laptop in a park without wifi. possible. For example, you may have your laptop in a park without wifi.
Clearing the cache however, completely wipes all local data about all accounts and groups. Clearing the cache, however, completely wipes all local data about all accounts and groups.
If you are relying on this cached (but invalid data) you may lose access to your accounts until If you are relying on this cached (but invalid data) you may lose access to your accounts until
other communication issues have been resolved. other communication issues have been resolved.

67
kanidm_book/src/posix_accounts.md
View file

@ -1,32 +1,32 @@
# Posix Accounts and Groups # POSIX Accounts and Groups
Kanidm has features that enable it's accounts and groups to be consumed on Kanidm has features that enable its accounts and groups to be consumed on
posix like machines, such as Linux, FreeBSD, or others. POSIX-like machines, such as Linux, FreeBSD, or others.
## Notes on Posix Features ## Notes on POSIX Features
There are a number of design decisions that have been made in the posix features Many design decisions have been made in the POSIX features
of kanidm that are intended to make distributed systems easier to manage, and of kanidm that are intended to make distributed systems easier to manage and
client systems more secure. client systems more secure.
### Uid and Gid numbers ### UID and GID numbers
In Kanidm there is no difference between a uid and a gid number. On most unix systems In Kanidm there is no difference between a UID and a GID number. On most UNIX systems
a user will create all files with a primary user and group. The primary group is a user will create all files with a primary user and group. The primary group is
effectively equivalent to the permissions of the user. It is very easy to see scenarioes effectively equivalent to the permissions of the user. It is very easy to see scenarios
where someone may change the account to have a shared primary group (ie allusers), where someone may change the account to have a shared primary group (ie `allusers`),
but without change the umask all client systems. This can cause user's data to be but without changing the umask on all client systems. This can cause users' data to be
compromised by any member of the same shared group. compromised by any member of the same shared group.
To prevent this many system create a user private group, or UPG. This group has the To prevent this, many systems create a "user private group", or UPG. This group has the
gid number match the uid number of the user, and the user set's it's primary gidnumber matching the uidnumber of the user, and the user sets its primary
group id to the gid number of the UPG. group id to the gidnumber of the UPG.
As there is now an equivalence between the uid and gid number of the user and the UPG, As there is now an equivalence between the UID and GID number of the user and the UPG,
there is no benefit to seperating these values. As a result kanidm accounts *only* there is no benefit to separating these values. As a result kanidm accounts *only*
have a gidnumber, which is also considered to be it's uidnumber as well. This has a benefit have a gidnumber, which is also considered to be its uidnumber as well. This has the benefit
of preventing accidental creation of a separate group that has an overlapping gidnumber of preventing the accidental creation of a separate group that has an overlapping gidnumber
(the uniqueness attribute of the schema will block the creation). (the `uniqueness` attribute of the schema will block the creation).
### UPG generation ### UPG generation
@ -41,33 +41,32 @@ two independent items. For example in /etc/passwd and /etc/group
Other systems like FreeIPA use a plugin that generates a UPG as a database record on Other systems like FreeIPA use a plugin that generates a UPG as a database record on
creation of the account. creation of the account.
Kanidm does neither of these. As the gidnumber of the user must by unique, and a user Kanidm does neither of these. As the gidnumber of the user must be unique, and a user
implies the UPG must exist, we are able to generate UPG's on demand from the account. implies the UPG must exist, we can generate UPG's on-demand from the account.
This has a single side effect, which is that you are unable to add any members to a This has a single side effect - that you are unable to add any members to a
UPG - however, given the nature of a user private group, this is somewhat the point. UPG - given the nature of a user private group, this is the point.
### Gid number generation ### gidnumber generation
In the future Kanidm plans to have async replication as a feature between writable In the future, Kanidm plans to have asynchronous replication as a feature between writable
database servers. In this case we need to be able to allocate stable and reliable database servers. In this case, we need to be able to allocate stable and reliable
gidnumbers to accounts on replicas that may not be in continual communication. gidnumbers to accounts on replicas that may not be in continual communication.
To do this, we use the last 32 bits of the account or group's UUID to generate the To do this, we use the last 32 bits of the account or group's UUID to generate the
gidnumber. gidnumber.
A valid concern is possibility of duplication in the lower 32 bits. Given the A valid concern is the possibility of duplication in the lower 32 bits. Given the
birthday problem, if you have 77,000 groups and accounts, you have a 50% chance birthday problem, if you have 77,000 groups and accounts, you have a 50% chance
of duplication. With 50,000 you have 20% chance, 9,300 you have a 1% chance and of duplication. With 50,000 you have a 20% chance, 9,300 you have a 1% chance and
with 2900 you have 0.1% chance. with 2900 you have a 0.1% chance.
We advise that if you have a site with >10,000 users you should use an external system We advise that if you have a site with >10,000 users you should use an external system
to allocate gidnumbers serially or in a consistent manner to avoid potential duplication to allocate gidnumbers serially or consistently to avoid potential duplication events.
events.
This design decision is made as most small sites will benefit greatly from the This design decision is made as most small sites will benefit greatly from the
autoallocation policy and the simplicity of it's design, while larger enterprises autoallocation policy and the simplicity of its design, while larger enterprises
will already have IDM or Business process applications for HR/People that are will already have IDM or Business process applications for HR/People that are
capable of suppling this kind of data in batch jobs. capable of supplying this kind of data in batch jobs.
## Enabling Posix Attributes on Accounts ## Enabling Posix Attributes on Accounts
@ -101,4 +100,4 @@ You can view the accounts posix token details with:
kanidm group posix show --name anonymous demo_group kanidm group posix show --name anonymous demo_group
Posix enabled groups will supply their members as posix members to clients. There is no Posix enabled groups will supply their members as posix members to clients. There is no
special or seperate type of membership for posix members required. special or separate type of membership for posix members required.

95
kanidm_book/src/radius.md
View file

@ -1,13 +1,13 @@
# RADIUS # RADIUS
RADIUS is a network-protocol that is commonly used to allow wifi devices or RADIUS is a network protocol that is commonly used to allow wifi devices or
vpn's to authenticate users to a network boundary. While it should not be a VPN's to authenticate users to a network boundary. While it should not be a
sole point of trust/authentication to an identity, it's still an important sole point of trust/authentication to an identity, it's still an important
control for improving barriers to attackers access to network resources. control for improving barriers to attackers access to network resources.
Kanidm has a philosophy that each account can have multiple credentials which Kanidm has a philosophy that each account can have multiple credentials which
are related to their devices and limited to specific resources. RADIUS is are related to their devices and limited to specific resources. RADIUS is
no exception, and has a seperate credential for each account to use for no exception and has a separate credential for each account to use for
RADIUS access. RADIUS access.
## Disclaimer ## Disclaimer
@ -19,7 +19,7 @@ It's worth noting some disclaimers about Kanidm's RADIUS integration here
Kanidm normally attempts to have credentials for each *device* and *application* Kanidm normally attempts to have credentials for each *device* and *application*
rather than the legacy model of one to one. rather than the legacy model of one to one.
RADIUS as a protocol is only able to attest a *single* credential in an authentication The RADIUS protocol is only able to attest a *single* credential in an authentication
attempt, which limits us to storing a single RADIUS credential per account. However attempt, which limits us to storing a single RADIUS credential per account. However
despite this limitation, it still greatly improves the situation by isolating the despite this limitation, it still greatly improves the situation by isolating the
RADIUS credential from the primary or application credentials of the account. This RADIUS credential from the primary or application credentials of the account. This
@ -30,31 +30,34 @@ authenticate to wifi with expired credentials.
### Cleartext Credential Storage ### Cleartext Credential Storage
RADIUS offers many different types of tunnels and authentication mechanisms. RADIUS offers many different types of tunnels and authentication mechanisms.
However, most client devices "out of the box" when you select a WPA2-Enterprise However, most client devices "out of the box" only attempt a single type when you select
network only attempt a single type: MSCHAPv2 with PEAP. This is a challenge a WPA2-Enterprise network: MSCHAPv2 with PEAP. This is a challenge-response protocol
response protocol which requires cleartext or ntlm credentials. that requires cleartext or NTLM credentials.
As MSCHAPv2 with PEAP is the only practical, universal RADIUS type supported As MSCHAPv2 with PEAP is the only practical, universal RADIUS type supported
on all devices with "minimal" configuration, we consider it imperitive on all devices with "minimal" configuration, we consider it imperative
that it MUST be supported as the default. Esoteric RADIUS types can be used that it MUST be supported as the default. Esoteric RADIUS types can be used
as well, but this is up to administrators to test and configure. as well, but this is up to administrators to test and configure.
Due to this requirement, we must store the RADIUS material as cleartext or Due to this requirement, we must store the RADIUS material as cleartext or
ntlm hashes. It would be silly to think that ntlm is "secure" as it's md4 NTLM hashes. It would be silly to think that NTLM is "secure" as it's md4
which is only an illusion of security. which is only an illusion of security.
This means, Kanidm stores RADIUS credentials in the database is cleartext. This means Kanidm stores RADIUS credentials in the database as cleartext.
We believe this is a reasonable decision and is a low risk to security as: We believe this is a reasonable decision and is a low risk to security as:
* The access controls around radius secret by default are "strong", limited to only self-account read and radius-server read. * The access controls around RADIUS secrets by default are "strong", limited
* As RADIUS credentials are seperate to the primary account credentials, and have no other rights, their disclosure is not going to lead to a full compromise account. to only self-account read and RADIUS-server read.
* Having the credentials in cleartext allows a better user experience as clients can view the credentials at anytime to enroll further devices. * As RADIUS credentials are separate from the primary account credentials and have
no other rights, their disclosure is not going to lead to a full account compromise.
* Having the credentials in cleartext allows a better user experience as clients
can view the credentials at any time to enrol further devices.
## Account Credential Configuration ## Account Credential Configuration
For an account to use RADIUS they must first generate a RADIUS secret unique to For an account to use RADIUS they must first generate a RADIUS secret unique to
that account. By default all accounts can self-create this secret. that account. By default, all accounts can self-create this secret.
kanidm account radius generate_secret --name william william kanidm account radius generate_secret --name william william
kanidm account radius show_secret --name william william kanidm account radius show_secret --name william william
@ -63,8 +66,8 @@ that account. By default all accounts can self-create this secret.
Kanidm enforces that accounts which can authenticate to RADIUS must be a member Kanidm enforces that accounts which can authenticate to RADIUS must be a member
of an allowed group. This allows you to define which users or groups may use of an allowed group. This allows you to define which users or groups may use
wifi or VPN infrastructure, and gives a path for "revoking" access to the resources wifi or VPN infrastructure and gives a path for "revoking" access to the resources
through group management. The key point of this, is that service accounts should through group management. The key point of this is that service accounts should
not be part of this group. not be part of this group.
kanidm group create --name idm_admin radius_access_allowed kanidm group create --name idm_admin radius_access_allowed
@ -72,7 +75,7 @@ not be part of this group.
## RADIUS Server Service Account ## RADIUS Server Service Account
To read these secrets, the radius server requires an account with the To read these secrets, the RADIUS server requires an account with the
correct privileges. This can be created and assigned through the group correct privileges. This can be created and assigned through the group
"idm_radius_servers" which is provided by default. "idm_radius_servers" which is provided by default.
@ -82,47 +85,47 @@ correct privileges. This can be created and assigned through the group
## Deploying a RADIUS Container ## Deploying a RADIUS Container
We provide a RADIUS container that has all the needed integrations. This container We provide a RADIUS container that has all the needed integrations.
requires some cryptographic material, laid out in a volume like so: This container requires some cryptographic material, laid out in a volume like so:
data data
data/ca.pem # This is the kanidm ca.pem data/ca.pem # This is the kanidm ca.pem
data/config.ini # This is the kanidm-radius configuration. data/config.ini # This is the kanidm-radius configuration.
data/certs data/certs
data/certs/dh # openssl dhparam -out ./dh 2048 data/certs/dh # openssl dhparam -out ./dh 2048
data/certs/key.pem # These are the radius ca/cert/key data/certs/key.pem # These are the radius ca/cert/key
data/certs/cert.pem data/certs/cert.pem
data/certs/ca.pem data/certs/ca.pem
The config.ini has the following template: The config.ini has the following template:
[kanidm_client] [kanidm_client]
url = # URL to the kanidm server url = # URL to the kanidm server
strict = false # Strict CA verification strict = false # Strict CA verification
ca = /data/ca.pem # Path to the kanidm ca ca = /data/ca.pem # Path to the kanidm ca
user = # Username of the RADIUS service account user = # Username of the RADIUS service account
secret = # Generated secret for the service account secret = # Generated secret for the service account
; default vlans for groups that don't specify one. ; default VLANs for groups that don't specify one.
[DEFAULT] [DEFAULT]
vlan = 1 vlan = 1
; [group.test] # group.<name> will have these options applied ; [group.test] # group.<name> will have these options applied
; vlan = ; vlan =
[radiusd] [radiusd]
ca = # Path to the radius server's CA ca = # Path to the radius server's CA
key = # Path to the radius servers key key = # Path to the radius servers key
cert = # Path to the radius servers cert cert = # Path to the radius servers cert
dh = # Path to the radius servers dh params dh = # Path to the radius servers dh params
required_group = # name of a kanidm group which you must be a member of to required_group = # Name of a kanidm group which you must be
# use radius. # A member of to use radius.
cache_path = # A path to an area where cached user records can be stored. cache_path = # A path to an area where cached user records can be stored.
# If in doubt, use /dev/shm/kanidmradiusd # If in doubt, use /dev/shm/kanidmradiusd
; [client.localhost] # client.<nas name> configures wifi/vpn consumers ; [client.localhost] # client.<nas name> configures wifi/vpn consumers
; ipaddr = # ipv4 or ipv6 address of the NAS ; ipaddr = # ipv4 or ipv6 address of the NAS
; secret = # shared secret ; secret = # Shared secret
A fully configured example is: A fully configured example is:
@ -130,10 +133,10 @@ A fully configured example is:
; be sure to check the listening port is correct, it's the docker internal port ; be sure to check the listening port is correct, it's the docker internal port
; not the external one if these containers are on the same host. ; not the external one if these containers are on the same host.
url = https://<kanidmd container name or ip>:8443 url = https://<kanidmd container name or ip>:8443
strict = true # adjust this if you have ca validation issues strict = true # Adjust this if you have CA validation issues
ca = /data/ca.crt ca = /data/ca.crt
user = radius_service_account user = radius_service_account
secret = # The generated password from above secret = # The generated password from above
; default vlans for groups that don't specify one. ; default vlans for groups that don't specify one.
[DEFAULT] [DEFAULT]
@ -162,12 +165,12 @@ You can then run the container with:
docker run --name radiusd -v ...:/data kanidm/radius:latest docker run --name radiusd -v ...:/data kanidm/radius:latest
Authentication can be tested through the client.localhost nas configuration with: Authentication can be tested through the client.localhost NAS configuration with:
docker exec -i -t radiusd radtest <username> badpassword 127.0.0.1 10 testing123 docker exec -i -t radiusd radtest <username> badpassword 127.0.0.1 10 testing123
docker exec -i -t radiusd radtest <username> <radius show_secret value here> 127.0.0.1 10 testing123 docker exec -i -t radiusd radtest <username> <radius show_secret value here> 127.0.0.1 10 testing123
Finally, to expose this to a wifi infrastructure, add your NAS in config.ini: Finally, to expose this to a wifi infrastructure, add your NAS in `config.ini`:
[client.access_point] [client.access_point]
ipaddr = <some ipadd> ipaddr = <some ipadd>
@ -182,5 +185,5 @@ of the problem. To increase the logging you can re-run your environment with deb
docker run --name radiusd -e DEBUG=True -i -t -v ...:/data kanidm/radius:latest docker run --name radiusd -e DEBUG=True -i -t -v ...:/data kanidm/radius:latest
Note the radius container *is* configured to provide Tunnel-Private-Group-ID so if you wish to use Note the radius container *is* configured to provide Tunnel-Private-Group-ID so if you wish to use
wifi assigned vlans on your infrastructure, you can assign these by groups in the config.ini as wifi assigned VLANs on your infrastructure, you can assign these by groups in the config.ini as
shown in the above examples. shown in the above examples.

2
kanidm_book/src/recycle_bin.md
View file

@ -5,7 +5,7 @@ recovery from mistakes for a period of time.
> **WARNING:** The recycle bin is a best effort - when recovering in some cases > **WARNING:** The recycle bin is a best effort - when recovering in some cases
> not everything can be "put back" the way it was. Be sure to check your entries > not everything can be "put back" the way it was. Be sure to check your entries
> are sane once they have been revived. > are valid once they have been revived.
## Where is the Recycle Bin? ## Where is the Recycle Bin?

2
kanidm_client/src/lib.rs
View file

@ -153,7 +153,7 @@ impl KanidmClientBuilder {
let mut f = match File::open(config_path) { let mut f = match File::open(config_path) {
Ok(f) => f, Ok(f) => f,
Err(e) => { Err(e) => {
debug!("Unabled to open config file [{:?}], skipping ...", e); debug!("Unable to open config file [{:?}], skipping ...", e);
return Ok(self); return Ok(self);
} }
}; };

2
kanidm_unix_int/src/unix_config.rs
View file

@ -84,7 +84,7 @@ impl KanidmUnixdConfig {
let mut f = match File::open(config_path) { let mut f = match File::open(config_path) {
Ok(f) => f, Ok(f) => f,
Err(e) => { Err(e) => {
debug!("Unabled to open config file [{:?}], skipping ...", e); debug!("Unable to open config file [{:?}], skipping ...", e);
return Ok(self); return Ok(self);
} }
}; };