https://github.com/mwat56/passlist
Add BasicAuth for Go web-server clients
https://github.com/mwat56/passlist
authentication golang golang-package middleware password-store website
Last synced: 5 months ago
JSON representation
Add BasicAuth for Go web-server clients
- Host: GitHub
- URL: https://github.com/mwat56/passlist
- Owner: mwat56
- License: gpl-3.0
- Created: 2019-05-02T18:05:41.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2025-05-02T11:08:38.000Z (about 1 year ago)
- Last Synced: 2025-08-14T07:39:07.358Z (11 months ago)
- Topics: authentication, golang, golang-package, middleware, password-store, website
- Language: Go
- Homepage:
- Size: 134 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# PassList
[](https://golang.org)
[](https://godoc.org/github.com/mwat56/passlist)
[](https://goreportcard.com/report/github.com/mwat56/passlist)
[](https://github.com/mwat56/passlist/issues?q=is%3Aopen+is%3Aissue)
[](https://github.com/mwat56/passlist/)
[](https://github.com/mwat56/passlist/tags)
[](https://github.com/mwat56/passlist/blob/main/LICENSE)
[](https://github.com/mwat56/passlist/blob/main/app/passlist.go)
- [PassList](#passlist)
- [Purpose](#purpose)
- [Installation](#installation)
- [Usage](#usage)
- [Authentication](#authentication)
- [HTTP handler](#http-handler)
- [The user/password list](#the-userpassword-list)
- [Access denial](#access-denial)
- [Security](#security)
- [Commandline tool](#commandline-tool)
- [Libraries](#libraries)
- [Licence](#licence)
----
## Purpose
Sometimes there is a need to password-protect your web-server, either in whole or just some parts of it. That's were this little package comes in. It offers to simply integrate the popular [BasicAuth](https://en.wikipedia.org/wiki/Basic_access_authentication) mechanism into your own web-server.
> **Note**: To be on the safe side your web-server should use `HTTPS` instead of plain old `HTTP` to avoid the chance of someone eavesdropping on the username/password transmission.
## Installation
You can use `Go` to install this package for you:
go get -u github.com/mwat56/passlist
Then in your application you add
import "github.com/mwat56/passlist"
and use the provided functions (discussed below) as you see fit.
## Usage
### Authentication
`PassList` provides an easy way to handle HTTP Basic Authentication by simply calling the package's `Wrap()` function and implementing the `TAuthDecider` interface which only requires the single function or method
NeedAuthentication(aRequest *http.Request) bool
That function may decide on whatever means necessary whether to grant access (returning `true`) or deny it (returning `false`).
For your ease there are two `TAuthDecider` implementations provided: `TAuthSkipper` (which generally returns `false`) and `TAuthNeeder` (which generally returns `true`). Just instantiate one of those - or, of course, your own implementation - and pass it to the `Wrap()` function.
### HTTP handler
To use this module as socalled middleware there's a function which you can call to wrap your existing HTTP handler thus allowing automatic authentication:
func Wrap(aNext http.Handler,
aRealm, aPasswdFile string,
aAuthDecider IAuthDecider) http.Handler
The arguments mean:
* `aNext`: The handler to be called after successful authentication; you will use the return value of `Wrap()` instead after you called this function.
* `aRealm`: The name of the host/domain to protect (this can be any string you like); it will be shown by most browsers when the username/password is requested.
* `aPasswdFile`: The name of the password file that holds all the username/password pairs to use when authentication is actually required.
* `aAuthDecider`: A deciding function we talked about above.
So, in short: implement the `IAuthDecider` interface and call `passlist.Wrap(…)`, and you're done.
### The user/password list
The package provides a `TPassList` class with methods to work with a username/password list. It's fairly well [documented](https://pkg.go.dev/github.com/mwat56/passlist), so it shouldn't be too hard to use it on your own if you don't like the automatic handling provided by `Wrap()`. You can create a new instance by either calling `passlist.LoadPasswords(aFilename string)` (which, as its name says, tries to load the given password file at once), or you call `passlist.New(aFilename string)` (which leaves it to you when to actually read the password file by calling the `TPassList` object's `Load()` method).
This library provides a couple of functions you can use in your own program to maintain your own password list without having to use the `TPassList` class directly.
* `AddUser(aUser, aFilename string)` reads a password for `aUser` from the commandline and adds it to `aFilename`.
* `CheckUser(aUser, aFilename string)` reads a password for `aUser` from the commandline and compares it with the one stored in `aFilename`.
* `DeleteUser(aUser, aFilename string)` removes the entry for `aUser` from the password list stored in `aFilename`.
* `ListUsers(aFilename string)` reads `aFilename` and lists all users stored in that file.
* `UpdateUser(aUser, aFilename string)` reads a password for `aUser` from the commandline and updates the entry in the password list in `aFilename`.
> **Note**: All these functions _do not return_ to the caller but terminate the respective program with error code `0` (zero) if successful, or `1` (one) otherwise.
### Access denial
There's an additional convenience function called `passlist.Deny()` which sends an _"Unauthorised"_ notice to the remote host in case the remote user couldn't be authenticated; this function is called internally whenever your `TAuthDecider` required authentication and wasn't given valid credentials from the remote user.
### Security
To further improve the safety of the passwords they are _peppered_ before hashing and storing them.
The default _pepper_ value can be read by calling:
pepper := passlist.Pepper()
And the _pepper_ value can be changed by calling:
myPepper := "This is my common 'pepper' value for the user passwords"
passlist.SetPepper(myPepper)
> **Note**: Changing the _pepper_ value _after_ storing user/password pairs **will** invalidate all existing userlist entries!
Please refer to the [source code documentation](https://godoc.org/github.com/mwat56/passlist#TPassList) for further details ot the `TPassList` class.
## Commandline tool
In the package's `./app` folder you'll find the `passlist.go` program which implements the maintenance of password files with the following options:
-add string
name of the user to add to the file (prompting for the password)
-chk string
name of the user whose pass to check (prompting for the password)
-del string
name of the user to remove from the file
-file string
name of the passwordfile to use (default "pwaccess.db")
-lst list all current usernames from the list
-q whether to be quiet or not (suppress screen output)
-upd string
name of the user to update in the file (prompting for the password)
This example app shows how to use the `passlist` package in your own program. Additionally it could be used as a standalone tool to manage your password files.
## Libraries
The following external libraries are used building `PassList`:
* [BCrypt](https://pkg.go.dev/golang.org/x/crypto/bcrypt) supplementary Go cryptography library.
* [SourceError](https://github.com/mwat56/sourceerror) improved error handling.
* [Syscalls](https://pkg.go.dev/golang.org/x/sys) OS-specific functionality.
* [Terminal](https://pkg.go.dev/golang.org/x/term) commandline handling.
## Licence
Copyright © 2019, 2025 M.Watermann, 10247 Berlin, Germany
All rights reserved
EMail :
> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
>
> This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
>
> You should have received a copy of the GNU General Public License along with this program. If not, see the [GNU General Public License](http://www.gnu.org/licenses/gpl.html) for details.
----
[](http://www.gnu.org/copyleft/fdl.html)