Installation

import (
"github.com/cego/go-lib/v2/logger""github.com/cego/go-lib/v2/renderer""github.com/cego/go-lib/v2/forwardauth""github.com/cego/go-lib/v2/oidcauth""github.com/cego/go-lib/v2/oidcclient""github.com/cego/go-lib/v2/headers""github.com/cego/go-lib/v2/serve""github.com/cego/go-lib/v2/periodic"
)

Using Logger

l:=logger.New()
l.Debug("Very nice")
err:=errors.New("An error")
l.Error("An error occurred in readme", logger.GetSlogAttrFromError(err))
handleFunc:=func(writer http.ResponseWriter, request*http.Request) {
l.Debug("Very nice", logger.GetSlogAttrFromRequest(request))
}
// With custom log levell:=logger.NewWithLevel(slog.LevelInfo)
// Set as global slog defaultslog.SetDefault(l)
// Testing with mock loggerl:=logger.NewMock()
r:=renderer.New(l)

Using Renderer with builtin logging

l:=logger.New()
r:=renderer.New(l)
handleFunc:=func(writer http.ResponseWriter, request*http.Request) {
r.Text(w, http.StatusOK, "Action package excitement !!!")
}

Using ForwardAuthHandler

Use builtin http client (timeout 10s)

mux:=http.NewServeMux()
fa:=forwardauth.New(l, "https://sso.example.com/auth", "myservice.example.com")
mux.Handle("/data", fa.Handler(reverseProxy))
mux.Handle("/data", fa.HandlerFunc(func (w http.ResponseWriter, req*http.Request) {
_,_=w.Write()
}))

Bring your own http client

mux:=http.NewServeMux()
httpClient:=&http.Client{Timeout: time.Duration(1) *time.Second}
fa:=forwardauth.New(l, "https://sso.example.com/auth", "myservice.example.com", forwardauth.WithHTTPClient(httpClient))
mux.Handle("/data", fa.Handler(reverseProxy))
mux.Handle("/data", fa.HandlerFunc(func (w http.ResponseWriter, req*http.Request) {
_,_=w.Write()
}))

Using OidcAuth

Authorization code flow with PKCE for browsers, bearer tokens for api clients. The verified id token is the session cookie, so there is no session store.

mux:=http.NewServeMux()
auth, err:=oidcauth.New(context.Background(), l, oidcauth.Config{
Issuer: "https://keycloak.example.com/realms/cego",
ClientID: "myservice",
ClientSecret: os.Getenv("MYSERVICE_OIDC_CLIENT_SECRET"),
BaseURL: "https://myservice.example.com",
})
auth.Register(mux) // Adds GET /auth/login, GET /auth/callback and POST /auth/logoutmux.Handle("GET /{$}", auth.HandlerFunc(index)) // Authenticatedmux.Handle("GET /things", auth.HandlerFunc(things, "reader", "tool-admin")) // Either rolemux.Handle("POST /things/{id}/delete", auth.HandlerFunc(del, "tool-admin")) // That roler.Use(auth.Middleware("reader")) // The same gate as chi middleware// Inside a wrapped handler, or a templateuser:=oidcauth.UserFromContext(r.Context())
user.HasRole("tool-admin")
user.HasAnyRole("reader", "tool-admin")

• Register <BaseURL>/auth/callback on the client, or the provider rejects the login
• Roles are read from client_roles and resource_access.<client>.roles
• Issuer and base url must be https, except on loopback
• No session: browsers go to the provider, htmx gets HX-Redirect, api clients get 401
• Logout is a POST, and hands the provider no token, so it asks the user to confirm
• Sessions cannot be revoked before the id token expires, so keep that lifetime short
• Cookies are __Host- prefixed, secure and SameSite=Lax, which is not a CSRF token
• User implements slog.LogValuer, so "user", user logs the ecs shaped group

Options

auth, err:=oidcauth.New(ctx, l, cfg,
oidcauth.WithHTTPClient(httpClient), // default timeout 10soidcauth.WithScopes("openid", "email"), // default openid, profile, emailoidcauth.WithRolesClaim("realm_roles"), // default client_rolesoidcauth.WithCookiePrefix("myservice"), // default oidcauthoidcauth.WithBearerAudience("myservice-api"), // default the client id
)

Using OidcClient

The outbound counterpart to OidcAuth: the client credentials grant, for calling another service that verifies bearer tokens.

tokens, err:=oidcclient.New(oidcclient.Config{
Issuer: "https://keycloak.example.com/realms/cego",
ClientID: "myservice",
ClientSecret: os.Getenv("MYSERVICE_OIDC_CLIENT_SECRET"),
})
// Set the header yourselftoken, err:=tokens.Token(ctx)
req.Header.Set(headers.Authorization, "Bearer "+token)
// Or let an http client do it on every requestclient:=tokens.HTTPClient(&http.Client{Timeout: 30*time.Second})
res, err:=client.Do(req)

• The issuer is not contacted until the first Token call, so a provider that is briefly unreachable does not stop the service from starting
• Tokens are cached and replaced DefaultRefreshBefore ahead of their expiry, so a token handed to a caller does not expire in flight
• Concurrent callers share one request to the issuer
• HTTP clients reject cross-origin redirects rather than forwarding the bearer token
• The roles and audiences in the token come from the provider's configuration of the client, not from this package

Options

tokens, err:=oidcclient.New(cfg,
oidcclient.WithHTTPClient(httpClient), // default timeout 10soidcclient.WithScopes("profile", "email"), // default the provider's ownoidcclient.WithRefreshBefore(10*time.Second), // default 30s
)

Headers

req.Header.Get(headers.Authorization)
req.Header.Get(headers.XForwardedFor)

Available constants: XForwardedProto, XForwardedMethod, XForwardedHost, XForwardedUri, XForwardedFor, Accept, UserAgent, Cookie, Authorization, RemoteUser, ContentType

Using Periodic

Context-aware periodic task execution with jitter support.

ctx, stop:=signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
deferstop()
periodic.Run(ctx, 2*time.Second, time.Duration(rand.Intn(1000))*time.Millisecond, func() {
fmt.Println("runs every 2 seconds until ctx is cancelled")
})

Using Serve (Graceful Shutdown)

Graceful HTTP server shutdown with a configurable delay for load balancer deregistration.

srv:=serve.WithDefaults(&http.Server{Addr: ":8080", Handler: myHandler})
ctx, stop:=signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
deferstop()
err:=serve.ListenAndServe(ctx, srv, slog.Default())