docs: add docs about scripting

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
+[OpenLDAP](https://www.openldap.org) is a monster of a service that implements
-extensions, plus some of its own. That said, if you need all that flexibility,
+all of LDAP and all of its extensions, plus some of its own. That said, if you
-it might be what you need! Note that installation can be a bit painful
+need all that flexibility, it might be what you need! Note that installation
-(figuring out how to use `slapd`) and people have mixed experiences following
+can be a bit painful (figuring out how to use `slapd`) and people have mixed
-tutorials online. If you don't configure it properly, you might end up storing
+experiences following tutorials online. If you don't configure it properly, you
-passwords in clear, so a breach of your server would reveal all the stored
+might end up storing passwords in clear, so a breach of your server would
-passwords!
+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,
+[FreeIPA](http://www.freeipa.org) is the one-stop shop for identity management:
-Samba, you name it, it has it. In addition to user management, it also does
+LDAP, Kerberos, NTP, DNS, Samba, you name it, it has it. In addition to user
-security policies, single sign-on, certificate management, linux account
+management, it also does security policies, single sign-on, certificate
-management and so on.
+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

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 <token>"`).
+
+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.