BetterIAM
Go

echo

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.

betagithub.com/Better-IAM/better-iam/go/middleware/echoecho.goecho_test.gonethttp.goindex.go

The echo integration connects a *iam.BetterIam to an echo server. Its Middleware serves the IAM HTTP API under /api/iam and stores the request helpers in the echo context; RequireSession and Authorize are route middleware; ErrorHandler is an HTTPErrorHandler that answers the IAM refusals your handlers return. The helpers, guards, and refusal rules are those of the net/http integration.

The package is named echo, like the framework, so import echo under another name (the examples use labstack).

Installation

Create the instance

Follow Go: Installation. The examples assume a package-level instance *iam.BetterIam. The module requires github.com/labstack/echo/v4.

Register the middleware

Install the error handler and the middleware. ErrorHandler(fallback) answers IAM refusals and passes every other error to fallback (echo's default handler here, so echo.HTTPError values keep their own responses).

main.go
import (
	"net/http"

	labstack "github.com/labstack/echo/v4"

	"github.com/Better-IAM/better-iam/go/middleware"
	"github.com/Better-IAM/better-iam/go/middleware/echo"
)

func main() {
	iamEcho := echo.New(instance, middleware.Options{LoginPath: "/login", StepUpPath: "/verify"})

	e := labstack.New()
	e.HTTPErrorHandler = iamEcho.ErrorHandler(e.DefaultHTTPErrorHandler)
	e.Use(iamEcho.Middleware())

	// ... routes, below

	e.Logger.Fatal(e.Start(":3000"))
}

With a nil fallback, other errors are logged and answered with a plain 500. middleware.Options is described under net/http: Options.

Protect routes

Guards are echo middleware; pass them after the handler, or to a group.

main.go
e.GET("/me", func(c labstack.Context) error {
	session, err := echo.FromContext(c).GetSession(c.Request().Context())
	if err != nil {
		return err
	}
	return c.JSON(http.StatusOK, map[string]any{"email": session.Get("identity").(*core.Object).Get("email")})
}, iamEcho.RequireSession(nil))

e.GET("/projects/:id", func(c labstack.Context) error {
	return c.JSON(http.StatusOK, map[string]any{"id": c.Param("id")})
}, iamEcho.Authorize("projects:read", middleware.AuthorizeSpec[labstack.Context]{
	Resource: echo.ResourceFromParam("project", "id"),
}))

e.GET("/secure", func(c labstack.Context) error { return nil },
	iamEcho.RequireSession(&middleware.StepUpRequirement{MFA: middleware.MfaRequired}))

admin := e.Group("/admin", iamEcho.Authorize("iam:identities:update", middleware.AuthorizeSpec[labstack.Context]{}))
admin.GET("/people", func(c labstack.Context) error { return nil })

The Resource and TenantID callbacks of middleware.AuthorizeSpec[labstack.Context] receive the echo 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

echo.ResourceFromParam(type, name) and echo.TenantFromParam(name) build the callbacks from route parameters:

main.go
e.GET("/orgs/:tenantId/members", func(c labstack.Context) error {
	return nil // list the members of c.Param("tenantId")
}, iamEcho.Authorize("iam:identities:read", middleware.AuthorizeSpec[labstack.Context]{
	TenantID: echo.TenantFromParam("tenantId"),
	Resource: echo.ResourceFromParam("iam", "tenantId"),
}))

Enforce inside a handler

Return the refusal; ErrorHandler answers it with the JSON envelope or a redirect.

main.go
e.DELETE("/documents/:id", func(c labstack.Context) error {
	resource := middleware.ResourceRef{Type: "document", ID: c.Param("id")}
	if err := echo.FromContext(c).Require(c.Request().Context(), "documents:delete", &resource); err != nil {
		return err // ErrorHandler answers 403 ACCESS_DENIED
	}
	return c.NoContent(http.StatusNoContent)
}, iamEcho.RequireSession(nil))

iamEcho.Answer(c, err) answers a refusal directly and returns false for any other error.

Read the session

echo.FromContext(c) returns the request's *middleware.Helpers (also stored under c.Get(echo.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

MemberWhat it does
echo.New(instance, options)The integration over a composed server
echo.NewWith(source, options)The integration over any middleware.IAM
echo.NewLazy(resolve, options)The integration over an instance resolved on first use
iamEcho.Middleware()Serves the IAM API and attaches the helpers
iamEcho.RequireSession(stepUp), iamEcho.Authorize(action, spec)Route middleware guards
iamEcho.ErrorHandler(fallback)An HTTPErrorHandler that answers refusals and passes other errors to fallback
iamEcho.Answer(c, err)Answers a refusal; false when err is not one
iamEcho.Helpers(c)The request's helpers, created on first use
echo.FromContext(c)The request's helpers, or nil
echo.ResourceFromParam(type, name), echo.TenantFromParam(name)Authorize callbacks from route parameters

Was this page helpful?

Better IAM is created by Sean Filimon

Last updated

On this page