gin
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.
The gin integration connects a *iam.BetterIam to a gin engine. Its Middleware serves the IAM HTTP API under
/api/iam and stores the request helpers in the gin context; RequireSession and Authorize are gin handlers that
guard routes; ErrorHandler answers the IAM refusals your handlers report with c.Error. The helpers, guards, and
refusal rules are those of the net/http integration.
The package is named gin, like the framework, so import gin under another name (the examples use gingonic).
Installation
Create the instance
Follow Go: Installation. The examples assume a package-level
instance *iam.BetterIam. The module requires github.com/gin-gonic/gin.
Register the middleware
Register ErrorHandler first and Middleware second. ErrorHandler runs the rest of the chain, then answers the
last error a handler reported.
import (
"log"
"net/http"
gingonic "github.com/gin-gonic/gin"
"github.com/Better-IAM/better-iam/go/middleware"
"github.com/Better-IAM/better-iam/go/middleware/gin"
)
func main() {
iamGin := gin.New(instance, middleware.Options{LoginPath: "/login", StepUpPath: "/verify"})
router := gingonic.New()
router.Use(iamGin.ErrorHandler(), iamGin.Middleware())
// ... routes, below
log.Fatal(router.Run(":3000"))
}Middleware answers requests under the Serve prefixes (default /api/iam) itself and aborts the chain for them.
middleware.Options is described under net/http: Options.
Protect routes
Guards are gin handlers placed before your handler. They answer refusals themselves and abort the chain.
router.GET("/me", iamGin.RequireSession(nil), func(c *gingonic.Context) {
session, err := gin.FromContext(c).GetSession(c.Request.Context())
if err != nil {
_ = c.Error(err)
return
}
c.JSON(http.StatusOK, gingonic.H{"email": session.Get("identity").(*core.Object).Get("email")})
})
router.GET("/projects/:id", iamGin.Authorize("projects:read", middleware.AuthorizeSpec[*gingonic.Context]{
Resource: gin.ResourceFromParam("project", "id"),
}), func(c *gingonic.Context) {
c.JSON(http.StatusOK, gingonic.H{"id": c.Param("id")})
})
router.GET("/secure", iamGin.RequireSession(&middleware.StepUpRequirement{MFA: middleware.MfaRequired}), func(c *gingonic.Context) {})
admin := router.Group("/admin", iamGin.Authorize("iam:identities:update", middleware.AuthorizeSpec[*gingonic.Context]{}))
admin.GET("/people", func(c *gingonic.Context) {})The Resource and TenantID callbacks of middleware.AuthorizeSpec[*gingonic.Context] receive the gin context, so
custom callbacks read parameters with c.Param. 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
gin.ResourceFromParam(type, name) and gin.TenantFromParam(name) build the callbacks from route parameters:
router.GET("/orgs/:tenantId/members", iamGin.Authorize("iam:identities:read", middleware.AuthorizeSpec[*gingonic.Context]{
TenantID: gin.TenantFromParam("tenantId"),
Resource: gin.ResourceFromParam("iam", "tenantId"),
}), func(c *gingonic.Context) {
// list the members of c.Param("tenantId")
})Enforce inside a handler
Report the refusal with c.Error; ErrorHandler answers it with the JSON envelope or a redirect, and any other
error with a plain 500, unless the response already started.
router.DELETE("/documents/:id", iamGin.RequireSession(nil), func(c *gingonic.Context) {
resource := middleware.ResourceRef{Type: "document", ID: c.Param("id")}
if err := gin.FromContext(c).Require(c.Request.Context(), "documents:delete", &resource); err != nil {
_ = c.Error(err) // ErrorHandler answers 403 ACCESS_DENIED
return
}
c.Status(http.StatusNoContent)
})iamGin.Answer(c, err) answers a refusal directly and returns false for any other error.
Read the session
gin.FromContext(c) returns the request's *middleware.Helpers (also stored under c.Get(gin.ContextKey), the key
"iam", and on the request's context). GetSession, Can, Authorize, Plan, Client, Credential, and
SignOut work as on the net/http page; pass them
c.Request.Context().
Reference
| Member | What it does |
|---|---|
gin.New(instance, options) | The integration over a composed server |
gin.NewWith(source, options) | The integration over any middleware.IAM |
gin.NewLazy(resolve, options) | The integration over an instance resolved on first use |
iamGin.Middleware() | Serves the IAM API and attaches the helpers |
iamGin.RequireSession(stepUp), iamGin.Authorize(action, spec) | Guard handlers |
iamGin.ErrorHandler() | Answers the last error reported with c.Error |
iamGin.Answer(c, err) | Answers a refusal; false when err is not one |
iamGin.Helpers(c) | The request's helpers, created on first use |
gin.FromContext(c) | The request's helpers, or nil |
gin.ResourceFromParam(type, name), gin.TenantFromParam(name) | Authorize callbacks from route parameters |
Related
Better IAM is created by Sean Filimon
Last updated
chibeta
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.
echobeta
Serve the Better IAM API from an echo server with echo.New, read the session with echo.FromContext, guard routes with RequireSession and Authorize, and answer refusals with ErrorHandler.