mirror of
https://github.com/kanidm/kanidm.git
synced 2025-02-23 12:37:00 +01:00
docs: Add application passwords design document (#2427)
Related to #41. Signed-off-by: Samuel Cabrero <scabrero@suse.de> Pair-Programmed-With: Firstyear <william@blackhats.net.au>
This commit is contained in:
Samuel Cabrero
GitHub
parent
ed2bd846cc
commit
492c3da36c
212
book/src/developers/designs/application_passwords.md
Normal file
212
book/src/developers/designs/application_passwords.md
Normal file
|
|
@ -0,0 +1,212 @@
|
||||||
|
# Rationale
|
||||||
|
|
||||||
|
Kanidm exists to provide an authentication source for external applications.
|
||||||
|
These applications need to have standardised ways to integrate with Kanidm to
|
||||||
|
allow that application to interact and trust Kanidm's authentication results.
|
||||||
|
|
||||||
|
For web based applications we offer Oauth2/OIDC. For Linux machines we offer a
|
||||||
|
Kanidm specific HTTPS channel for identifying users (UNIX integration).
|
||||||
|
Currently, for applications that don't support other protocols we offer an LDAPS
|
||||||
|
gateway that allows users to bind using their UNIX password.
|
||||||
|
|
||||||
|
However this has the issue that due to how limited Linux authentication is, UNIX
|
||||||
|
passwords are always single factor. We also don't want the same UNIX credentials
|
||||||
|
that are used, e.g. for sudo on machines, to be leaked and used for applications
|
||||||
|
like email.
|
||||||
|
|
||||||
|
To improve this we need a way to offer authentication services to applications
|
||||||
|
that are unable to support anything modern.
|
||||||
|
|
||||||
|
Since LDAP is the "lingua franca" of authentication and almost universally
|
||||||
|
implemented as an authentication for all applications, we can use this to
|
||||||
|
provide *application specific* password based authentication and remove the
|
||||||
|
ability to bind with the UNIX password.
|
||||||
|
|
||||||
|
# User experience
|
||||||
|
|
||||||
|
The administrator configures two applications on their Kanidm instance. One is
|
||||||
|
"mail" for a generic SMTP+IMAP service. The other is HTTP basic auth to a legacy
|
||||||
|
web server. Then the administrator configures which users will be able to use
|
||||||
|
application passwords for each application.
|
||||||
|
|
||||||
|
The mail services and web services are configured to point to Kanidm's LDAP
|
||||||
|
gateway with a customized search base DN.
|
||||||
|
|
||||||
|
The users can login to the webui or command line and list what linked
|
||||||
|
applications exist on their accounts that require application passwords.
|
||||||
|
|
||||||
|
The users can then request a new "application password" for the mail server for
|
||||||
|
their laptop and another one for their phone. They can copy-paste the generated
|
||||||
|
passwords to their mail clients which uses this password on their behalf.
|
||||||
|
Similarly, they can request a new application password to access the web server
|
||||||
|
basic auth.
|
||||||
|
|
||||||
|
# Technical Details
|
||||||
|
|
||||||
|
## Client
|
||||||
|
|
||||||
|
Currently the LDAP basedn is configurable by an admin, or generated from domain.
|
||||||
|
For example, example.com <http://example.com/> becomes dc=example,dc=com.
|
||||||
|
|
||||||
|
Each configured application will define a new naming context, like
|
||||||
|
app=mail,dc=example,dc=com or app=httpd,dc=example,dc=com
|
||||||
|
|
||||||
|
(NOTE: Should this be app=? Some broken clients could try to validate this rdn
|
||||||
|
and error, so perhaps it should be a standard rdn value like cn?)
|
||||||
|
|
||||||
|
The application then uses this app=mail,dc=example,dc=com as their search base
|
||||||
|
rather than dc=example,dc=com. Within this search base, we show the same content
|
||||||
|
from dc=example,dc=com.
|
||||||
|
|
||||||
|
(NOTE: We could limit this to application only entries via group membership, but
|
||||||
|
the issue then is when you have a group for allowing access to the application,
|
||||||
|
but then still need other groups reflected into the subtree. In this case, if we
|
||||||
|
limited the view to application access only, we wouldn't be displaying the
|
||||||
|
non-access groups that the application may still rely on. Ultimately, in this
|
||||||
|
case the application needs to make it's own authorisation decisions to an
|
||||||
|
extend. Kanidm can limit which users are members of the access allowed group as
|
||||||
|
only they can bind still as an extra layer of defence)
|
||||||
|
|
||||||
|
The application must bind with its api-token if it wishes to read extended user
|
||||||
|
information. With this, only basic info limited to anonymous rights are granted.
|
||||||
|
|
||||||
|
(NOTE: We can't assume these DNs are private - I did consider making these
|
||||||
|
app=<secret key>,dc=example,dc=com, but client applications may disclose this
|
||||||
|
basedn in ui elements).
|
||||||
|
|
||||||
|
When a user authenticates the binddn of the account is set to
|
||||||
|
spn=user,app=name,dc=example,dc=com. This difference in base DN triggers Kanidm
|
||||||
|
to re-route the authentication to the application specific password, rather than
|
||||||
|
the UNIX one.
|
||||||
|
|
||||||
|
## Kanidm
|
||||||
|
|
||||||
|
### Application Entries
|
||||||
|
|
||||||
|
A new class for applications will be added. Each application will have a single
|
||||||
|
associated group so 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. It
|
||||||
|
will be the administrator who will configure the association after creating the
|
||||||
|
application and optionally a new group. It will be possible to associate
|
||||||
|
`idm_all_persons` to an application. Removing an application will not delete the
|
||||||
|
associated group nor its members.
|
||||||
|
|
||||||
|
When users are removed from a group associated to an application all of their
|
||||||
|
application passwords for the application will be disabled.
|
||||||
|
|
||||||
|
Application schema class will supplement service account class to allow
|
||||||
|
generating tokens for them. These are optional since an anonymous bind to kanidm
|
||||||
|
and searching under the basedn or application base dn will continue to work.
|
||||||
|
|
||||||
|
Application should have a URL reference to help admins identify where the
|
||||||
|
application may be located or accessed.
|
||||||
|
|
||||||
|
(NOTE: Future, it could be good to allow customisable instructions for users on
|
||||||
|
where to go to use their app password?)
|
||||||
|
|
||||||
|
### Accounts
|
||||||
|
|
||||||
|
The user may wish to have multiple passwords per application. Each password must
|
||||||
|
have, at minimum, a label to identify it. For example:
|
||||||
|
|
||||||
|
```
|
||||||
|
MAIL
|
||||||
|
iphone: abcd...
|
||||||
|
laptop: bcde...
|
||||||
|
HTTP
|
||||||
|
workstation: cdef...
|
||||||
|
```
|
||||||
|
|
||||||
|
Person accounts will need a new `Attribute::ApplicationPassword` that stores a
|
||||||
|
`ValueSetApplicationPassword`. Each value in the set is a new type to manage these
|
||||||
|
secrets and their labeling and the references to the applications.
|
||||||
|
|
||||||
|
```
|
||||||
|
struct ApplicationPAssword {
|
||||||
|
label: String,
|
||||||
|
password: Password,
|
||||||
|
}
|
||||||
|
|
||||||
|
type ApplicationPasswords = BTreeMap<Uuid, ApplicationPassword>;
|
||||||
|
^ ^
|
||||||
|
| |
|
||||||
|
| +-> Application password
|
||||||
|
+-> Application password UUID
|
||||||
|
|
||||||
|
type ApplicationUuid = Uuid;
|
||||||
|
|
||||||
|
struct ValueSetApplicationPassword {
|
||||||
|
map: Map<ApplicationUuid, ApplicationPasswords>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Each value in the set is queried by its UUID. This defines the value as
|
||||||
|
`Value::ApplicationPassword(Uuid, ApplicationPassword)`. The
|
||||||
|
`ApplicationPassword` type implements `PartialEq` so two application passwords
|
||||||
|
are equal if their label is equal and they refer to the same application.
|
||||||
|
|
||||||
|
The user must be able to delete credentials individually. The generated password
|
||||||
|
is only displayed once when the user creates it and it is not possible to
|
||||||
|
recover the clear-text form, only hashed form is stored. It is not allowed to
|
||||||
|
store duplicated application passwords (same app refer and label).
|
||||||
|
|
||||||
|
We do not need temporary locks or holds - users can delete and recreate as
|
||||||
|
needed.
|
||||||
|
|
||||||
|
### Reference integrity
|
||||||
|
|
||||||
|
Since application passwords are related to applications, on delete of an
|
||||||
|
application all entries that have a bound application password should be removed
|
||||||
|
from user accounts.
|
||||||
|
|
||||||
|
### Access controls
|
||||||
|
|
||||||
|
The "Application administrators" group will manage the applications, and
|
||||||
|
applications will allow "managed by" so that they can have delegated
|
||||||
|
administration.
|
||||||
|
|
||||||
|
The "Application user passwords administrators" group will be able to list the
|
||||||
|
users's application passwords and delete them but only the users will be able
|
||||||
|
to, additionally to listing and deleting, self-create their own application
|
||||||
|
passwords.
|
||||||
|
|
||||||
|
### LDAP
|
||||||
|
|
||||||
|
The bind DN regular expression needs to adjusted to detect and determine the
|
||||||
|
bind dn if it is related to an application or not. The application bind dn
|
||||||
|
regular expression will capture the user name, and the application name.
|
||||||
|
|
||||||
|
If the session is related to an application we should only accept application
|
||||||
|
passwords in the bind. The user needs to be a member of the associated
|
||||||
|
application group. Binds to an application password must be limited by account
|
||||||
|
validity and expiration.
|
||||||
|
|
||||||
|
We need to add a cache of available applications for lookup.
|
||||||
|
|
||||||
|
(NOTE: Caching and reload needs more explanation)
|
||||||
|
|
||||||
|
An application can bind with its api-token because the application may need to
|
||||||
|
search LDAP with elevated read permissions.
|
||||||
|
|
||||||
|
### kanidm CLI
|
||||||
|
|
||||||
|
The `kanidm` command line tool will be extended to satisfy the following
|
||||||
|
configuration requirements:
|
||||||
|
|
||||||
|
* List applications
|
||||||
|
|
||||||
|
* Create an application
|
||||||
|
|
||||||
|
* Delete an application
|
||||||
|
|
||||||
|
* Manage application - group association
|
||||||
|
|
||||||
|
* Manage the application api-token
|
||||||
|
|
||||||
|
* List application passwords
|
||||||
|
|
||||||
|
* Create application password
|
||||||
|
|
||||||
|
* Delete application password
|
||||||
Loading…
Reference in a new issue