auth-plug

README

auth-plug

Small Go service that takes LDAP logins and hands out JWTs. Very useful for adding authentication to an otherwise unsecured API, and easily adaptable to other authentication methods.

Build and Test

This project uses Go and make to build and test. Go 1.11+ is required for the use of Go modules.

# Run tests
make test

# Run the standard build process
make build

# Build a statically linked binary for release
make static

Configure and Run

All configuration is done at run time with the following environment variables.

AUTH_IP default: all interfaces
The IP address to bind to.

AUTH_JWT_METHOD default: HS512
The signing method to use for creating JWTs.

AUTH_JWT_SECRET required
The key to use to sign JWTs.

AUTH_JWT_VALID_MIN default: 30
The number of minutes a JWT is valid for.

AUTH_LDAP_BASE required
The base DN to use when searching the LDAP server.

AUTH_LDAP_BIND_DN default: <empty>
The DN to bind to the LDAP server with (i.e. the username).

AUTH_LDAP_BIND_PW default: <empty>
The password to use when binding to the LDAP server.

AUTH_LDAP_HOST default: localhost
The hostname or IP of the LDAP server.

AUTH_LDAP_PORT default: 389
The port of the LDAP server.

AUTH_LDAP_TLS default: false
Use TLS to connect to the LDAP server.

AUTH_LDAP_START_TLS default: false
Use STARTTLS to connect to the LDAP server.

AUTH_LDAP_GID_NAME default: memberUid
The LDAP attribute that maps a user to a group.
This functionality is not yet implemented.

AUTH_LDAP_TIMEOUT_SECS default: 3
The number of seconds to wait for the LDAP server to respond.

AUTH_LDAP_UID_NAME default: uid
The LDAP attribute that contains the username.

AUTH_PORT required
The port to bind to.

AUTH_PROFILE
The [ip]:<port> for a pprof web server to listen on.
This then enables the standard set of /debug pprof endpoints.

Usage

auth-plug follows a familiar flow.

1. POST a username and password to /login.
2. Retrieve the JWT from the response.
3. Send a GET to /verify, setting the JWT from step 2 in the Authorization header.
4. If step 3 fails, go back to step 1.

Here is a full list of defined endpoints.

/login POST
Takes a username and password as post data, validates it against the LDAP server, and sends back a JWT.

/verify GET
Returns OK if a valid Authorization header w/ JWT (type Bearer) is supplied and the JWT is validated.

/health GET
Returns an HTTP 200 on healthy and HTTP 503 if an error is found with the service.
Always returns a JSON structure with a status key.

Healthy

{"status":"OK"}

Unhealthy (e.g.)

{"status":"LDAP Result Code 200 \"Network Error\": dial tcp: lookup bad.examplehost.com: no such host"}

I don't want to use LDAP

No problem! The authentication code is contained inside auth/main.go and auth/ldap.go. Swap it out with your authentication server type.

Caveats

auth-plug only does authentication, not authorization. Future versions will support some form of authz control (e.g. casbin).

A standard use-case for auth-plug is running on localhost with the LDAP server and nginx. Full TLS support is yet to be implemented.

go-ldap-client is used for the LDAP work. This library seems to be abandoned and should be changed out for something that is actively maintained.