narra

README

narra

nginx auth_request via remote api

Project status: MVP

This program intended to be used for client authentication with

• nginx http auth_request module
• traefik ForwardAuth

OAuth2 services supported:

• gitea
• mattermost

Also, narra accepts auth via header with Gitea Access Tokens for non-interactive use cases.

Usage example available inside dcape project (see apps/cis there).

Install

narra is available as docker image at

• DockerHub
• GitHub container registry

Use

Chain of requests with warning Cookie decode error: securecookie: the value is not valid in logfile means you have the same cookie for upper domain. This is configuration problem and you should rename one of these cookies (see --as.cookie_name).

See also

• using-the-nginx-auth-request-module
• traefik-oauth2-proxy

OAuth2 proxies

• traefik-forward-auth (cannot be used while this PR open)
• oauth2-proxy (waiting for this and probably more)
• for nginx: vouch-proxy (waiting for this)
• buzzfeed/sso
• pomerium
• external-auth-server

History

Primary goal is to allow logins via gitea API, starting from v0.10 we support OAuth2 services like gitea or mattermost.

Since v0.20 narra can act as Traefik2 ForwardAuth service.

License

The MIT License (MIT), see LICENSE.

Copyright (c) 2017-2020 Aleksei Kovrizhkin lekovr+dopos@gmail.com

Documentation

Index

• Variables
• type Config
• type Option
  • func Cache(c *cache.Cache[string, string]) Option
  • func Cookie(cookie *securecookie.SecureCookie) Option
  • func Provider(prov *ProviderConfig) Option
• type ProviderConfig
• type Service
  • func New(cfg *Config, options ...Option) *Service
  • func (srv *Service) AuthHandler() http.Handler
  • func (srv *Service) AuthIsOK(w http.ResponseWriter, r *http.Request, replaceHeaders bool) bool
  • func (srv *Service) IsMyURLEmpty() bool
  • func (srv *Service) LogoutHandler() http.Handler
  • func (srv *Service) ProtectMiddleware(next http.Handler, re *regexp.Regexp) http.Handler
  • func (srv *Service) SetMyURL(scheme, host string)
  • func (srv *Service) SetupRoutes(mux *http.ServeMux, privPrefix string)
  • func (srv *Service) Stage1Handler() http.Handler
  • func (srv *Service) Stage2Handler() http.Handler

Variables

var (
	// ErrNoTeam holds error: User is not in required team
	ErrNoTeam = errors.New("user is not in required team")
	// ErrAuthNotGranted holds error: Auth not granted
	ErrAuthNotGranted = errors.New("auth not granted")
	// ErrStateUnknown holds error: Unknown state
	ErrStateUnknown = errors.New("unknown state")
	// ErrBasicTokenExpected holds error when username <> token
	ErrBasicTokenExpected = errors.New("basic Auth username does not match")
	// ErrBasicAuthRequired holds 401 for docker client
	ErrBasicAuthRequired = errors.New("basic Auth is required")
)

var DL = 1

DL holds package debug level

var Providers = map[string]*ProviderConfig{
	"gitea": {
		Auth:        "/login/oauth/authorize",
		Token:       "/login/oauth/access_token",
		User:        "/api/v1/user",
		Team:        "/api/v1/user/orgs",
		TokenPrefix: "token ",
		TeamName:    "username",
	},
	"mmost": {
		Auth:        "/oauth/authorize",
		Token:       "/oauth/access_token",
		User:        "/api/v4/users/me",
		Team:        "/api/v4/users/%s/teams",
		TokenPrefix: "Bearer ",
		TeamName:    "name",
	},
}

Providers holds supported Authorization Servers properties

Types

type Config

