diff --git a/README.md b/README.md index 55ad2ad..a660011 100644 --- a/README.md +++ b/README.md @@ -269,26 +269,27 @@ folder for help with: ### vs OpenLDAP -OpenLDAP is a monster of a service that implements all of LDAP and all of its -extensions, plus some of its own. That said, if you need all that flexibility, -it might be what you need! Note that installation can be a bit painful -(figuring out how to use `slapd`) and people have mixed experiences following -tutorials online. If you don't configure it properly, you might end up storing -passwords in clear, so a breach of your server would reveal all the stored -passwords! +[OpenLDAP](https://www.openldap.org) is a monster of a service that implements +all of LDAP and all of its extensions, plus some of its own. That said, if you +need all that flexibility, it might be what you need! Note that installation +can be a bit painful (figuring out how to use `slapd`) and people have mixed +experiences following tutorials online. If you don't configure it properly, you +might end up storing passwords in clear, so a breach of your server would +reveal all the stored passwords! OpenLDAP doesn't come with a UI: if you want a web interface, you'll have to -install one (not that many that look nice) and configure it. +install one (not that many look nice) and configure it. LLDAP is much simpler to setup, has a much smaller image (10x smaller, 20x if you add PhpLdapAdmin), and comes packed with its own purpose-built web UI. +However, it's not as flexible as OpenLDAP. ### vs FreeIPA -FreeIPA is the one-stop shop for identity management: LDAP, Kerberos, NTP, DNS, -Samba, you name it, it has it. In addition to user management, it also does -security policies, single sign-on, certificate management, linux account -management and so on. +[FreeIPA](http://www.freeipa.org) is the one-stop shop for identity management: +LDAP, Kerberos, NTP, DNS, Samba, you name it, it has it. In addition to user +management, it also does security policies, single sign-on, certificate +management, linux account management and so on. If you need all of that, go for it! Keep in mind that a more complex system is more complex to maintain, though. @@ -297,6 +298,18 @@ LLDAP is much lighter to run (<10 MB RAM including the DB), easier to configure (no messing around with DNS or security policies) and simpler to use. It also comes conveniently packed in a docker container. +### vs Kanidm + +[Kanidm](https://kanidm.com) is an up-and-coming Rust identity management +platform, covering all your bases: OAuth, Linux accounts, SSH keys, Radius, +WebAuthn. It comes with a (read-only) LDAPS server. + +It's fairly easy to install and does much more; but their LDAP server is +read-only, and by having more moving parts it is inherently more complex. If +you don't need to modify the users through LDAP and you're planning on +installing something like [KeyCloak](https://www.keycloak.org) to provide +modern identity protocols, check out Kanidm. + ## I can't log in! If you just set up the server, can get to the login page but the password you diff --git a/docs/cookie.png b/docs/cookie.png new file mode 100644 index 0000000..dc1ae54 Binary files /dev/null and b/docs/cookie.png differ diff --git a/docs/scripting.md b/docs/scripting.md new file mode 100644 index 0000000..af81c2b --- /dev/null +++ b/docs/scripting.md @@ -0,0 +1,90 @@ +# Scripting + +Programmatically accessing LLDAP can be done either through the LDAP protocol, +or via the GraphQL API. + +## LDAP + +Most _read-only_ queries about users and groups are supported. Anything not +supported would be considered a missing feature or a bug. + +Most _modification_ queries are not supported, except for creating users and +changing the password (through the extended password operation). Those could be +added in the future, on a case-by-case basis. + +Most _meta_-queries about the LDAP server itself are not supported and are out +of scope. That includes anything that touches the schema, for instance. LLDAP +still supports basic RootDSE queries. + +Anonymous bind is not supported. + +## GraphQL + +The best way to interact with LLDAP programmatically is via the GraphQL +interface. You can use any language that has a GraphQL library (most of them +do), and use the [GraphQL Schema](../schema.graphql) to guide your queries. + +### Getting a token + +You'll need a JWT (authentication token) to issue GraphQL queries. Your view of +the system will be limited by the rights of your user. In particular, regular +users can only see themselves and the groups they belong to (but not other +members of these groups, for instance). + +#### Manually + +Log in to the web front-end of LLDAP. Then open the developer tools (F12), find +the "Storage > Cookies", and you'll find the "token" cookie with your JWT. + +![Cookies menu with a JWT](cookie.png) + +#### Automatically + +The easiest way is to send a json POST request to `/auth/simple/login` with +`{"username": "john", "password": "1234"}` in the body. +Then you'll receive a JSON response with: + +``` +{ + "token": "eYbat...", + "refreshToken": "3bCka...", +} +``` + +### Using the token + +You can use the token directly, either as a cookie, or as a bearer auth token +(add an "Authorization" header with contents `"Bearer "`). + +The JWT is valid for 1 day (unless you log out explicitly). +You can use the refresh token to query `/auth/refresh` and get another JWT. The +refresh token is valid for 30 days. + +### Testing your GraphQL queries + +You can go to `/api/graphql/playground` to test your queries and explore the +data in the playground. You'll need to provide the JWT in the headers: + +``` +{ "Authorization": "Bearer abcdef123..." } +``` + +Then you can enter your query, for instance: + +```graphql +{ + user(userId:"admin") { + displayName + } + groups { + id + displayName + users { + id + email + } + } +} +``` + +The schema is on the right, along with some basic docs.