From 7c27b4001802602c60ad691ef594a8782145e771 Mon Sep 17 00:00:00 2001 From: alexvonme <163657928+alexvonme@users.noreply.github.com> Date: Fri, 5 Jul 2024 01:10:28 +0200 Subject: [PATCH] Vale Edits 0.1 (#2869) * Grammar/spell-checking using SUSE Vale ruleset --- book/src/accounts/authentication_and_credentials.md | 2 +- book/src/accounts/people_accounts.md | 2 +- book/src/accounts/posix_accounts_and_groups.md | 6 +++--- book/src/developers/designs/architecture.md | 4 ++-- book/src/developers/designs/auth.md | 2 +- book/src/developers/designs/authentication_flow.md | 3 +-- book/src/developers/designs/cryptography_key_domains.md | 2 +- .../developers/designs/domain_join_machine_accounts.md | 2 +- book/src/developers/designs/indexing.md | 2 +- .../developers/designs/replication_design_and_notes.md | 6 +++--- book/src/developers/readme.md | 2 +- book/src/domain_rename.md | 2 +- book/src/frequently_asked_questions.md | 2 +- book/src/integrations/ldap.md | 8 ++++---- book/src/integrations/oauth2.md | 4 ++-- book/src/integrations/pam_and_nsswitch/suse.md | 2 +- book/src/packaging/ppa_packages.md | 2 +- book/src/preparing_for_your_deployment.md | 4 ++-- book/src/support.md | 8 ++++---- book/src/sync/concepts.md | 2 +- 20 files changed, 33 insertions(+), 34 deletions(-) diff --git a/book/src/accounts/authentication_and_credentials.md b/book/src/accounts/authentication_and_credentials.md index 0045f3d61..f83f962b5 100644 --- a/book/src/accounts/authentication_and_credentials.md +++ b/book/src/accounts/authentication_and_credentials.md @@ -100,7 +100,7 @@ when creating the token. Tokens are only allowed to be valid for a maximum of 24 ### Resetting Credentials Directly -You can perform a password reset on the `demo_user`, for example as the `idm_admin` user, who is a +You can perform a password reset on the `demo_user`, for example, as the `idm_admin` user, who is a default member of this group. The lines below prefixed with `#` are the interactive credential update interface. This allows the user to directly manage the credentials of another account. diff --git a/book/src/accounts/people_accounts.md b/book/src/accounts/people_accounts.md index 76b33397f..662f84f65 100644 --- a/book/src/accounts/people_accounts.md +++ b/book/src/accounts/people_accounts.md @@ -43,7 +43,7 @@ kanidm person get demo_user --name anonymous {{#template ../templates/kani-warning.md imagepath=images 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. +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. }} diff --git a/book/src/accounts/posix_accounts_and_groups.md b/book/src/accounts/posix_accounts_and_groups.md index c7fa40d7a..bc381d253 100644 --- a/book/src/accounts/posix_accounts_and_groups.md +++ b/book/src/accounts/posix_accounts_and_groups.md @@ -1,7 +1,7 @@ # POSIX Accounts and Groups Kanidm has features that enable its accounts and groups to be consumed on POSIX-like machines, such -as Linux, FreeBSD, or others. Both service accounts and person accounts can be used on POSIX +as Linux, FreeBSD or others. Both service accounts and person accounts can be used on POSIX systems. ## Notes on POSIX Features @@ -29,7 +29,7 @@ schema will block the creation). ### UPG Generation Due to the requirement that a user have a UPG for security, many systems create these as two -independent items. For example in /etc/passwd and /etc/group: +independent items. For example, in /etc/passwd and /etc/group: ```text # passwd @@ -138,5 +138,5 @@ ERROR[0000] cannot find UID/GID for user NAME: No subuid ranges found for user " ``` This is a fault in Podman and how it attempts to provide non-root containers, when UID/GIDs are -greater than 65535. In this case you may manually allocate your users GID number to be between +greater than 65535. In this case, you may manually allocate your users GID number to be between 1000 - 65535, which may not trigger the fault. diff --git a/book/src/developers/designs/architecture.md b/book/src/developers/designs/architecture.md index 37b215931..c315fc67b 100644 --- a/book/src/developers/designs/architecture.md +++ b/book/src/developers/designs/architecture.md @@ -28,7 +28,7 @@ authoritative source of protocol layouts with regard to REST or raw communicatio ## Kanidmd (main server) Kanidmd is intended to have minimal (thin) client tools, where the server itself contains most logic -for operations, transformations, and routing of requests to their relevant datatypes. As a result, +for operations, transformations and routing of requests to their relevant datatypes. As a result, the `kanidmd` section is the largest component of the project as it implements nearly everything required for IDM functionality to exist. @@ -110,7 +110,7 @@ make. If you are not within rights to perform these operations the event returns (4) The entries are now sent to the pre-operation plugins for the relevant operation type. This allows transformation of the candidate entries beyond the scope of your access controls, and to -maintain some elements of data consistency. For example one plugin prevents creation of system +maintain some elements of data consistency. For example, one plugin prevents creation of system protected types where another ensures that uuid exists on every entry. (5) These transformed entries are now returned to the query server. diff --git a/book/src/developers/designs/auth.md b/book/src/developers/designs/auth.md index 477a4f15d..e8863867f 100644 --- a/book/src/developers/designs/auth.md +++ b/book/src/developers/designs/auth.md @@ -285,7 +285,7 @@ addition to low. extra: groups could define a "number of ID points" required, where the server lists each auth type based on strength. So group high would request 30 points. Password is 10 points, totp is 20 points, -webauthn could be 20 for example. This way, using totp + webauth would still get you a login. +webauthn could be 20, for example. This way, using totp + webauth would still get you a login. There may be other ways to define this logic, but this applies to method one as well. diff --git a/book/src/developers/designs/authentication_flow.md b/book/src/developers/designs/authentication_flow.md index 1aea69617..380cd62fe 100644 --- a/book/src/developers/designs/authentication_flow.md +++ b/book/src/developers/designs/authentication_flow.md @@ -8,8 +8,7 @@ 3. Client requests auth with a method (`AuthStep::Begin(AuthMech)`) 4. Server responds with an acknowledgement (`AuthState::Continue(Vec)`). This is so the challenge can be included in the response, for Passkeys or other challenge-response methods. - - If required, this challenge/response continues in a loop until the requirements are satisfied - - for example, TOTP + Password. + - If required, this challenge/response continues in a loop until the requirements are satisfied. For example, TOTP and then Password. 5. The result is returned, either: - Success, with the User Auth Token as a `String`. - Denied, with a reason as a `String`. diff --git a/book/src/developers/designs/cryptography_key_domains.md b/book/src/developers/designs/cryptography_key_domains.md index c9c87250b..c15a986a7 100644 --- a/book/src/developers/designs/cryptography_key_domains.md +++ b/book/src/developers/designs/cryptography_key_domains.md @@ -90,7 +90,7 @@ The type defines the possible operations of the Key Object but not how the opera A key object MAY have multiple Key Types. -Key Objects also must define their structure related to their Key Provider. For example a possible +Key Objects also must define their structure related to their Key Provider. For example, a possible TPM Key Provider needs to store its Public and Private components in the Key Object, where our internal provider needs to store the DER portions of the keys. diff --git a/book/src/developers/designs/domain_join_machine_accounts.md b/book/src/developers/designs/domain_join_machine_accounts.md index 1e6ebfa33..3442e2250 100644 --- a/book/src/developers/designs/domain_join_machine_accounts.md +++ b/book/src/developers/designs/domain_join_machine_accounts.md @@ -36,7 +36,7 @@ identify themself to other systems. When a user authenticates with credentials s it's not possible to use these to request other forwardable credentials - and ssh agent forwarding only allows forwarding of ssh credentials, not other types of credentials that may be needed. -In this case when a user authenticates with SSH, since they're using a trusted machine, Kanidm can +In this case, when a user authenticates with SSH, since they're using a trusted machine, Kanidm can request short-term and limited credentials on the users behalf. An example is that we could dynamically request TLS certificates or Kerberos credentials. diff --git a/book/src/developers/designs/indexing.md b/book/src/developers/designs/indexing.md index a70c94b3a..a2fe92b3e 100644 --- a/book/src/developers/designs/indexing.md +++ b/book/src/developers/designs/indexing.md @@ -111,7 +111,7 @@ Imagine a query like: And(Eq(class, person), Eq(name, claire)) ``` -In this case with our database of 250,000 persons, our idl's would have: +In this case, with our database of 250,000 persons, our idl's would have: ``` And( idl[250,000 ids], idl(1 id)) diff --git a/book/src/developers/designs/replication_design_and_notes.md b/book/src/developers/designs/replication_design_and_notes.md index d2160fcb9..1a74f8e77 100644 --- a/book/src/developers/designs/replication_design_and_notes.md +++ b/book/src/developers/designs/replication_design_and_notes.md @@ -156,7 +156,7 @@ In our example, if node B was the last write the entry would resolve as: In attribute level resolution, the time of update for each attribute is tracked. If an attribute was written later, the content of that attribute wins over the other entries. -For example if attr b was written last on node B, and attr c was written last on node A then the +For example, if attr b was written last on node B, and attr c was written last on node A then the entry would resolve to: # AL Resolution @@ -333,7 +333,7 @@ It is rare (if not will never happen) that an entry is morphed in place from a g from one class to a fundamentally different class. But the possibility exists so we must account for it. -In this case what would occur is that the attribute of 'member' would be applied to a person, which +In this case, what would occur is that the attribute of 'member' would be applied to a person, which is invalid for the kanidm schema. In this case, the entry would be moved into a conflict state since logically it is not valid for directory operations (even if the attributes and entry level replication requirements for consistency have been met). @@ -386,7 +386,7 @@ This shows that server B contains the set of data ranging _from_ server A at tim time 6 to the latest values of server A at time 8 and server B at time 16. During incremental replication the consumer sends it RUV to the supplier. The supplier calculates -the _difference_ between the consumer RUV and the supplier RUV. For example +the _difference_ between the consumer RUV and the supplier RUV. For example, Server A RUV Server B RUV |-----|----------|----------| |-----|----------|----------| diff --git a/book/src/developers/readme.md b/book/src/developers/readme.md index 42810f9f1..b2be75477 100644 --- a/book/src/developers/readme.md +++ b/book/src/developers/readme.md @@ -17,7 +17,7 @@ If you have not already, please see our documentation on [rights and ethics](dev ### Humans First -We must at all times make decisions that put humans first. We must respect all cultures, languages, +We must at all times make decisions that put humans first. We must respect all cultures, languages and identities and how they are represented. We will never put a burden on the user to correct for poor designs on our part. diff --git a/book/src/domain_rename.md b/book/src/domain_rename.md index e82a5c1c8..e9d88e9f2 100644 --- a/book/src/domain_rename.md +++ b/book/src/domain_rename.md @@ -1,7 +1,7 @@ # Domain Rename There are some cases where you may need to rename the domain. You should have configured this -initially in the setup, however you may have a situation where a business is changing name, merging, +initially in the setup, however you may have a situation where a business is changing name, merging or other needs which may prompt this needing to be changed. > **WARNING:** This WILL break ALL u2f/webauthn tokens that have been enrolled, which MAY cause diff --git a/book/src/frequently_asked_questions.md b/book/src/frequently_asked_questions.md index e20a96f6e..7f500fd9e 100644 --- a/book/src/frequently_asked_questions.md +++ b/book/src/frequently_asked_questions.md @@ -54,7 +54,7 @@ has an excellent explanation of the attack. Additionally, this threat is discuss [RFC6819 Section 4.4.1](https://www.rfc-editor.org/rfc/rfc6819#section-4.4.1). As Kanidm aims for "secure by default" design, even with _confidential_ clients, we deem it -important to raise the bar for attackers. For example an attacker may have access to the `client_id` +important to raise the bar for attackers. For example, an attacker may have access to the `client_id` and `client_secret` of a confidential client as it was mishandled by a system administrator. While they may not have direct access to the client/application systems, they could still use this `client_id+secret` to then carry out the authorisation code interception attack listed. diff --git a/book/src/integrations/ldap.md b/book/src/integrations/ldap.md index 32e131740..0939c3f7c 100644 --- a/book/src/integrations/ldap.md +++ b/book/src/integrations/ldap.md @@ -20,7 +20,7 @@ text=The LDAP server in Kanidm is not a full LDAP server. This is intentional, a LDAP is a protocol to read data from a directory of information. It is not a server, but a way to communicate to a server. There are many famous LDAP implementations such as Active Directory, 389 -Directory Server, DSEE, FreeIPA, and many others. Because it is a standard, applications can use an +Directory Server, DSEE, FreeIPA and many others. Because it is a standard, applications can use an LDAP client library to authenticate users to LDAP, given "one account" for many applications - an IDM just like Kanidm! @@ -31,7 +31,7 @@ key-values on objects which are all UTF8 strings (or subsets thereof) based on v rules. Kanidm internally implements complex structured data types such as tagging on SSH keys, or multi-value credentials. These can not be represented in LDAP. -Many of the structures in Kanidm do not correlate closely to LDAP. For example Kanidm only has a GID +Many of the structures in Kanidm do not correlate closely to LDAP. For example, Kanidm only has a GID number, where LDAP's schemas define both a UID number and a GID number. Entries in the database also have a specific name in LDAP, related to their path in the directory @@ -61,7 +61,7 @@ HTTPS and LDAPS. ### Writes -LDAP's structure is too simplistic for writing to the complex entries that Kanidm internally +The structure of LDAP is too simplistic for writing to the complex entries that Kanidm internally contains. As a result, writes are rejected for all users via the LDAP interface. ### Access Controls @@ -157,7 +157,7 @@ ldapwhoami -H ldaps://idm.example.com -x -D "dn=token" -w "..." ## Changing the Basedn -By default the basedn of the LDAP server is derived from the domain name. For example a domain name +By default the basedn of the LDAP server is derived from the domain name. For example, a domain name of `idm.example.com` will become `dc=idm,dc=example,dc=com`. However, you may wish to change this to something shorter or at a higher level within your domain diff --git a/book/src/integrations/oauth2.md b/book/src/integrations/oauth2.md index d6567bae7..2326752e4 100644 --- a/book/src/integrations/oauth2.md +++ b/book/src/integrations/oauth2.md @@ -262,7 +262,7 @@ kanidm system oauth2 delete-claim-map nextcloud account_role nextcloud_admins Some applications are unable to provide client authentication. A common example is single page web applications that act as the OAuth2 client and its corresponding webserver is the resource server. -In this case the SPA is unable to act as a confidential client since the basic secret would need to +In this case, the SPA is unable to act as a confidential client since the basic secret would need to be embedded in every client. Another common example is native applications that use a redirect to localhost. These can't have a @@ -460,7 +460,7 @@ kanidm system oauth2 create_scope_map velociraptor_users openid em ### Grafana Grafana is a open source analytics and interactive visualization web application. It provides -charts, graphs, and alerts when connected to supported data source. +charts, graphs and alerts when connected to supported data source. Prepare the environment: diff --git a/book/src/integrations/pam_and_nsswitch/suse.md b/book/src/integrations/pam_and_nsswitch/suse.md index 788b078e2..900d0153b 100644 --- a/book/src/integrations/pam_and_nsswitch/suse.md +++ b/book/src/integrations/pam_and_nsswitch/suse.md @@ -10,7 +10,7 @@ authentication: /etc/pam.d/common-session ``` -> **IMPORTANT** By default these files are symlinks to their corresponding `-pc` file, for example +> **IMPORTANT** By default these files are symlinks to their corresponding `-pc` file, for example, > `common-account -> common-account-pc`. If you directly edit these you are updating the inner > content of the `-pc` file and it WILL be reset on a future upgrade. To prevent this you must first > copy the `-pc` files. You can then edit the files safely. diff --git a/book/src/packaging/ppa_packages.md b/book/src/packaging/ppa_packages.md index 4a068ae2f..02e72eaf4 100644 --- a/book/src/packaging/ppa_packages.md +++ b/book/src/packaging/ppa_packages.md @@ -5,7 +5,7 @@ This pulls the packages from the Kanidm “nightly” packages. Packages are distributed for the latest LTS versions, Ubuntu 22.04 & Debian 12. Please note that while the commands below should also work on other Ubuntu-based distributions, we -cannot ensure their compatibility with PPA. Pop OS for example, would require an altered setup in +cannot ensure their compatibility with PPA. Pop OS, for example, would require an altered setup in line with their [instructions](https://support.system76.com/articles/ppa-third-party/). ## Adding it to your system diff --git a/book/src/preparing_for_your_deployment.md b/book/src/preparing_for_your_deployment.md index 08469d677..0a4446117 100644 --- a/book/src/preparing_for_your_deployment.md +++ b/book/src/preparing_for_your_deployment.md @@ -67,7 +67,7 @@ media. ## TLS -You'll need a volume where you can place configuration, certificates, and the database: +You'll need a volume where you can place configuration, certificates and the database: ```bash docker volume create kanidmd @@ -129,7 +129,7 @@ If your chain.pem contains the CA certificate, you can validate this file with t openssl verify -CAfile chain.pem chain.pem ``` -If your chain.pem does not contain the CA certificate (Let's Encrypt chains do not contain the CA +If your chain.pem does not contain the CA certificate (Let's Encrypt chains do not contain the CA, for example) then you can validate with this command. ```bash diff --git a/book/src/support.md b/book/src/support.md index fdb70a9ea..28517bb7b 100644 --- a/book/src/support.md +++ b/book/src/support.md @@ -16,10 +16,10 @@ considered authoritive and applies to all versions. Kanidm is released on a 3 month (quarterly) schedule. -- February 1st -- May 1st -- August 1st -- November 1st +- February 1 +- May 1 +- August 1 +- November 1 Versions follow semver using `major.minor.patch` with an optional `-tag`. diff --git a/book/src/sync/concepts.md b/book/src/sync/concepts.md index 69b0831d4..16599be9e 100644 --- a/book/src/sync/concepts.md +++ b/book/src/sync/concepts.md @@ -98,7 +98,7 @@ An adminisrator may wish to allow synchronised entries to have some attributes w instance locally. An example is allowing passkeys to be created on Kanidm when the external synchronisation provider does not supply them. -In this case the synchronisation agreement can be configured to yield it's authority over these +In this case, the synchronisation agreement can be configured to yield its authority over these attributes to Kanidm. To configure the attributes that Kanidm can control: