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

Minor corrections to case, punctuation, spelling (#789)

Browse source
This commit is contained in:
Carla Schroder 2022-05-26 16:07:15 -07:00 committed by GitHub
parent 40b29e14ca
commit 8abd5b2052
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 60 additions and 61 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

73
kanidm_book/src/oauth2.md
View file

@ -1,16 +1,16 @@
# Oauth2 # OAuth2
Oauth is a web authorisation protocol that allows "single sign on". It's key to note 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 authorisation, not authentication, as the protocol in its default forms
do not provide identity or authentication information, only information that do not provide identity or authentication information, only information that
an entity is authorised for the requested resources. an entity is authorised for the requested resources.
Oauth can tie into extensions allowing an identity provider to reveal information OAuth can tie into extensions allowing an identity provider to reveal information
about authorised sessions. This extends oauth from an authorisation only system about authorised sessions. This extends OAuth from an authorisation only system
to a system capable of identity and authorisation. Two primary methods of this 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 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 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 authorisation from the authorisation server to the resource server as some identity
information may be revealed by granting this consent. 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 If successful and consent given, the user is redirected back to the resource server with an
code. The resource server then contacts the authorisation server directly with this 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. 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 The resource server may then optionally contact the token introspection endpoint of the
provided oauth token, which yields extra metadata about the identity that holds the authorisation server about the provided OAuth token, which yields extra metadata about the identity
token from the authorisation. This metadata may include identity information, 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 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 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 the resource server to make extended authorisation decisions without the need
to contact the authorisation server to arbitrate. 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 It's important to note that OAuth2 at its core is an authorisation system which has layered
identity providing elements on top. identity-providing elements on top.
### Resource Server ### 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 or something else. This is the system that "needs protecting" and wants to delegate authorisation
decisions to Kanidm. decisions to Kanidm.
It's important for you to know *how* your resource server supports oauth2. For example, does it 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? support RFC 7662 token introspection or does it rely on OpenID connect for identity information?
Does the resource server support PKCE S256? Does the resource server support PKCE S256?
In general Kanidm requires that your resource server supports: 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 * PKCE S256 code verification to prevent certain token attack classes
* OIDC only - JWT ES256 for token signatures * 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 * user auth url: https://idm.example.com/ui/oauth2
* api auth url: https://idm.example.com/oauth2/authorise * api auth url: https://idm.example.com/oauth2/authorise
* token url: https://idm.example.com/oauth2/token * token url: https://idm.example.com/oauth2/token
* token inspect url: https://idm.example.com/oauth2/inspect * 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: urls:
* openid connect issuer uri: https://idm.example.com/oauth2/openid/:client\_id:/ * 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 discovery: https://idm.example.com/oauth2/openid/:client\_id:/.well-known/openid-configuration
For manual 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 * token signing public key: https://idm.example.com/oauth2/openid/:client\_id:/public\_key.jwk
### Scope Relationships ### Scope Relationships
For an authorisation to proceed, the resource server will request a list of scopes, which are 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 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 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. 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). 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. 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. 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 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: 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 kanidm system oauth2 create_scope_map nextcloud nextcloud_admins admin
> **WARNING** > **WARNING**
> If you are creating an openid connect (OIDC) resource server you *MUST* provide a > 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* > scope map OR implicit scope named 'openid'. Without this, OpenID clients *WILL NOT WORK*
> **HINT** > **HINT**
> openid connect allows a number of scopes that affect the content of the resulting > 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, > 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 > then the associated claims may be added to the authorisation token. It is not guaranteed
> that all of the associated claims will be added. > 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 ### Configure the Resource Server
On your resource server, you should configure the client id as the "oauth2\_rs\_name" from 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 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. the code challenge/verification method is set to S256.
You should now be able to test authorisation. 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) - 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". 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, '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 <resource server name> kanidm system oauth2 warning_insecure_client_disable_pkce <resource server name>
kanidm system oauth2 warning_enable_legacy_crypto <resource server name> kanidm system oauth2 warning_enable_legacy_crypto <resource server name>
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: You can choose to disable other login methods with:
php occ config:app:set --value=0 user_oidc allow_multiple_user_backends 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` other backends by setting the value to `1`
### Velociraptor ### Velociraptor
@ -271,4 +271,3 @@ these to a group with a scope map due to Velociraptors high impact.
# kanidm group create velociraptor_users # kanidm group create velociraptor_users
# kanidm group add_members velociraptor_users ... # kanidm group add_members velociraptor_users ...
kanidm system oauth2 create_scope_map <resource server name> velociraptor_users openid email kanidm system oauth2 create_scope_map <resource server name> velociraptor_users openid email

7
kanidm_book/src/recycle_bin.md
View file

@ -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 backups and restores, just like any other data. It is also replicated between
all servers. 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 Any delete operation of an entry will cause it to be sent to the recycle bin. No
configuration or specification is required. 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. 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 <id> kanidm recycle_bin revive --name admin <id>
## Edge cases ## Edge Cases
The recycle bin is a best effort to restore your data - there are some cases where 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 the revived entries may not be the same as their were when they were deleted. This
@ -69,4 +69,3 @@ groups is rare - we expect recycle bin to save you in "opps" moments, and in a m
of cases you may delete a group or a user and then restore them. To handle this series 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, 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).

35
kanidm_book/src/ssh_key_dist.md
View file

@ -1,39 +1,40 @@
# SSH Key Distribution # SSH Key Distribution
To support SSH authentication securely to a large set of hosts running SSH, we support distribution To support SSH authentication securely to a large set of hosts running SSH, we support
of SSH public keys via the kanidm server. 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 <login user> <account to view> kanidm account ssh list_publickeys --name <login user> <account to view>
kanidm account ssh list_publickeys --name idm_admin william 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: is the best way to do so:
kanidm account ssh add_publickey --name william william 'test-key' "`cat ~/.ssh/id_rsa.pub`" 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' 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: Uploading a private key or other data will be rejected. For example:
kanidm account ssh add_publickey --name william william 'test-key' "invalid" kanidm account ssh add_publickey --name william william 'test-key' "invalid"
Enter password: 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 ## 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 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 can still SSH into your machines, even if your network is down, you move away from Kanidm, or
some other interruption occurs. some other interruption occurs.
The kanidm_ssh_authorizedkeys command is part of the kanidm-unix-clients package, so should be installed 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 <account name> kanidm_ssh_authorizedkeys <account name>
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 To configure servers to accept these keys, you must change their /etc/ssh/sshd_config to
contain the lines: contain the lines:
@ -69,12 +70,12 @@ management tool such as salt or ansible.
GSSAPIAuthentication no GSSAPIAuthentication no
KerberosAuthentication 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:** > **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 > outage or communication loss may prevent you accessing your systems. You should
> only use this version if you have a requirement for it. > 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 <account name> kanidm_ssh_authorizedkeys_direct -D anonymous <account name>
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 To configure servers to accept these keys, you must change their /etc/ssh/sshd_config to
contain the lines: contain the lines: