diff --git a/README.md b/README.md index 17c50387e..cd1250045 100644 --- a/README.md +++ b/README.md @@ -63,13 +63,13 @@ all backgrounds. ### Currently Working On * 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) ### Upcoming Focus Areas * OIDC/Oauth -* Replication (async multiple active write servers, read only servers) +* Replication (async multiple active write servers, read-only servers) ### Future @@ -81,7 +81,7 @@ all backgrounds. ## 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. * 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. @@ -97,5 +97,5 @@ all backgrounds. 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. +IDM is the common industry term for identity management services. diff --git a/kanidm_book/src/administrivia.md b/kanidm_book/src/administrivia.md index f0047cbe4..a1e74d527 100644 --- a/kanidm_book/src/administrivia.md +++ b/kanidm_book/src/administrivia.md @@ -71,7 +71,7 @@ you can then rename the domain with the commands as follows: In some (rare) cases you may need to reindex. 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! 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 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 -process the query however it will not be the optimal method of delivering the results as we need to +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 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 @@ -96,9 +96,10 @@ Generally, reindexing is a rare action and should not normally be required. # Vacuum -Vacuuming is the process of reclaiming un-used pages from the sqlite freelists, as well as performing -some data reordering tasks that may make some 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. +[Vacuuming](https://www.sqlite.org/lang_vacuum.html) is the process of reclaiming un-used pages +from the sqlite freelists, as well as performing some data reordering tasks that may make some +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 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 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. # Create from json (group or account) diff --git a/kanidm_book/src/client_tools.md b/kanidm_book/src/client_tools.md index f1fab7d64..c4692492a 100644 --- a/kanidm_book/src/client_tools.md +++ b/kanidm_book/src/client_tools.md @@ -1,34 +1,15 @@ # 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 Kanidm currently supports: + * Fedora 33 - * OpenSUSE leap 15.2 - * Tumbleweed + * OpenSUSE Leap 15.2 + * 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 @@ -41,14 +22,35 @@ You can then install with: 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 -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 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 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 -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 diff --git a/kanidm_book/src/installing_the_server.md b/kanidm_book/src/installing_the_server.md index 1eff69a68..b5151bc41 100644 --- a/kanidm_book/src/installing_the_server.md +++ b/kanidm_book/src/installing_the_server.md @@ -114,7 +114,7 @@ in place you can use a shell container that mounts the volume such as: ## Configuration 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. # Defaults to "127.0.0.1:8443" diff --git a/kanidm_book/src/intro.md b/kanidm_book/src/intro.md index 8bf15ae38..c0c14179e 100644 --- a/kanidm_book/src/intro.md +++ b/kanidm_book/src/intro.md @@ -3,30 +3,30 @@ Kanidm is an identity management server, acting as an authority on accounts and authorisation 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. -* To enable integrations to systems and services so they can authenticate accounts. -* To make system, network, application and web authentication easy and accessible. +* Provide a single truth source for accounts, groups and privileges. +* Enable integrations to systems and services so they can authenticate accounts. +* 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 +> 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. ## 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 +Whether you work in a business, a volunteer organisation, or are an enthusiast who manages +their personal services, we need methods of authenticating and identifying ourselves +to these systems and subsequently, ways to determine what authorisation and privileges 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 +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 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. +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: ┌──────────────────┐ @@ -74,18 +74,16 @@ many devices and credentials with different privileges. An example of how this l │ 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 +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, +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 +This helps improve security; a compromise of the service or the network transmission does not +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 can revoke its 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. - - +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 enrol wireless credentials. diff --git a/kanidm_book/src/ldap.md b/kanidm_book/src/ldap.md index ec041f064..98e60f765 100644 --- a/kanidm_book/src/ldap.md +++ b/kanidm_book/src/ldap.md @@ -3,7 +3,7 @@ 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 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. > **WARNING** The LDAP server in Kanidm is not RFC compliant. This @@ -21,20 +21,19 @@ many applications - an IDM just like Kanidm! ## Data Mapping 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 -of based on validation (matching) rules. Kanidm internally implements complex -datatypes such as taging on SSH keys, or multi-value credentials. These can not +types are simple key-values on objects which are all UTF8 strings (or subsets +thereof) based on validation (matching) rules. Kanidm internally implements complex +data types such as tagging on SSH keys, or multi-value credentials. These can not be represented in LDAP. 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. 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. -For this reason, when you search the ldap interface, Kanidm will make some mappinng -decisions. +For this reason, when you search the LDAP interface, Kanidm will make some mapping decisions. * 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) @@ -45,7 +44,7 @@ decisions. * The Kanidm domain name is used to generate the basedn. 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 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 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. -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 -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" @@ -79,7 +78,7 @@ material. ## 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: 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)' 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 -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). ldapwhoami ... -x -D 'name=test1' @@ -127,8 +126,8 @@ All give the same error: This is despite the fact: * 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 -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. diff --git a/kanidm_book/src/pam_and_nsswitch.md b/kanidm_book/src/pam_and_nsswitch.md index 4c68abc98..fa1320a85 100644 --- a/kanidm_book/src/pam_and_nsswitch.md +++ b/kanidm_book/src/pam_and_nsswitch.md @@ -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 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 cache is also able to cache missing-entry responses to reduce network traffic and main server load. + Additionally, the daemon means that the pam and nsswitch integration libraries 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 -login, and supports a number of features related to aliases and links to these +Similarly, a tasks daemon is available that can create home directories on first +login and supports several features related to aliases and links to these home directories. 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 + > **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 > 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 > 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 -> 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 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 -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. 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_env.so -> **WARNING:** Ensure that `pam_mkhomedir` or `pam_oddjobd` are *not* present in your pam configuration -> these interfer with the correct operation of the kanidm tasks daemon. +> **WARNING:** Ensure that `pam_mkhomedir` or `pam_oddjobd` are *not* present in your +> pam configuration, as they interfere with the correct operation of the kanidm tasks daemon. ### 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: > `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 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 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 -some operations may take longer to complete causing a degree of latency. By increasing the -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 -implications) +some operations may take longer to complete causing a degree of latency. + +By increasing the cache_timeout, you will need to refresh "less" but it may mean on an +account lockout or group change, that you need to wait until cache_timeout to see the effect +(this has security implications) # /etc/kanidm/unixd # Seconds @@ -307,11 +310,11 @@ You can clear (wipe) the cache with: $ 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 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 other communication issues have been resolved. diff --git a/kanidm_book/src/posix_accounts.md b/kanidm_book/src/posix_accounts.md index 8a4a99fa8..b814e7bdb 100644 --- a/kanidm_book/src/posix_accounts.md +++ b/kanidm_book/src/posix_accounts.md @@ -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 -posix like machines, such as Linux, FreeBSD, or others. +Kanidm has features that enable its accounts and groups to be consumed on +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 -of kanidm that are intended to make distributed systems easier to manage, and +Many design decisions have been made in the POSIX features +of kanidm that are intended to make distributed systems easier to manage and 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 -effectively equivalent to the permissions of the user. It is very easy to see scenarioes -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 +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`), +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. -To prevent this many system 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 -group id to the gid number of the UPG. +To prevent this, many systems create a "user private group", or UPG. This group has the +gidnumber matching the uidnumber of the user, and the user sets its primary +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, -there is no benefit to seperating 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 -of preventing accidental creation of a separate group that has an overlapping gidnumber -(the uniqueness attribute of the schema will block the creation). +As there is now an equivalence between the UID and GID number of the user and the UPG, +there is no benefit to separating these values. As a result kanidm accounts *only* +have a gidnumber, which is also considered to be its uidnumber as well. This has the benefit +of preventing the accidental creation of a separate group that has an overlapping gidnumber +(the `uniqueness` attribute of the schema will block the creation). ### 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 creation of the account. -Kanidm does neither of these. As the gidnumber of the user must by unique, and a user -implies the UPG must exist, we are able to 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 -UPG - however, given the nature of a user private group, this is somewhat the point. +Kanidm does neither of these. As the gidnumber of the user must be unique, and a user +implies the UPG must exist, we can generate UPG's on-demand from the account. +This has a single side effect - that you are unable to add any members to a +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 -database servers. In this case we need to be able to allocate stable and reliable +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 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 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 -of duplication. With 50,000 you have 20% chance, 9,300 you have a 1% chance and -with 2900 you have 0.1% chance. +of duplication. With 50,000 you have a 20% chance, 9,300 you have a 1% chance and +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 -to allocate gidnumbers serially or in a consistent manner to avoid potential duplication -events. +We advise that if you have a site with >10,000 users you should use an external system +to allocate gidnumbers serially or consistently to avoid potential duplication events. 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 -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 @@ -101,4 +100,4 @@ You can view the accounts posix token details with: kanidm group posix show --name anonymous demo_group 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. \ No newline at end of file diff --git a/kanidm_book/src/radius.md b/kanidm_book/src/radius.md index c02a4fd93..de0d20f6e 100644 --- a/kanidm_book/src/radius.md +++ b/kanidm_book/src/radius.md @@ -1,13 +1,13 @@ # RADIUS -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 +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 sole point of trust/authentication to an identity, it's still an important control for improving barriers to attackers access to network resources. Kanidm has a philosophy that each account can have multiple credentials which 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. ## 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* 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 despite this limitation, it still greatly improves the situation by isolating the 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 RADIUS offers many different types of tunnels and authentication mechanisms. -However, most client devices "out of the box" when you select a WPA2-Enterprise -network only attempt a single type: MSCHAPv2 with PEAP. This is a challenge -response protocol which requires cleartext or ntlm credentials. +However, most client devices "out of the box" only attempt a single type when you select +a WPA2-Enterprise network: MSCHAPv2 with PEAP. This is a challenge-response protocol +that requires cleartext or NTLM credentials. 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 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 -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. -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: -* The access controls around radius secret by default are "strong", limited to only self-account read and radius-server read. -* 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. -* Having the credentials in cleartext allows a better user experience as clients can view the credentials at anytime to enroll further devices. +* The access controls around RADIUS secrets by default are "strong", limited + to only self-account read and RADIUS-server read. +* 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 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 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 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 -through group management. The key point of this, is that service accounts should +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 not be part of this group. kanidm group create --name idm_admin radius_access_allowed @@ -72,7 +75,7 @@ not be part of this group. ## 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 "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 -We provide a RADIUS container that has all the needed integrations. This container -requires some cryptographic material, laid out in a volume like so: +We provide a RADIUS container that has all the needed integrations. +This container requires some cryptographic material, laid out in a volume like so: data - data/ca.pem # This is the kanidm ca.pem - data/config.ini # This is the kanidm-radius configuration. + data/ca.pem # This is the kanidm ca.pem + data/config.ini # This is the kanidm-radius configuration. data/certs - data/certs/dh # openssl dhparam -out ./dh 2048 - data/certs/key.pem # These are the radius ca/cert/key + data/certs/dh # openssl dhparam -out ./dh 2048 + data/certs/key.pem # These are the radius ca/cert/key data/certs/cert.pem data/certs/ca.pem The config.ini has the following template: [kanidm_client] - url = # URL to the kanidm server - strict = false # Strict CA verification - ca = /data/ca.pem # Path to the kanidm ca - user = # Username of the RADIUS service account - secret = # Generated secret for the service account + url = # URL to the kanidm server + strict = false # Strict CA verification + ca = /data/ca.pem # Path to the kanidm ca + user = # Username of the RADIUS 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] vlan = 1 - ; [group.test] # group. will have these options applied + ; [group.test] # group. will have these options applied ; vlan = [radiusd] - ca = # Path to the radius server's CA - key = # Path to the radius servers key - cert = # Path to the radius servers cert - dh = # Path to the radius servers dh params - required_group = # name of a kanidm group which you must be a member of to - # use radius. - cache_path = # A path to an area where cached user records can be stored. - # If in doubt, use /dev/shm/kanidmradiusd + ca = # Path to the radius server's CA + key = # Path to the radius servers key + cert = # Path to the radius servers cert + dh = # Path to the radius servers dh params + required_group = # Name of a kanidm group which you must be + # A member of to use radius. + cache_path = # A path to an area where cached user records can be stored. + # If in doubt, use /dev/shm/kanidmradiusd - ; [client.localhost] # client. configures wifi/vpn consumers - ; ipaddr = # ipv4 or ipv6 address of the NAS - ; secret = # shared secret + ; [client.localhost] # client. configures wifi/vpn consumers + ; ipaddr = # ipv4 or ipv6 address of the NAS + ; secret = # Shared secret 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 ; not the external one if these containers are on the same host. url = https://: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 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] @@ -162,12 +165,12 @@ You can then run the container with: 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 badpassword 127.0.0.1 10 testing123 docker exec -i -t radiusd radtest 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] ipaddr = @@ -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 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. diff --git a/kanidm_book/src/recycle_bin.md b/kanidm_book/src/recycle_bin.md index 7af69fb87..3c62256f5 100644 --- a/kanidm_book/src/recycle_bin.md +++ b/kanidm_book/src/recycle_bin.md @@ -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 > 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? diff --git a/kanidm_client/src/lib.rs b/kanidm_client/src/lib.rs index d276901eb..4cfe7df75 100644 --- a/kanidm_client/src/lib.rs +++ b/kanidm_client/src/lib.rs @@ -153,7 +153,7 @@ impl KanidmClientBuilder { let mut f = match File::open(config_path) { Ok(f) => f, Err(e) => { - debug!("Unabled to open config file [{:?}], skipping ...", e); + debug!("Unable to open config file [{:?}], skipping ...", e); return Ok(self); } }; diff --git a/kanidm_unix_int/src/unix_config.rs b/kanidm_unix_int/src/unix_config.rs index 52d86cc59..0f959d3cf 100644 --- a/kanidm_unix_int/src/unix_config.rs +++ b/kanidm_unix_int/src/unix_config.rs @@ -84,7 +84,7 @@ impl KanidmUnixdConfig { let mut f = match File::open(config_path) { Ok(f) => f, Err(e) => { - debug!("Unabled to open config file [{:?}], skipping ...", e); + debug!("Unable to open config file [{:?}], skipping ...", e); return Ok(self); } };