type Config struct {
	MyURL       string `long:"my_url" description:"Own host URL (autodetect if empty)"`
	CallBackURL string `long:"cb_url" default:"/login" description:"URL for Auth server's redirect"`

	//nolint:staticcheck // Multiple struct tag "choice" is allowed
	Type      string `long:"type" env:"TYPE" default:"gitea"  choice:"gitea" choice:"mmost" description:"Authorization Server type (gitea|mmost)"`
	Do401     bool   `long:"do401" env:"DO401" description:"Do not redirect with http.StatusUnauthorized, process it"`
	Host      string `long:"host" env:"HOST" default:"http://gitea:8080" description:"Authorization Server host"`
	Team      string `long:"team" env:"TEAM" default:"dcape" description:"Authorization Server team which members has access to resource"`
	ClientID  string `long:"client_id" env:"CLIENT_ID" description:"Authorization Server Client ID"`
	ClientKey string `long:"client_key" env:"CLIENT_KEY" description:"Authorization Server Client key"`

	CacheExpire  time.Duration `long:"cache_expire" default:"5m" description:"Cache expire interval"`
	CacheCleanup time.Duration `long:"cache_cleanup" default:"10m" description:"Cache cleanup interval"`

	AuthHeader     string `long:"auth_header" default:"X-narra-token" description:"Use token from this header if given"`
	CookieDomain   string `long:"cookie_domain"  description:"Auth cookie domain"`
	CookieName     string `long:"cookie_name" default:"narra_token" description:"Auth cookie name"`
	CookieSignKey  string `long:"cookie_sign" env:"COOKIE_SIGN_KEY" description:"Cookie sign key (32 or 64 bytes)"`
	CookieCryptKey string `long:"cookie_crypt" env:"COOKIE_CRYPT_KEY" description:"Cookie crypt key (16, 24, or 32 bytes)"`

	UserHeader string `long:"user_header" env:"USER_HEADER" default:"X-Username" description:"HTTP Response Header for username"`

	BasicRealm     string `long:"basic_realm" default:"narra" description:"Basic Auth realm"`
	BasicUser      string `long:"basic_username" default:"token" description:"Basic Auth user name"`
	BasicUserAgent string `long:"basic_useragent" default:"docker/" description:"UserAgent which requires Basic Auth"`
}

Config holds package options and constants

type Option

type Option func(*Service)

Option is a functional options return type

func Cache

func Cache(c *cache.Cache[string, string]) Option

Cache allows to change default cache lib

func Cookie

func Cookie(cookie *securecookie.SecureCookie) Option

Cookie allows to change default cookie lib

func Provider

func Provider(prov *ProviderConfig) Option

Provider allows to change authorization server config

type ProviderConfig

type ProviderConfig struct {
	Auth        string
	Token       string
	User        string
	Team        string
	TokenPrefix string
	TeamName    string
}

ProviderConfig holds Authorization Server properties

type Service

type Service struct {
	Config *Config
	// contains filtered or unexported fields
}

Service holds service attributes

func New

func New(cfg *Config, options ...Option) *Service

New creates service

func (*Service) AuthHandler

func (srv *Service) AuthHandler() http.Handler

AuthHandler is a Nginx auth_request handler

func (*Service) AuthIsOK

func (srv *Service) AuthIsOK(w http.ResponseWriter, r *http.Request, replaceHeaders bool) bool

AuthIsOK returns true if request is allowed to proceed

func (*Service) IsMyURLEmpty

func (srv *Service) IsMyURLEmpty() bool

IsMyURLEmpty check if app URL autodetect requested

func (*Service) LogoutHandler

func (srv *Service) LogoutHandler() http.Handler

LogoutHandler handles auth cookie clearing

func (*Service) ProtectMiddleware

func (srv *Service) ProtectMiddleware(next http.Handler, re *regexp.Regexp) http.Handler

ProtectMiddleware requires auth for given URLs mask

func (*Service) SetMyURL

func (srv *Service) SetMyURL(scheme, host string)

SetMyURL changes app URL

func (*Service) SetupRoutes

func (srv *Service) SetupRoutes(mux *http.ServeMux, privPrefix string)

SetupRoutes attaches OAuth2 URIs

func (*Service) Stage1Handler

func (srv *Service) Stage1Handler() http.Handler

Stage1Handler handles 401 error & redirects user to auth server

func (*Service) Stage2Handler

func (srv *Service) Stage2Handler() http.Handler

Stage2Handler handles redirect from auth provider, fetches token & user info