From 8abd5b2052b6862181124a12ba41d9015e2791fa Mon Sep 17 00:00:00 2001 From: Carla Schroder Date: Thu, 26 May 2022 16:07:15 -0700 Subject: [PATCH] Minor corrections to case, punctuation, spelling (#789) --- kanidm_book/src/oauth2.md | 75 ++++++++++++++++----------------- kanidm_book/src/recycle_bin.md | 9 ++-- kanidm_book/src/ssh_key_dist.md | 37 ++++++++-------- 3 files changed, 60 insertions(+), 61 deletions(-) diff --git a/kanidm_book/src/oauth2.md b/kanidm_book/src/oauth2.md index 68b6434aa..52023e08f 100644 --- a/kanidm_book/src/oauth2.md +++ b/kanidm_book/src/oauth2.md @@ -1,16 +1,16 @@ -# Oauth2 +# OAuth2 -Oauth is a web authorisation protocol that allows "single sign on". It's key to note -oauth is authorisation, not authentication, as the protocol in it's default forms +OAuth is a web authorisation protocol that allows "single sign on". It's key to note +OAuth is authorisation, not authentication, as the protocol in its default forms do not provide identity or authentication information, only information that an entity is authorised for the requested resources. -Oauth can tie into extensions allowing an identity provider to reveal information -about authorised sessions. This extends oauth from an authorisation only system +OAuth can tie into extensions allowing an identity provider to reveal information +about authorised sessions. This extends OAuth from an authorisation only system to a system capable of identity and authorisation. Two primary methods of this -exist today: rfc7662 token introspection, and openid connect. +exist today: RFC7662 token introspection, and OpenID connect. -## How Does Oauth2 Work? +## How Does OAuth2 Work? A user wishes to access a service (resource, resource server). The resource server does not have an active session for the client, so it redirects to the @@ -24,29 +24,29 @@ allows the authorisation to proceed. The user is then prompted to consent to the authorisation from the authorisation server to the resource server as some identity information may be revealed by granting this consent. -If successful and consent given, the user is redirected back to the resource server with an authorisation -code. The resource server then contacts the authorisation server directly with this -code and exchanges it for a valid token that may be provided to the users browser. +If successful and consent given, the user is redirected back to the resource server with an +authorisation code. The resource server then contacts the authorisation server directly with this +code and exchanges it for a valid token that may be provided to the user's browser. -The resource server may then optionally contact the token introspection endpoint of the authorisation server about the -provided oauth token, which yields extra metadata about the identity that holds the -token from the authorisation. This metadata may include identity information, +The resource server may then optionally contact the token introspection endpoint of the +authorisation server about the provided OAuth token, which yields extra metadata about the identity +that holds the token from the authorisation. This metadata may include identity information, but also may include extended metadata, sometimes refered to as "claims". Claims are information bound to a token based on properties of the session that may allow the resource server to make extended authorisation decisions without the need to contact the authorisation server to arbitrate. -It's important to note that oauth2 at it's core is an authorisation system which has layered -identity providing elements on top. +It's important to note that OAuth2 at its core is an authorisation system which has layered +identity-providing elements on top. ### Resource Server -This is the server that a user wants to access. Common examples could be nextcloud, a wiki +This is the server that a user wants to access. Common examples could be Nextcloud, a wiki, or something else. This is the system that "needs protecting" and wants to delegate authorisation decisions to Kanidm. -It's important for you to know *how* your resource server supports oauth2. For example, does it -support rfc7662 token introspection or does it rely on openid connect for identity information? +It's important for you to know *how* your resource server supports OAuth2. For example, does it +support RFC 7662 token introspection or does it rely on OpenID connect for identity information? Does the resource server support PKCE S256? In general Kanidm requires that your resource server supports: @@ -55,32 +55,32 @@ In general Kanidm requires that your resource server supports: * PKCE S256 code verification to prevent certain token attack classes * OIDC only - JWT ES256 for token signatures -Kanidm will expose it's oauth2 apis at the following urls: +Kanidm will expose its OAuth2 APIs at the following URLs: * user auth url: https://idm.example.com/ui/oauth2 * api auth url: https://idm.example.com/oauth2/authorise * token url: https://idm.example.com/oauth2/token * token inspect url: https://idm.example.com/oauth2/inspect -OpenID Connect discovery - you need to substitute your oauth2 client id in the following +OpenID Connect discovery - you need to substitute your OAuth2 client id in the following urls: -* openid connect issuer uri: https://idm.example.com/oauth2/openid/:client\_id:/ -* openid connect discovery: https://idm.example.com/oauth2/openid/:client\_id:/.well-known/openid-configuration +* OpenID connect issuer uri: https://idm.example.com/oauth2/openid/:client\_id:/ +* OpenID connect discovery: https://idm.example.com/oauth2/openid/:client\_id:/.well-known/openid-configuration For manual OpenID configuration: -* openid connect userinfo: https://idm.example.com/oauth2/openid/:client\_id:/userinfo +* OpenID connect userinfo: https://idm.example.com/oauth2/openid/:client\_id:/userinfo * token signing public key: https://idm.example.com/oauth2/openid/:client\_id:/public\_key.jwk ### Scope Relationships For an authorisation to proceed, the resource server will request a list of scopes, which are unique to that resource server. For example, when a user wishes to login to the admin panel -of the resource server, it may request the "admin" scope from kanidm for authorisation. But when -a user wants to login, it may only request "access" as a scope from kanidm. +of the resource server, it may request the "admin" scope from Kanidm for authorisation. But when +a user wants to login, it may only request "access" as a scope from Kanidm. -As each resource server may have it's own scopes and understanding of these, Kanidm isolates +As each resource server may have its own scopes and understanding of these, Kanidm isolates scopes to each resource server connected to Kanidm. Kanidm has two methods of granting scopes to accounts (users). The first are implicit scopes. These are scopes granted to all accounts that Kanidm holds. @@ -103,7 +103,7 @@ you have a resource server that will always request a scope of "read", then you After you have understood your resource server requirements you first need to configure Kanidm. By default members of "system\_admins" or "idm\_hp\_oauth2\_manage\_priv" are able to create or -manage oauth2 resource server integrations. +manage OAuth2 resource server integrations. You can create a new resource server with: @@ -121,12 +121,12 @@ You can create a scope map with: kanidm system oauth2 create_scope_map nextcloud nextcloud_admins admin > **WARNING** -> If you are creating an openid connect (OIDC) resource server you *MUST* provide a -> scope map OR implicit scope named 'openid'. Without this, openid clients *WILL NOT WORK* +> If you are creating an OpenID Connect (OIDC) resource server you *MUST* provide a +> scope map OR implicit scope named 'openid'. Without this, OpenID clients *WILL NOT WORK* > **HINT** -> openid connect allows a number of scopes that affect the content of the resulting -> authorisation token. If one of the following scopes are requested by the openid client, +> OpenID connect allows a number of scopes that affect the content of the resulting +> authorisation token. If one of the following scopes are requested by the OpenID client, > then the associated claims may be added to the authorisation token. It is not guaranteed > that all of the associated claims will be added. > @@ -151,8 +151,8 @@ Once created you can view the details of the resource server. ### Configure the Resource Server -On your resource server, you should configure the client id as the "oauth2\_rs\_name" from -kanidm, and the password to be the value shown in "oauth2\_rs\_basic\_secret". Ensure that +On your resource server, you should configure the client ID as the "oauth2\_rs\_name" from +Kanidm, and the password to be the value shown in "oauth2\_rs\_basic\_secret". Ensure that the code challenge/verification method is set to S256. You should now be able to test authorisation. @@ -216,7 +216,7 @@ In the virtual host, to protect a location: Install the module [from the nextcloud market place](https://apps.nextcloud.com/apps/user_oidc) - it can also be found in the Apps section of your deployment as "OpenID Connect user backend". -In nextcloud's config.php you need to allow connection to remote servers: +In Nextcloud's config.php you need to allow connection to remote servers: 'allow_local_remote_servers' => true, @@ -234,13 +234,13 @@ This module does not support PKCE or ES256. You will need to run: kanidm system oauth2 warning_insecure_client_disable_pkce kanidm system oauth2 warning_enable_legacy_crypto -In the settings menu, configure the discovery url and client id and secret. +In the settings menu, configure the discovery URL and client ID and secret. You can choose to disable other login methods with: php occ config:app:set --value=0 user_oidc allow_multiple_user_backends -You can login directly by appending `?direct=1` to your login page still. You can re-enable +You can login directly by appending `?direct=1` to your login page. You can re-enable other backends by setting the value to `1` ### Velociraptor @@ -270,5 +270,4 @@ these to a group with a scope map due to Velociraptors high impact. # kanidm group create velociraptor_users # kanidm group add_members velociraptor_users ... - kanidm system oauth2 create_scope_map velociraptor_users openid email - + kanidm system oauth2 create_scope_map velociraptor_users openid email \ No newline at end of file diff --git a/kanidm_book/src/recycle_bin.md b/kanidm_book/src/recycle_bin.md index 0d2b1369b..7bff61a0e 100644 --- a/kanidm_book/src/recycle_bin.md +++ b/kanidm_book/src/recycle_bin.md @@ -13,12 +13,12 @@ The recycle bin is stored as part of your main database - it is included in all backups and restores, just like any other data. It is also replicated between all servers. -## How do things get into the Recycle Bin? +## How do Things Get Into the Recycle Bin? Any delete operation of an entry will cause it to be sent to the recycle bin. No configuration or specification is required. -## How long do items stay in the Recycle Bin? +## How Long Do Items Stay in the Recycle Bin? Currently they stay up to 1 week before they are removed. @@ -36,7 +36,7 @@ An entry can be revived with: kanidm recycle_bin revive --name admin -## Edge cases +## Edge Cases The recycle bin is a best effort to restore your data - there are some cases where the revived entries may not be the same as their were when they were deleted. This @@ -68,5 +68,4 @@ These issues could be looked at again in the future, but for now we think that d groups is rare - we expect recycle bin to save you in "opps" moments, and in a majority of cases you may delete a group or a user and then restore them. To handle this series of steps requires extra code complexity in how we flag operations. For more, -see [This issue on github](https://github.com/kanidm/kanidm/issues/177). - +see [This issue on github](https://github.com/kanidm/kanidm/issues/177). \ No newline at end of file diff --git a/kanidm_book/src/ssh_key_dist.md b/kanidm_book/src/ssh_key_dist.md index 80b2fd94d..7e3e5e3fa 100644 --- a/kanidm_book/src/ssh_key_dist.md +++ b/kanidm_book/src/ssh_key_dist.md @@ -1,39 +1,40 @@ # SSH Key Distribution -To support SSH authentication securely to a large set of hosts running SSH, we support distribution -of SSH public keys via the kanidm server. +To support SSH authentication securely to a large set of hosts running SSH, we support +distribution of SSH public keys via the Kanidm server. -## Configuring accounts +## Configuring Accounts -To view the current ssh public keys on accounts, you can use: +To view the current SSH public keys on accounts, you can use: kanidm account ssh list_publickeys --name kanidm account ssh list_publickeys --name idm_admin william -All users by default can self-manage their ssh public keys. To upload a key, a command like this +All users by default can self-manage their SSH public keys. To upload a key, a command like this is the best way to do so: kanidm account ssh add_publickey --name william william 'test-key' "`cat ~/.ssh/id_rsa.pub`" -To remove (revoke) an ssh publickey, you delete them by the tag name: +To remove (revoke) an SSH public key, delete them by the tag name: kanidm account ssh delete_publickey --name william william 'test-key' -## Security notes +## Security Notes -As a security feature, kanidm validates *all* publickeys to ensure they are valid ssh publickeys. +As a security feature, Kanidm validates *all* public keys to ensure they are valid SSH public keys. Uploading a private key or other data will be rejected. For example: kanidm account ssh add_publickey --name william william 'test-key' "invalid" Enter password: - thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Http(400, Some(SchemaViolation(InvalidAttributeSyntax)))', src/libcore/result.rs:1084:5 + thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: + Http(400, Some(SchemaViolation(InvalidAttributeSyntax)))', src/libcore/result.rs:1084:5 ## Server Configuration -### Public key caching configuration +### Public Key Caching Configuration -If you have kanidm_unixd running, you can use it to locally cache ssh public keys. This means you -can still ssh into your machines, even if your network is down, you move away from kanidm, or +If you have kanidm_unixd running, you can use it to locally cache SSH public keys. This means you +can still SSH into your machines, even if your network is down, you move away from Kanidm, or some other interruption occurs. The kanidm_ssh_authorizedkeys command is part of the kanidm-unix-clients package, so should be installed @@ -44,7 +45,7 @@ You can test this is configured correctly by running: kanidm_ssh_authorizedkeys -If the account has ssh public keys you should see them listed, one per line. +If the account has SSH public keys you should see them listed, one per line. To configure servers to accept these keys, you must change their /etc/ssh/sshd_config to contain the lines: @@ -69,12 +70,12 @@ management tool such as salt or ansible. GSSAPIAuthentication no KerberosAuthentication no -### Direct communication configuration +### Direct Communication Configuration -In this mode, the authorised keys commands will contact kanidm directly. +In this mode, the authorised keys commands will contact Kanidm directly. > **NOTICE:** -> As kanidm is contacted directly there is no ssh public key cache. Any network +> As Kanidm is contacted directly there is no SSH public key cache. Any network > outage or communication loss may prevent you accessing your systems. You should > only use this version if you have a requirement for it. @@ -87,7 +88,7 @@ You can test this is configured correctly by running: kanidm_ssh_authorizedkeys_direct -D anonymous -If the account has ssh public keys you should see them listed, one per line. +If the account has SSH public keys you should see them listed, one per line. To configure servers to accept these keys, you must change their /etc/ssh/sshd_config to contain the lines: @@ -100,4 +101,4 @@ contain the lines: Restart sshd, and then attempt to authenticate with the keys. It's highly recommended you keep your client configuration and sshd_configuration in a configuration -management tool such as salt or ansible. +management tool such as salt or ansible. \ No newline at end of file