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
|
||||
|
||||
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
|
||||
|
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