gsadmin/glauth
1
0
Fork 0
mirror of https://github.com/glauth/glauth.git synced 2026-10-24 21:23:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

Shortened README

Browse Source
This commit is contained in:
Chris F Ravenscroft
2022-10-29 22:56:53 -07:00
parent 32750d2abd
commit 9865de68ac
1 changed files with 5 additions and 287 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+5 -287
View File
@@ -27,43 +27,9 @@ Use it to centralize account management across your Linux servers, your OSX mach
<hr>
### Contributing
- Please base all Pull Requests on [dev](https://github.com/glauth/glauth/tree/dev), not master.
- Format your code autonmatically using `gofmt -d ./` before committing
### Quickstart
This quickstart is a great way to try out GLAuth in a non-production environment. *Be warned that you should take the extra steps to setup SSL (TLS) for production use!*
1. Download a precompiled binary from the [releases](https://github.com/glauth/glauth/releases) page.
2. Download the [example config file](https://raw.githubusercontent.com/glauth/glauth/master/v2/sample-simple.cfg).
3. Start the GLAuth server, referencing the path to the desired config file with `-c`.
- `./glauth64 -c sample-simple.cfg`
4. Test with traditional LDAP tools
- For example: `ldapsearch -LLL -H ldap://localhost:3893 -D cn=serviceuser,ou=svcaccts,dc=glauth,dc=com -w mysecret -x -bdc=glauth,dc=com cn=hackers`
GLAuth Documentation can be found [here](https://glauth.github.io/docs/)
### Make Commands
Note - makefile uses git data to inject build-time variables. For best results, run in the context of the git repo.
*make all* - run build binaries for platforms
*make fast* - run build for only linux 64 bit
*make run* - wrapper for the 'go run' command, setting up the needed tooling
*make pull-base-plugins* - add base plugins code as submodules for local build
*make forget-plugins* - remove all plugins from current tree
*make test* - run the integration test on linux64 binary
*make releaseplugins* - build app plugins that we pulled locally
*make releasedocker* - build main and plugins, push to docker hub
*make testdocker* - quick docker sanity check
Get started in three short [steps](https://glauth.github.io/docs/quickstart.html)
### Usage:
```
@@ -112,267 +78,19 @@ Here's a sample config wth hardcoded users and groups:
name = "superheros"
gidnumber = 5501
```
To create the password SHA hash, use this command: `echo -n "mysecret" | openssl dgst -sha256`
Instead of a local configuration file, GLAuth can fetch its configuration from S3. This is an easy way to ensure redundant GLAuth servers are always in-sync.
```unix
glauth -c s3://bucketname/glauth.cfg
```
In order to use S3, you must set your AWS credentials. Either:
1. set the -K and -S command-line flags **OR**
2. set the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.
More configuration options are documented here: https://github.com/glauth/glauth/blob/master/sample-simple.cfg
### Chaining backends
This can be used, for instance, to inject support for Two Factor Authentication for backends that do not support the feature natively:
```
[[backends]]
datastore = "ldap"
servers = ["ldap:s//localhost:390"]
[[backends]]
datastore = "config"
...
[[users]]
name = "hackers"
otpsecret = "................"
```
### Required Fields
* Name
* The user's username
* ou
* ID of the user's primary group
* uidnumber
* The user's unix user id
* sshPublicKey
* Specify an array of public keys
### Optional Fields
* otherGroups
* Array of IDs of groups the user is a member of.
* Example: [5501, 5002]
* default = blank
* givenname
* First name
* Example: John
* default = blank
* sn
* Last name
* Example: Doe
* default = blank
* disabled
* Specify if account is active.
* Set to 'true' (without quotes) to make the LDAP entry add 'AccountStatus = inactive'
* default = false (active)
* mail
* Specify an email
* example: jdoe@example.com
* default = blank
* loginshell
* Specify a different login shell for the user
* Example: /bin/sh, or /sbin/nologin
* default = /bin/bash
* homedirectory
* Specify an overridden home directory for the user
* Example: /home/itadmin
* default = /home/[username]
* otpsecret
* Specify OTP secret used to validate OTP passcode
* Example: 3hnvnk4ycv44glzigd6s25j4dougs3rk
* default = blank
* passappbcrypt
* Specify an array of app passwords which can also succesfully bind - these bypass the OTP check. Hash the same way as password.
* Example: ["c32255dbf6fd6b64883ec8801f793bccfa2a860f2b1ae1315cd95cdac1338efa","4939efa7c87095dacb5e7e8b8cfb3a660fa1f5edcc9108f6d7ec20ea4d6b3a88"]
* default = blank
* passappsha256
* Specify an array of app passwords which can also succesfully bind - these bypass the OTP check. Hash the same way as password.
* Example: ["c32255dbf6fd6b64883ec8801f793bccfa2a860f2b1ae1315cd95cdac1338efa","4939efa7c87095dacb5e7e8b8cfb3a660fa1f5edcc9108f6d7ec20ea4d6b3a88"]
* default = blank
* yubikey
* Specify Yubikey ID for maching Yubikey OTP against the user
* Example: cccjgjgkhcbb
* default = blank
### Capabilities
Introduced in 2.1.0, this feature continues improving the intrinsic security model of GLAuth.
While some level of access control is already enforced when using an LDAP backend, Capabilities are now part of the Config and Database backends.
Currently, one capability is recognized: "search" -- here is how to configure it in a Config yaml file:
```
...
[behaviors]
# Ignore all capabilities restrictions, for instance allowing every user to perform a search
IgnoreCapabilities = false
...
[[users]]
name = "hackers"
[[users.capabilities]]
action = "search"
object = "ou=superheros,dc=glauth,dc=com"
[[users.capabilities]]
action = "search"
object = "ou=someotherdn,dc=glauth,dc=com"
...
[[users]]
name = "serviceuser"
[[users.capabilities]]
action = "search"
object = "*"
...
```
For backward compatibility, you can set `IgnoreCapabilities` to "true"
If you are using a Database backend, check the plugins README for configuration information.
### OpenSSH keys:
GLAuth can store a user's SSH authorized keys. Add one or more keys per user as shown above, then setup the goklp helper: https://github.com/appliedtrust/goklp
### Strong Passwords
If you are currently using sha256 passwords (`passsha256` or `passappsha256`) moving to strong, salted paswords is recommended. Simply switch to `passbcrypt` and/or `passappbcrypt` password types. Currently (2021) 2<sup>12</sup> is a reasonably good value, depending our your server's CPU.
### Two Factor Authentication
GLAuth can be configured to accept OTP tokens as appended to a users password. Support is added for both **TOTP tokens** (often known by it's most prominent implementation, "Google Authenticator") and **Yubikey OTP tokens**.
When using 2FA, append the 2FA code to the end of the password when authenticating. For example, if your password is "monkey" and your otp is "123456", enter "monkey123456" as your password.
#### TOTP Configuration
To enable TOTP authentication on a user, you can use a tool [like this](https://freeotp.github.io/qrcode.html) to generate a QR code (pick 'Timeout' and optionally let it generate a random secret for you), which can be scanned and used with the [Google Authenticator](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en) app. To enable TOTP authentication, configure the `otpsecret` for the user with the TOTP secret.
#### App Passwords
Additionally, you can specify an array of password hashes using the `passappsha256` for app passwords. These are not OTP validated, and are hashed in the same way as a password. This allows you to generate a long random string to be used in software which requires the ability to authenticate.
However, app passwords can be used without OTP as well.
#### Yubikey Configuration
For Yubikey OTP token authentication, first [configure your Yubikey](https://www.yubico.com/products/services-software/personalization-tools/yubikey-otp/). After this, make sure to [request a `Client ID` and `Secret key` pair](https://upgrade.yubico.com/getapikey/).
Now configure the `yubikeyclientid` and `yubikeysecret` fields in the general section in the configuration file.
To enable Yubikey OTP authentication for a user, you must specify their Yubikey ID on the users `yubikey` field. The Yubikey ID is the first 12 characters of the Yubikey OTP, as explained in the below chart.
![Yubikey OTP](https://developers.yubico.com/OTP/otp_details.png)
When a user has been configured with either one of the OTP options, the OTP authentication is required for the user. If both are configured, either one will work.
More configuration options are documented [here](https://glauth.github.io/docs/file.html) and in this [sample file](https://github.com/glauth/glauth/blob/master/v2/sample-simple.cfg)
### Backends:
For advanced users, GLAuth supports pluggable backends. Currently, it can use a local file, S3 or an existing LDAP infrastructure. In the future, we hope to have backends that support Mongo, SQL, and other datastores.
For advanced users, GLAuth supports pluggable backends. Currently, it can use a local file, S3 or an existing LDAP infrastructure. Through the use of optional plugins, you can connect SQL databases, PAM, and other datastores.
```toml
[backend]
datastore = "ldap"
servers = [ "ldaps://server1:636", "ldaps://server2:636" ]
```
### Production:
Any of the architectures above will work for production. Just remember:
* Always use legit SSL certs for production!
# Other Architectures
A small note about other architectures: while I expect the code is, for the most part, system-independent, there is not a good (and free) CI system which can be easily used to continuously test releases on ARM, BSD, Linux-32bit, and Windows. As such, all of the non-linux-64bit packages are provided as is. The extent of testing on these packages consists solely of cross-compiling for these architectures from a linux 64 bit system.
We will accept PRs which fix bugs on these platforms, but be aware these binaries will not be tested regularly, and instead are provided for the convenience of those who feel comfortable with this.
### Building:
# Logging
- using logr with increasing verbosity
- 0 you always want to see this
- 1 common logging that you might *possibly* want to turn off (error)
- 2 warn
- 3 notice
- 4 info
- 6 debug
- 8 trace
- 10 I would like to performance test your log collection stack
- errors really are errors that cannot be handled or returned
- returning a proper LDAP error code is handling an error
# Testing
Of course, a core set of tests is being run by Github Actions CI. However, when developing new features/refactoring, a more comprehensive regression testing suite is needed.
You can run `go test` to execute the tests found in `glauth_test.go` -- better, if it is installed, you can run [goconvey](https://github.com/smartystreets/goconvey)
Since some tests cover TOTP, you will first need to install `oathtool` in your environment.
You also must create a symbolink link called `glauth` to make it easy for the test framework to find the executable. For instance:
```
cd bin
ln -s glauth64 glauth
```
In order to test GLAuth against an LDAP backend, you will need docker. Run this command:
```
docker run \
--rm \
-d \
-p 389:389 \
--name openldap-service \
--hostname ldap-service \
--env LDAP_ORGANISATION="GLauth" \
--env LDAP_DOMAIN="glauth.com" \
--env LDAP_ADMIN_PASSWORD="password" \
--env LDAP_CONFIG_PASSWORD="password" \
--env LDAP_BASE_DN="dc=glauth,dc=com" \
-v $PWD/misc/openldap/config:/etc/ldap/slapd.d \
-v $PWD/misc/openldap/db:/var/lib/ldap \
osixia/openldap:latest
```
Refer to [this page](https://github.com/glauth/glauth/wiki/Quick-openldap-setup-to-test-LDAP-backend) for a somewhat more in-depth overview of testing with OpenLDAP.
# Compatibility
While our stated goal for GLAuth is to provide the simplest possible authentication server, we keep finding an increasing number of client appliances that are asking fairly "existential" questions of the server. We have been working on providing answers these clients will find satisfactory.
### Root DSE
RFC 4512: "An LDAP server SHALL provide information about itself and other information that is specific to each server. This is represented as a group of attributes located in the root DSE"
Test: `ldapsearch -LLL -H ldap://localhost:3893 -D cn=serviceuser,ou=svcaccts,dc=glauth,dc=com -w mysecret -x -s base "(objectclass=*)"`
### Subschema Discovery
RFC 4512: "To read schema attributes from the subschema (sub)entry, clients MUST issue a Search operation [RFC4511] where baseObject is the DN of the subschema (sub)entry..."
Test: `ldapsearch -LLL -o ldif-wrap=no -H ldap://localhost:3893 -D cn=serviceuser,ou=svcaccts,dc=glauth,dc=com -w mysecret -x -bcn=schema -s base`
By default, this query will return a very minimal schema (~5 objects) -- you can ask GLAuth to return more comprehensive schemas by unpacking, in the `schema/` directory, the OpenLDAP or FreeIPA schema archives found in the `assets/` directory.
### LDAP Backend: "1.1" attribute
RFC 4511: "A list containing only the OID "1.1" indicates that no attributes are to be returned."
# Contributing
## Releasing
Run `./scripts/release.sh`
### Here is what this script does:
On a local Linux system (mandatory):
1. `localmake` -> `release` -> all `linux` and `win` targets
2. `localmake` -> `plugins` -> all plugins on `linux` targets
On a remote MacOS system:
1. `remotemake` -> `release_darwin` -> all `darwin` targets
2. `remotemake` -> `plugins_darwin` -> all plugins on `darwin` targets
# Stargazers over time
[![Stargazers over time](https://starchart.cc/glauth/glauth.svg)](https://starchart.cc/glauth/glauth)