chi
Serve the Better IAM API from a chi router with chi.New, guard routes with router.With, and read route parameters in authorize guards with ResourceFromParam and TenantFromParam.
chi middlewares are net/http middlewares, so the chi integration is the
net/http integration with helpers that read chi route parameters. chi.New
returns an *chi.IamChi, which embeds *middleware.Middleware: everything on the net/http page applies, including
middleware.FromRequest(r) for the request helpers.
The package is named chi, like the router, so import the router under another name (the examples use
chirouter).
Installation
Create the instance
Follow Go: Installation. The examples assume a package-level
instance *iam.BetterIam. The module requires github.com/go-chi/chi/v5.
Mount the integration
router.Use(iamChi.Handler) serves the IAM API under /api/iam and attaches the helpers to every other request.
Register it before your routes.
import (
"log"
"net/http"
chirouter "github.com/go-chi/chi/v5"
"github.com/Better-IAM/better-iam/go/middleware"
"github.com/Better-IAM/better-iam/go/middleware/chi"
)
func main() {
iamChi := chi.New(instance, middleware.Options{LoginPath: "/login", StepUpPath: "/verify"})
router := chirouter.NewRouter()
router.Use(iamChi.Handler) // serves /api/iam and attaches the request helpers
// ... routes, below
log.Fatal(http.ListenAndServe(":3000", router))
}middleware.Options is described under net/http: Options.
Protect routes
Guards are chi middlewares; attach them with router.With for one route or Use inside a route group.
router.With(iamChi.RequireSession(nil)).Get("/me", iamChi.Wrap(func(w http.ResponseWriter, r *http.Request) error {
session, err := middleware.FromRequest(r).GetSession(r.Context())
if err != nil {
return err
}
_, err = w.Write([]byte(session.Get("identity").(*core.Object).Get("email").(string)))
return err
}).ServeHTTP)
router.With(iamChi.Authorize("projects:read", middleware.AuthorizeSpec[*http.Request]{
Resource: chi.ResourceFromParam("project", "id"),
})).Get("/projects/{id}", func(w http.ResponseWriter, r *http.Request) {
_, _ = w.Write([]byte(chirouter.URLParam(r, "id")))
})
router.With(iamChi.RequireSession(&middleware.StepUpRequirement{MFA: middleware.MfaRequired})).
Get("/secure", func(w http.ResponseWriter, r *http.Request) {})
router.Route("/admin", func(admin chirouter.Router) {
admin.Use(iamChi.Authorize("iam:identities:update", middleware.AuthorizeSpec[*http.Request]{}))
admin.Get("/people", func(w http.ResponseWriter, r *http.Request) {})
})A signed-out API call gets 401 UNAUTHENTICATED, a denied one 403 ACCESS_DENIED, and page navigations are
redirected to LoginPath or StepUpPath. See net/http: Protect routes
for the refusal rules and the CSRF check.
Route parameters
chi.ResourceFromParam(type, name) and chi.TenantFromParam(name) build the Resource and TenantID callbacks of
an authorize guard from chi's URLParam:
router.With(iamChi.Authorize("iam:identities:read", middleware.AuthorizeSpec[*http.Request]{
TenantID: chi.TenantFromParam("tenantId"),
Resource: chi.ResourceFromParam("iam", "tenantId"),
})).Get("/orgs/{tenantId}/members", func(w http.ResponseWriter, r *http.Request) {
// list the members of chirouter.URLParam(r, "tenantId")
})A session of another tenant gets 403 here: the check runs in the tenant the URL names.
Enforce inside a handler
Return the refusal from a handler wrapped with iamChi.Wrap. Wrap returns an http.Handler; pass its
ServeHTTP where chi wants a HandlerFunc.
router.Delete("/documents/{id}", iamChi.Wrap(func(w http.ResponseWriter, r *http.Request) error {
resource := middleware.ResourceRef{Type: "document", ID: chirouter.URLParam(r, "id")}
if err := middleware.FromRequest(r).Require(r.Context(), "documents:delete", &resource); err != nil {
return err // 403 ACCESS_DENIED
}
w.WriteHeader(http.StatusNoContent)
return nil
}).ServeHTTP)Read the session
Handlers read the helpers with middleware.FromRequest(r): GetSession, Can, Authorize, Plan, Client,
Credential, and SignOut work as on the net/http page.
Reference
| Member | What it does |
|---|---|
chi.New(instance, options) | The integration over a composed server |
chi.NewWith(source, options) | The integration over any middleware.IAM |
chi.NewLazy(resolve, options) | The integration over an instance resolved on first use |
iamChi.Handler | Middleware for router.Use: serves the IAM API and attaches the helpers |
iamChi.RequireSession(stepUp), iamChi.Authorize(action, spec) | Guards for router.With and Use |
iamChi.Wrap(handler), iamChi.HandleError(w, r, err) | Refusal answers |
chi.ResourceFromParam(type, name) | An authorize Resource callback naming a resource by a route parameter |
chi.TenantFromParam(name) | An authorize TenantID callback reading the tenant from a route parameter |
Related
Better IAM is created by Sean Filimon
Last updated
net/httpbeta
Serve the Better IAM API from a Go net/http server with middleware.New, read the session with middleware.FromRequest, and guard routes with RequireSession and Authorize.
ginbeta
Serve the Better IAM API from a gin engine with gin.New, read the session with gin.FromContext, guard routes with RequireSession and Authorize, and answer refusals with ErrorHandler.