README
¶
HTTP Authentication implementation in Go
This is an implementation of HTTP Basic and HTTP Digest authentication in Go language. It is designed as a simple wrapper for http.RequestHandler functions.
Features
- Supports HTTP Basic and HTTP Digest authentication.
- Supports proxy authentication
- Supports htpasswd and htdigest formatted files.
- Automatic reloading of password files.
- Pluggable interface for user/password storage.
- Supports MD5, SHA1 and BCrypt for Basic authentication password storage.
- Configurable Digest nonce cache size with expiration.
- Wrapper for legacy http handlers (http.HandlerFunc interface)
Example usage
This is a complete working example for Basic auth:
package main
import (
auth "github.com/abbot/go-http-auth"
"fmt"
"net/http"
)
func Secret(user, realm string) string {
if user == "john" {
// password is "hello"
return "$1$dlPL2MqE$oQmn16q49SqdmhenQuNgs1"
}
return ""
}
func handle(w http.ResponseWriter, r *auth.AuthenticatedRequest) {
fmt.Fprintf(w, "<html><body><h1>Hello, %s!</h1></body></html>", r.Username)
}
func main() {
authenticator := auth.NewBasicAuthenticator("example.com", Secret)
http.HandleFunc("/", authenticator.Wrap(handle))
http.ListenAndServe(":8080", nil)
}
See more examples in the "examples" directory.
Legal
This module is developed under Apache 2.0 license, and can be used for open and proprietary projects.
Copyright 2012-2013 Lev Shamardin
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file or any other part of this project except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Documentation
¶
Overview ¶
Package auth is an implementation of HTTP Basic and HTTP Digest authentication.
Index ¶
- Constants
- Variables
- func AuthenticateHeaderName(proxy bool) string
- func AuthenticationInfoHeaderName(proxy bool) string
- func AuthorizationHeaderName(proxy bool) string
- func H(data string) string
- func JustCheck(auth AuthenticatorInterface, wrapped http.HandlerFunc) http.HandlerFunc
- func MD5Crypt(password, salt, magic []byte) []byte
- func ParseList(value string) []string
- func ParsePairs(value string) map[string]string
- func RandomKey() string
- func UnauthorizedStatusCode(proxy bool) int
- func UnauthorizedStatusText(proxy bool) string
- type AuthenticatedHandlerFunc
- type AuthenticatedRequest
- type Authenticator
- type AuthenticatorInterface
- type BasicAuth
- type BitSet
- type DigestAuth
- func (da *DigestAuth) CheckAuth(r *http.Request) (*DigestAuthResult, error)
- func (a *DigestAuth) DigestAuthParams(r *http.Request) map[string]string
- func (a *DigestAuth) JustCheck(wrapped http.HandlerFunc) http.HandlerFunc
- func (a *DigestAuth) NewContext(ctx context.Context, r *http.Request) context.Context
- func (a *DigestAuth) Purge(count int)
- func (a *DigestAuth) RequireAuth(w http.ResponseWriter, r *http.Request, stale bool)
- func (a *DigestAuth) Wrap(wrapped AuthenticatedHandlerFunc) http.HandlerFunc
- type DigestAuthResult
- type ErrDigestBadNc
- type ErrDigestBadUri
- type ErrDigestHostMismatch
- type ErrDigestUriMismatch
- type File
- type HtdigestFile
- type HtpasswdFile
- type Info
- type MD5Entry
- type SecretProvider
Constants ¶
const DefaultClientCacheSize = 1000
Default values for ClientCacheSize and ClientCacheTolerance for DigestAuth
const DefaultClientCacheTolerance = 100
const DefaultNcCacheSize = 65536
const DigestAlgorithm = "MD5"
const DigestQop = "auth"
Variables ¶
var ErrDigestAlgorithmMismatch = fmt.Errorf("algorithm mismatch; expected %s", DigestAlgorithm)
var ErrDigestAuthMissing = fmt.Errorf("missing digest auth header")
var ErrDigestOpaqueMismatch = fmt.Errorf("client opaque does not match server opaque")
var ErrDigestQopMismatch = fmt.Errorf("qop mismatch; expected %s", DigestQop)
var ErrDigestRepeatedNc = fmt.Errorf("repeated nc! (replay attack?)")
var ErrDigestResponseMismatch = fmt.Errorf("response mismatch")
var ErrDigestStaleNonce = fmt.Errorf("stale nonce")
Functions ¶
func AuthenticateHeaderName ¶
func AuthorizationHeaderName ¶
func JustCheck ¶
func JustCheck(auth AuthenticatorInterface, wrapped http.HandlerFunc) http.HandlerFunc
func ParseList ¶
ParseList parses a comma-separated list of values as described by RFC 2068. which was itself ported from urllib2.parse_http_list, from the Python standard library. Lifted from https://code.google.com/p/gorilla/source/browse/http/parser/parser.go
func ParsePairs ¶
ParsePairs extracts key/value pairs from a comma-separated list of values as described by RFC 2068. The resulting values are unquoted. If a value doesn't contain a "=", the key is the value itself and the value is an empty string. Lifted from https://code.google.com/p/gorilla/source/browse/http/parser/parser.go
func UnauthorizedStatusCode ¶
func UnauthorizedStatusText ¶
Types ¶
type AuthenticatedHandlerFunc ¶
type AuthenticatedHandlerFunc func(http.ResponseWriter, *AuthenticatedRequest)
AuthenticatedHandlerFunc is like http.HandlerFunc, but takes AuthenticatedRequest instead of http.Request
type AuthenticatedRequest ¶
type AuthenticatedRequest struct {
http.Request
/*
Authenticated user name. Current API implies that Username is
never empty, which means that authentication is always done
before calling the request handler.
*/
Username string
}
Request handlers must take AuthenticatedRequest instead of http.Request
type Authenticator ¶
type Authenticator func(AuthenticatedHandlerFunc) http.HandlerFunc
Authenticator wraps an AuthenticatedHandlerFunc with authentication-checking code.
Typical Authenticator usage is something like:
authenticator := SomeAuthenticator(...)
http.HandleFunc("/", authenticator(my_handler))
Authenticator wrapper checks the user authentication and calls the wrapped function only after authentication has succeeded. Otherwise, it returns a handler which initiates the authentication procedure.
type AuthenticatorInterface ¶
type AuthenticatorInterface interface {
// NewContext returns a new context carrying authentication
// information extracted from the request.
NewContext(ctx context.Context, r *http.Request) context.Context
// Wrap returns an http.HandlerFunc which wraps
// AuthenticatedHandlerFunc with this authenticator's
// authentication checks.
Wrap(AuthenticatedHandlerFunc) http.HandlerFunc
}
type BasicAuth ¶
type BasicAuth struct {
IsProxy bool
Realm string
Secrets SecretProvider
}
func NewBasicAuthenticator ¶
func NewBasicAuthenticator(realm string, secrets SecretProvider) *BasicAuth
func NewBasicAuthenticatorForProxy ¶
func NewBasicAuthenticatorForProxy(realm string, secrets SecretProvider) *BasicAuth
func (*BasicAuth) CheckAuth ¶
Checks the username/password combination from the request. Returns either an empty string (authentication failed) or the name of the authenticated user.
Supports MD5 and SHA1 password entries
func (*BasicAuth) NewContext ¶
NewContext returns a context carrying authentication information for the request.
func (*BasicAuth) RequireAuth ¶
func (a *BasicAuth) RequireAuth(w http.ResponseWriter, r *http.Request)
http.Handler for BasicAuth which initiates the authentication process (or requires reauthentication).
func (*BasicAuth) Wrap ¶
func (a *BasicAuth) Wrap(wrapped AuthenticatedHandlerFunc) http.HandlerFunc
BasicAuthenticator returns a function, which wraps an AuthenticatedHandlerFunc converting it to http.HandlerFunc. This wrapper function checks the authentication and either sends back required authentication headers, or calls the wrapped function with authenticated username in the AuthenticatedRequest.
type DigestAuth ¶
type DigestAuth struct {
IsProxy bool
Realm string
Opaque string
Secrets SecretProvider
PlainTextSecrets bool
NcCacheSize uint64 // The max number of nc values we remember before issuing a new nonce
/*
Approximate size of Client's Cache. When actual number of
tracked client nonces exceeds
ClientCacheSize+ClientCacheTolerance, ClientCacheTolerance*2
older entries are purged.
*/
ClientCacheSize int
ClientCacheTolerance int
// contains filtered or unexported fields
}
func NewDigestAuthenticator ¶
func NewDigestAuthenticator(realm string, secrets SecretProvider) *DigestAuth
func NewDigestAuthenticatorForProxy ¶
func NewDigestAuthenticatorForProxy(realm string, secrets SecretProvider) *DigestAuth
func (*DigestAuth) CheckAuth ¶
func (da *DigestAuth) CheckAuth(r *http.Request) (*DigestAuthResult, error)
CheckAuth checks whether the request contains valid authentication data. Returns a tuple of DigestAuthResult, error. On success, err is nil and the result contains the name of the authenticated user and authinfo for the contents of the optional XYZ-Authentication-Info response header. If err==ErrDigestStaleNonce then the caller should specify stale=true (see https://www.ietf.org/rfc/rfc2617.txt Section 3.3) when sending the XYZ-Authenticate header.
func (*DigestAuth) DigestAuthParams ¶
func (a *DigestAuth) DigestAuthParams(r *http.Request) map[string]string
Parse Authorization header from the http.Request. Returns a map of auth parameters or nil if the header is not a valid parsable Digest auth header.
func (*DigestAuth) JustCheck ¶
func (a *DigestAuth) JustCheck(wrapped http.HandlerFunc) http.HandlerFunc
JustCheck returns function which converts an http.HandlerFunc into a http.HandlerFunc which requires authentication. Username is passed as an extra X-Authenticated-Username header.
func (*DigestAuth) NewContext ¶
NewContext returns a context carrying authentication information for the request.
func (*DigestAuth) Purge ¶
func (a *DigestAuth) Purge(count int)
Remove count oldest entries from DigestAuth.clients
func (*DigestAuth) RequireAuth ¶
func (a *DigestAuth) RequireAuth(w http.ResponseWriter, r *http.Request, stale bool)
http.Handler for DigestAuth which initiates the authentication process (or requires reauthentication).
func (*DigestAuth) Wrap ¶
func (a *DigestAuth) Wrap(wrapped AuthenticatedHandlerFunc) http.HandlerFunc
Wrap returns an Authenticator which uses HTTP Digest authentication. Arguments:
realm: The authentication realm.
secrets: SecretProvider which must return HA1 digests for the same realm as above.
type DigestAuthResult ¶
type ErrDigestBadNc ¶
type ErrDigestBadNc struct {
// contains filtered or unexported fields
}
func (ErrDigestBadNc) Error ¶
func (e ErrDigestBadNc) Error() string
type ErrDigestBadUri ¶
type ErrDigestBadUri struct {
// contains filtered or unexported fields
}
func (ErrDigestBadUri) Error ¶
func (e ErrDigestBadUri) Error() string
type ErrDigestHostMismatch ¶
type ErrDigestHostMismatch struct {
// contains filtered or unexported fields
}
func (ErrDigestHostMismatch) Error ¶
func (e ErrDigestHostMismatch) Error() string
type ErrDigestUriMismatch ¶
type ErrDigestUriMismatch struct {
// contains filtered or unexported fields
}
func (ErrDigestUriMismatch) Error ¶
func (e ErrDigestUriMismatch) Error() string
type File ¶
type File struct {
Path string
Info os.FileInfo
/* must be set in inherited types during initialization */
Reload func()
}
Common functions for file auto-reloading
func (*File) ReloadIfNeeded ¶
func (f *File) ReloadIfNeeded()
type HtdigestFile ¶
Structure used for htdigest file authentication. Users map realms to maps of users to their HA1 digests.
type HtpasswdFile ¶
Structure used for htdigest file authentication. Users map users to their salted encrypted password
type Info ¶
type Info struct {
// Authenticated is set to true when request was authenticated
// successfully, i.e. username and password passed in request did
// pass the check.
Authenticated bool
// Username contains a user name passed in the request when
// Authenticated is true. It's value is undefined if Authenticated
// is false.
Username string
// ResponseHeaders contains extra headers that must be set by server
// when sending back HTTP response.
ResponseHeaders http.Header
}
Info contains authentication information for the request.
func FromContext ¶
FromContext returns authentication information from the context or nil if no such information present.
func (*Info) UpdateHeaders ¶
UpdateHeaders updates headers with this Info's ResponseHeaders. It is safe to call this function on nil Info.
type SecretProvider ¶
SecretProvider is used by authenticators. Takes user name and realm as an argument, returns secret required for authentication (HA1 for digest authentication, properly encrypted password for basic).
Returning an empty string means failing the authentication.
func HtdigestFileProvider ¶
func HtdigestFileProvider(filename string) SecretProvider
SecretProvider implementation based on htdigest-formated files. Will reload htdigest file on changes. Will panic on syntax errors in htdigest files.
func HtpasswdFileProvider ¶
func HtpasswdFileProvider(filename string) SecretProvider
SecretProvider implementation based on htpasswd-formated files. Will reload htpasswd file on changes. Will panic on syntax errors in htpasswd files. Realm argument of the SecretProvider is ignored.
Source Files