mart-w/kanidm
1
0
Fork 0
mirror of https://github.com/kanidm/kanidm.git synced 2025-05-19 15:33:54 +02:00
Code Issues Actions16 Packages Projects Releases Wiki Activity

Doc multi instance ()

Browse source 
* fix(docs): document the "instance" settings and flag for the CLI

Co-authored-by: James Hodgkinson <james@terminaloutcomes.com>
This commit is contained in:
Firstyear 2024-08-23 17:53:10 +10:00 committed by GitHub
parent 2ea8a0ed88
commit a78692e9d1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 83 additions and 64 deletions

40
book/src/access_control/intro.md
View file

@ -59,26 +59,26 @@ Kanidm ships with default permission groups. You can use these to enable (or dis
performing certain actions or tasks within Kanidm as required by modifying the memberships of these
groups.
| group name | description |
| ---------------------------- | ----------------------------------------------------------------------- |
| `domain_admins` | modify the name of this domain |
| `idm_access_control_admins` | write access controls |
| `idm_account_policy_admins` | modify account policy requirements for user authentication |
| `idm_group_admins` | create and modify groups |
| `idm_mail_servers` | read mail attributes needed to be a mail server |
| `idm_mail_service_admins` | grant permissions to service accounts to act as mail servers |
| `idm_oauth2_admins` | create and modify OAuth2 integrations |
| `idm_people_admins` | create and modify persons |
| `idm_people_on_boarding` | create (but not modify) persons. Intended for use with service accounts |
| `idm_people_pii_read` | allow read to personally identifying information |
| `idm_people_self_mail_write` | allow self-modification of the mail attribute |
| `idm_people_self_name_write` | allow self-modification of the name related attributes |
| `idm_radius_servers` | read user radius secrets. Intended for use with service accounts |
| `idm_radius_service_admins` | create and reset user radius secrets, and allow users to access radius |
| `idm_recycle_bin_admins` | modify and restore entries from the recycle bin |
| `idm_schema_admins` | add and modify elements of schema |
| `idm_service_account_admins` | create and modify service accounts |
| `idm_unix_admins` | enable posix attributes on accounts and groups |
| group name | description |
| ---------------------------- | ---------------------------------------------------------------------------- |
| `domain_admins` | modify the name of this domain |
| `idm_access_control_admins` | write access controls |
| `idm_account_policy_admins` | modify account policy requirements for user authentication |
| `idm_group_admins` | create and modify groups |
| `idm_mail_servers` | read mail attributes needed to be a mail server |
| `idm_mail_service_admins` | grant permissions to service accounts to act as mail servers |
| `idm_oauth2_admins` | create and modify OAuth2 integrations |
| `idm_people_admins` | create and modify persons |
| `idm_people_on_boarding` | create (but not modify) persons. Intended for use with service accounts |
| `idm_people_pii_read` | allow read to personally identifying information |
| `idm_people_self_mail_write` | allow self-modification of the mail attribute |
| `idm_people_self_name_write` | allow self-modification of the name related attributes |
| `idm_radius_servers` | read user radius secrets. Intended for use with service accounts |
| `idm_radius_service_admins` | create and reset user radius secrets, and allow users to access radius |
| `idm_recycle_bin_admins` | modify and restore entries from the recycle bin |
| `idm_schema_admins` | add and modify elements of schema |
| `idm_service_account_admins` | create and modify service accounts |
| `idm_unix_admins` | enable posix attributes on accounts and groups |
| `idm_application_admins` | create and modify ldap applications which use per-user application passwords |
## Default Roles

27
book/src/client_tools.md
View file

@ -55,3 +55,30 @@ To log out of a session:
kanidm logout --name USERNAME
kanidm logout --name admin
```
## Multiple Instances
In some cases you may have multiple Kanidm instances. For example you may have a production instance
and a development instance. This can introduce friction for admins when they need to change between
those instances.
The Kanidm cli tool allows you to configure multiple instances and swap between them with an
environment variable, or the `--instance` flag. Instances maintain separate session stores.
```toml
uri = "https://idm.example.com"
ca_path = "/path/to/ca.pem"
["development"]
uri = "https://idm.dev.example.com"
ca_path = "/path/to/dev-ca.pem"
```
The instance can then be selected with:
```
export KANIDM_INSTANCE=development
kanidm login -D username@idm.dev.example.com
```
To return to the default instance you `unset` the `KANIDM_INSTANCE` variable.

8
book/src/developers/designs/application_passwords.md
View file

@ -79,10 +79,10 @@ A new class for applications will be added. Each application will have a single
only members of this group will be able to bind with the application password for the associated
application.
Creating a new application will not create an associated group automatically, an existing group
must be provided. It will be possible to associate `idm_all_persons` to an application. Removing
an application will not delete the associated group nor its members. It will be possible to change
the linked group after creation.
Creating a new application will not create an associated group automatically, an existing group must
be provided. It will be possible to associate `idm_all_persons` to an application. Removing an
application will not delete the associated group nor its members. It will be possible to change the
linked group after creation.
When users are removed from a group associated to an application all of their application passwords
for the application will be disabled.

60
book/src/developers/designs/unixd_multi_resolver_2024.md
View file

@ -71,9 +71,9 @@ authentication mechanisms like CTAP2 or PIV.
Unixd already needs to parse these files to understand and prevent conflicts between local items and
remote ones. Extending this functionality will allow us to resolve local users from memory.
Not only this, we need to store information *permanently* that goes beyore what /etc/passwd and
similar can store. It would be damaging to users if their CTAP2 (passkeys) were deleted randomly
on a cache clear!
Not only this, we need to store information _permanently_ that goes beyore what /etc/passwd and
similar can store. It would be damaging to users if their CTAP2 (passkeys) were deleted randomly on
a cache clear!
#### Local Group Extension
@ -130,43 +130,42 @@ future.
#### CTAP2 / TPM-PIN
We want to allow local authentication with CTAP2 or a TPM with PIN. Both provide stronger assurances
of both who the user is, and that they are in posession of a specific cryptographic device. The
nice part of this is that they both implement hardware bruteforce protections. For soft-tpm we
can emulate this with a strict bruteforce lockout prevention mechanism.
of both who the user is, and that they are in posession of a specific cryptographic device. The nice
part of this is that they both implement hardware bruteforce protections. For soft-tpm we can
emulate this with a strict bruteforce lockout prevention mechanism.
The weakness is that PIN's which are used on both CTAP2 and TPM, tend to be shorter, ranging from
4 to 8 characters, generally numeric. This makes them unsuitable for remote auth.
The weakness is that PIN's which are used on both CTAP2 and TPM, tend to be shorter, ranging from 4
to 8 characters, generally numeric. This makes them unsuitable for remote auth.
This means for SSH without keys, we *must* use a passphrase or similar instead. We must not allow
This means for SSH without keys, we _must_ use a passphrase or similar instead. We must not allow
SSH auth with PIN to a TPM as this can easily become a remote DOS via the bruteforce prevention
mechanism.
This introduces it's own challenge - we are now juggling multiple potential credentials and need
to account for their addition and removal, as well as changing.
This introduces it's own challenge - we are now juggling multiple potential credentials and need to
account for their addition and removal, as well as changing.
Another significant challenge is that linux is heavily embedded in "passwords as the only factor"
meaning that many systems are underdeveloped like gnome keyring - this expects stacked pam modules
to unlock the keyring as it proceeds.
*Local Users*
_Local Users_
Local Users will expect on login equivalent functionality that `/etc/passwd` provides today, meaning
that local wallets and keyrings are unlocked at login. This necesitates that any CTAP2 or TPM unlock
need to be able to unlock the keyring.
This also has implications for how users expect to interact with the feature. A user will expect that
changing their PIN will continue to allow unlock of their system. And a change of the users password
should not invalidate their existing PIN's or CTAP devices. To achieve this we will need some methods
to cryptographically protect credentials and allow these updates.
This also has implications for how users expect to interact with the feature. A user will expect
that changing their PIN will continue to allow unlock of their system. And a change of the users
password should not invalidate their existing PIN's or CTAP devices. To achieve this we will need
some methods to cryptographically protect credentials and allow these updates.
To achieve this, we need to make the compromise that the users password must be stored in a reversible
form on the system. Without this, the various wallets/keyrings won't work. This trade is acceptable
since `pam_kanidm` is already a module that handles password material in plaintext, so having a
mechanism to securely retrieve this *while* the user is entering equivalent security material is
reasonable.
To achieve this, we need to make the compromise that the users password must be stored in a
reversible form on the system. Without this, the various wallets/keyrings won't work. This trade is
acceptable since `pam_kanidm` is already a module that handles password material in plaintext, so
having a mechanism to securely retrieve this _while_ the user is entering equivalent security
material is reasonable.
The primary shift is that rather than storing a *kdf/hash* of the users output, we will be storing
The primary shift is that rather than storing a _kdf/hash_ of the users output, we will be storing
an authenticated encrypted object where valid decryption of that object is proof that the password
matches.
@ -211,7 +210,7 @@ and consider HMAC of the output.
└──────────────────┘
```
*Remote Users (such as Kanidm)*
_Remote Users (such as Kanidm)_
After a lot of thinking, the conclusion we arrived at is that trying to handle password stacking for
later pam modules is out of scope at this time.
@ -224,9 +223,9 @@ We may allow PINs to be set on a per-machine basis, rather than syncing them via
This would require that a change of the password remotely invalidates set PINs unless we think of
some way around this.
We also think that in the case of things like password managers such as desktop wallets, these should
have passwords that are the concern of the user, not the remote auth source so that our IDM has no
knowledge of the material to unlock these.
We also think that in the case of things like password managers such as desktop wallets, these
should have passwords that are the concern of the user, not the remote auth source so that our IDM
has no knowledge of the material to unlock these.
### Challenges
@ -409,10 +408,3 @@ be consumed by the User.
A usecase is that for application passwords a mail server may wish to cache and locally store the
application password. Only domain joined systems should be capable of this, and need to protect the
application password appropriately.

6
book/src/domain_rename.md
View file

@ -6,9 +6,9 @@ or other needs which may prompt this needing to be changed.
> [!WARNING]
>
> This WILL break ALL PassKeys (WebAuthn tokens) that have been enrolled, which MAY cause accounts to be
> locked out and unrecoverable until further action is taken. DO NOT CHANGE the domain name unless
> REQUIRED and have a plan on how to manage these issues.
> This WILL break ALL PassKeys (WebAuthn tokens) that have been enrolled, which MAY cause accounts
> to be locked out and unrecoverable until further action is taken. DO NOT CHANGE the domain name
> unless REQUIRED and have a plan on how to manage these issues.
&nbsp;

6
book/src/integrations/oauth2.md
View file

@ -144,9 +144,9 @@ kanidm system oauth2 show-basic-secret nextcloud
### Configure the Client/Resource Server
On your client, you should configure the client ID as the `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.
On your client, you should configure the client ID as the `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 to the client.