ldapauthfiber

README

Fiber middleware for ldap-authenticator

LDAP authentication for Fiber, built on github.com/ctolon/ldap-authenticator.

go get github.com/ctolon/ldap-authenticator/contrib/fiber

Why this is a separate module

The root package promises exactly one direct dependency, github.com/go-ldap/ldap/v3, and means it — a CI job fails the build if that stops being true. Framework middleware cannot live there without breaking that promise, so it lives here instead. Importing ldapauth never puts Fiber in your build graph; importing this module is how you ask for it.

The policy — realms, group requirements, status codes, response padding — lives in the root module's httpauth package and is shared with the net/http, Gin, Echo, and Fiber adapters alike. There is one implementation of "what a 403 means here", not four.

Basic auth

auth, err := ldapauth.New(
    ldapauth.WithURL("ldaps://dc1.corp.example:636"),
    ldapauth.WithDirectBind("uid={{username}},ou=people,dc=corp,dc=example"),
    ldapauth.WithMemberOfGroups(),
)
if err != nil {
    log.Fatal(err)
}
defer auth.Close()

app := fiber.New()

app.Use(ldapauthfiber.BasicAuth(auth,
    httpauth.WithRealm("corp"),
    httpauth.RequireAnyGroup("developers", "ops"),
    httpauth.WithMinimumDuration(100*time.Millisecond),
))

app.Get("/me", func(c *fiber.Ctx) error {
    return c.JSON(ldapauthfiber.MustIdentity(c))
})

Login

app.Post("/login", ldapauthfiber.LoginHandler(auth,
    func(c *fiber.Ctx, identity ldapauth.Identity) error {
        // Start whatever a session is in your application. This library
        // deliberately does not decide that for you.
        return c.JSON(fiber.Map{"dn": identity.GetDN()})
    },
))

Credentials are read from a JSON body, a form body, or a Basic header — whichever the request carries.

Reading the identity

identity, ok := ldapauthfiber.IdentityFrom(c)     // the interface
principal, ok := ldapauthfiber.PrincipalFrom(c)   // the concrete struct
identity := ldapauthfiber.MustIdentity(c)         // panics if absent

The identity lives in c.Locals, under ldapauthfiber.ContextKey.

What is different here

Fiber is built on fasthttp rather than net/http, and that has three consequences worth knowing:

• httpauth.WithSkip and httpauth.WithErrorHandler do nothing, because both take an *http.Request and there is not one. Skip with Fiber's own routing, and shape errors with a Fiber error handler.
• httpauth.WithMaxBodyBytes is applied, but after the fact: Fiber has already read the body into memory by the time this adapter can measure it. Set fiber.Config.BodyLimit to the same number, which is what actually bounds the allocation.
• The context for the authentication is c.UserContext(). Set it if you want a deadline or a trace to reach the directory.
• This module does not build for the wasm targets that the rest of the repository does. fasthttp's listener has no implementation for them.

The Authorization header is still parsed by net/http's own parser rather than by hand: RFC 7617 has more corners than it looks, and none of them are worth meeting twice.

What the caller sees

200	authenticated, and in the required groups
400	the request was not a login: no username, an empty password
401	wrong or absent credentials, with a WWW-Authenticate challenge
403	the credentials were right and the groups were not
503	the directory could not answer

Running the example

go run ./example
curl -u alice:s3cret localhost:8080/me

It runs against the in-memory directory in ldaptest, so there is no LDAP server to install.

More

• Package documentation
• The library's documentation
• HTTP integration guide

Documentation

Overview

Package ldapauthfiber is Fiber middleware for github.com/ctolon/ldap-authenticator.

It is a separate module so that the root package can promise a single dependency and mean it. The policy — group requirements, status codes, response padding — lives in the httpauth package of the root module and is shared with the other framework adapters.

app := fiber.New()
app.Use(ldapauthfiber.BasicAuth(auth, httpauth.RequireAnyGroup("developers")))
app.Get("/me", func(c *fiber.Ctx) error {
    return c.JSON(ldapauthfiber.MustIdentity(c))
})

Fiber is built on fasthttp, which also means this module does not build for the wasm targets that the rest of this repository does — fasthttp's listener has no implementation for them.

Fiber is built on fasthttp rather than net/http, so this adapter does not share the other three's request plumbing: it reads the Authorization header and the body itself, and writes the rejection through Fiber. The httpauth options that take an *http.Request — WithSkip and WithErrorHandler — therefore do nothing here. Skip with Fiber's own routing, and shape errors with a custom Fiber error handler.

Index

• Constants
• func BasicAuth(auth ldapauth.Authenticator, opts ...httpauth.Option) fiber.Handler
• func IdentityFrom(c *fiber.Ctx) (ldapauth.Identity, bool)
• func LoginHandler(auth ldapauth.Authenticator, ...) fiber.Handler
• func MustIdentity(c *fiber.Ctx) ldapauth.Identity
• func PrincipalFrom(c *fiber.Ctx) (*ldapauth.Principal, bool)

Constants

const ContextKey = "ldapauth.identity"

ContextKey is the Locals key the identity is stored under.

Functions

func BasicAuth

func BasicAuth(auth ldapauth.Authenticator, opts ...httpauth.Option) fiber.Handler

BasicAuth returns middleware that authenticates every request with HTTP Basic credentials.

func IdentityFrom

func IdentityFrom(c *fiber.Ctx) (ldapauth.Identity, bool)

IdentityFrom returns the identity the middleware authenticated.

func LoginHandler

func LoginHandler(
	auth ldapauth.Authenticator,
	onSuccess func(c *fiber.Ctx, p ldapauth.Identity) error,
	opts ...httpauth.Option,
) fiber.Handler

LoginHandler returns a handler that reads credentials from the request — JSON body, form body, or Basic header — and hands the authenticated principal to onSuccess.

func MustIdentity

func MustIdentity(c *fiber.Ctx) ldapauth.Identity

MustIdentity returns the authenticated identity and panics if there is none, for handlers that are only ever mounted behind BasicAuth.

func PrincipalFrom

func PrincipalFrom(c *fiber.Ctx) (*ldapauth.Principal, bool)

PrincipalFrom returns the identity as the concrete ldapauth.Principal, for the common case where the mapper was not replaced and reading fields is nicer than calling accessors.