mirror of
https://github.com/nitnelave/lldap.git
synced 2023-04-12 14:25:13 +00:00
docs: add docs about scripting
This commit is contained in:
parent
1b91cc8ac2
commit
2593606f16
37
README.md
37
README.md
@ -269,26 +269,27 @@ folder for help with:
|
|||||||
|
|
||||||
### vs OpenLDAP
|
### 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
|
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
|
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.
|
you add PhpLdapAdmin), and comes packed with its own purpose-built web UI.
|
||||||
|
However, it's not as flexible as OpenLDAP.
|
||||||
|
|
||||||
### vs FreeIPA
|
### 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
|
If you need all of that, go for it! Keep in mind that a more complex system is
|
||||||
more complex to maintain, though.
|
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
|
configure (no messing around with DNS or security policies) and simpler to
|
||||||
use. It also comes conveniently packed in a docker container.
|
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!
|
## I can't log in!
|
||||||
|
|
||||||
If you just set up the server, can get to the login page but the password you
|
If you just set up the server, can get to the login page but the password you
|
||||||
|
BIN
docs/cookie.png
Normal file
BIN
docs/cookie.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 61 KiB |
90
docs/scripting.md
Normal file
90
docs/scripting.md
Normal file
@ -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.
|
Loading…
Reference in New Issue
Block a user