narra

package module
v0.27.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 4, 2025 License: MIT Imports: 16 Imported by: 1

README

narra

nginx auth_request via remote api

Project status: Production use since 2017.

This program intended to be used for client authentication with

OAuth2 services supported:

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

Usage example available inside dcape project.

Install

narra is available as docker image at

Configuration

See config.md

Changes

See CHANGELOG.md

Статистика исходного кода

Problems known

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

OAuth2 proxies

History

Primary goal was to allow logins via gitea API. Starting from v0.10 narra uses 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-2025 Aleksei Kovrizhkin [email protected]

Documentation

Index

Constants

This section is empty.

Variables

View Source
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")
)

Functions

This section is empty.

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"`

	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"`
	ClientTimeout time.Duration `long:"client_timeout" default:"10s" description:"HTTP Client timeout"`

	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"`

	Endpoint EndpointConfig `env-namespace:"EP" group:"Endpoint Options" namespace:"ep"`
}

Config holds package options and constants

type EndpointConfig added in v0.27.0

type EndpointConfig struct {
	Auth     string `long:"auth" default:"/login/oauth/authorize" description:"Auth URI"`
	Token    string `long:"token" default:"/login/oauth/access_token" description:"Token URI"`
	User     string `long:"user" default:"/api/v1/user" description:"User info URI"`
	Teams    string `long:"teams" default:"/api/v1/user/orgs" description:"User teams URI"`
	TeamName string `long:"team_name" default:"username" description:"Teams response field name for team name"`
}

EndpointConfig holds Authorization Server Endpoint properties.

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(cookie *securecookie.SecureCookie) Option

Cookie allows to change default cookie lib

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 added in v0.25.0

func (srv *Service) IsMyURLEmpty() bool

IsMyURLEmpty check if app URL autodetect requested

func (*Service) LogoutHandler added in v0.25.0

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

LogoutHandler handles auth cookie clearing

func (*Service) ProtectMiddleware added in v0.25.0

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

ProtectMiddleware requires auth for given URLs mask

func (*Service) SetMyURL added in v0.25.0

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

SetMyURL changes app URL

func (*Service) SetupRoutes added in v0.25.0

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

Directories

Path Synopsis
cmd
narra command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL