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

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

75
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 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 <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:
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 <resource server name> velociraptor_users openid email
kanidm system oauth2 create_scope_map <resource server name> velociraptor_users openid email

9
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
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 <id>
## 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).

37
kanidm_book/src/ssh_key_dist.md
View file

@ -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 <login user> <account to view>
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 <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
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 <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
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.