http

Documentation

Overview

Package http provides authorization middleware for HTTP servers built on top of net/http.

The middleware intercepts incoming requests and calls the Aserto authorizer service to determine if access should be allowed or denied.

Example

package main

import (
	"context"
	"log"
	"net/http"

	"github.com/aserto-dev/aserto-go/authorizer/grpc"
	"github.com/aserto-dev/aserto-go/client"
	mw "github.com/aserto-dev/aserto-go/middleware/http"
)

func Hello(w http.ResponseWriter, r *http.Request) {
	if _, err := w.Write([]byte(`"hello"`)); err != nil {
		log.Println("Failed to write HTTP response:", err)
	}
}

func main() {
	ctx := context.Background()

	// Create authorizer client.
	authorizer, err := grpc.New(
		ctx,
		client.WithAPIKeyAuth("<Aserto authorizer API Key>"),
		client.WithTenantID("<Aserto tenant ID>"),
	)
	if err != nil {
		log.Fatal("Failed to create authorizer client:", err)
	}

	// Create HTTP middleware.
	middleware := mw.New(
		authorizer,
		mw.Policy{
			ID:       "<Aserto policy ID>",
			Decision: "<authorization decision (e.g. 'allowed')",
		},
	)

	// Define HTTP route.
	http.Handle(
		"/",
		middleware.Handler(http.HandlerFunc(Hello)), // Attach middleware to route.
	)

	// Start server.
	log.Fatal(http.ListenAndServe(":8080", nil))
}

Index

• type AuthorizerClient
• type IdentityBuilder
  • func (b *IdentityBuilder) FromContextValue(key interface{}) *IdentityBuilder
  • func (b *IdentityBuilder) FromHeader(header ...string) *IdentityBuilder
  • func (b *IdentityBuilder) FromHostname(segment int) *IdentityBuilder
  • func (b *IdentityBuilder) ID(identity string) *IdentityBuilder
  • func (b *IdentityBuilder) JWT() *IdentityBuilder
  • func (b *IdentityBuilder) Mapper(mapper IdentityMapper) *IdentityBuilder
  • func (b *IdentityBuilder) None() *IdentityBuilder
  • func (b *IdentityBuilder) Subject() *IdentityBuilder
• type IdentityMapper
• type Middleware
  • func New(client AuthorizerClient, policy Policy) *Middleware
  • func (m *Middleware) Handler(next http.Handler) http.Handler
  • func (m *Middleware) WithPolicyFromURL(prefix string) *Middleware
  • func (m *Middleware) WithPolicyPathMapper(mapper StringMapper) *Middleware
  • func (m *Middleware) WithResourceMapper(mapper StructMapper) *Middleware
• type Policy
• type StringMapper
• type StructMapper

Examples

• Package

Types

type AuthorizerClient

type AuthorizerClient = authorizer.AuthorizerClient

type IdentityBuilder

type IdentityBuilder struct {
	// contains filtered or unexported fields
}

IdentityBuilder is used to configure what information about caller identity is sent in authorization calls.

func (*IdentityBuilder) FromContextValue

func (b *IdentityBuilder) FromContextValue(key interface{}) *IdentityBuilder

FromContextValue extracts caller identity from a value in the incoming request context.

If the value is not present, not a string, or an empty string then the request is considered anonymous.

func (*IdentityBuilder) FromHeader

func (b *IdentityBuilder) FromHeader(header ...string) *IdentityBuilder

FromHeader retrieves caller identity from request headers.

Headers are attempted in order. The first non-empty header is used. If none of the specified headers have a value, the request is considered anonymous.

func (*IdentityBuilder) FromHostname

func (b *IdentityBuilder) FromHostname(segment int) *IdentityBuilder

FromHostname extracts caller identity from the incoming request's host name.

The function returns the specified hostname segment. Indexing is zero-based and starts from the left. Negative indices start from the right.

For Example, if the hostname is "service.user.company.com" then both FromHostname(1) and FromHostname(-3) return the value "user".

func (*IdentityBuilder) ID

func (b *IdentityBuilder) ID(identity string) *IdentityBuilder

Call ID(...) to set the user's identity. If neither JWT() or Subject() are called too, IdentityMapper tries to infer whether the specified identity is a JWT or not. Passing an empty string is the same as calling .None() and results in an authorization check for anonymous access.

func (*IdentityBuilder) JWT

func (b *IdentityBuilder) JWT() *IdentityBuilder

Call JWT() to indicate that the user's identity is expressed as a string-encoded JWT.

JWT() is always called in conjunction with another method that provides the user ID itself. For example:

idBuilder.JWT().FromHeader("Authorization")

func (*IdentityBuilder) Mapper

func (b *IdentityBuilder) Mapper(mapper IdentityMapper) *IdentityBuilder

Mapper takes a custom IdentityMapper to be used for extracting identity information from incomign requests.

func (*IdentityBuilder) None

func (b *IdentityBuilder) None() *IdentityBuilder

Call None() to indicate that requests are unauthenticated.

func (*IdentityBuilder) Subject

func (b *IdentityBuilder) Subject() *IdentityBuilder

Subject() is always used in conjunction with another methd that provides the user ID itself. For example:

idBuilder.Subject().FromContextValue("username")

type IdentityMapper

type IdentityMapper func(*http.Request, middleware.Identity)

IdentityMapper is the type of callback functions that can inspect incoming HTTP requests and set the caller's identity.

type Middleware

type Middleware struct {
	// Identity determines the caller identity used in authorization calls.
	Identity *IdentityBuilder
	// contains filtered or unexported fields
}

Middleware implements an http.Handler that can be added to routes in net/http servers.

To authorize incoming requests, the middleware needs information about:

1. The user making the request.

2. The Aserto authorization policy to evaluate.

3. Optional, additional input data to the authorization policy.

The values for these parameters can be set globally or extracted dynamically from incoming messages.

func New

func New(client AuthorizerClient, policy Policy) *Middleware

New creates middleware for the specified policy.

The new middleware is created with default identity and policy path mapper. Those can be overridden using `Middleware.Identity` to specify the caller's identity, or using the middleware's ".With...()" functions to set policy path and resource mappers.

func (*Middleware) Handler

func (m *Middleware) Handler(next http.Handler) http.Handler

Handler is the middleware implementation. It is how an Authorizer is wired to an HTTP server.

func (*Middleware) WithPolicyFromURL

func (m *Middleware) WithPolicyFromURL(prefix string) *Middleware

WithPolicyFromURL instructs the middleware to construct the policy path from the path segment of the incoming request's URL.

Path separators ('/') are replaced with dots ('.'). If the request uses gorilla/mux to define path parameters, those are added to the path with two leading underscores. An optional prefix can be specified to be included in all paths.

Example

Using 'WithPolicyFromURL("myapp")', the route

POST /products/{id}

becomes the policy path

"myapp.POST.products.__id"

func (*Middleware) WithPolicyPathMapper

func (m *Middleware) WithPolicyPathMapper(mapper StringMapper) *Middleware

WithPolicyPathMapper sets a custom policy mapper, a function that takes an incoming request and returns the path within the policy of the package to query.

func (*Middleware) WithResourceMapper

func (m *Middleware) WithResourceMapper(mapper StructMapper) *Middleware

WithResourceMapper sets a custom resource mapper, a function that takes an incoming request and returns the resource object to include with the authorization request as a `structpb.Struct`.

type Policy

type Policy = middleware.Policy

type StringMapper

type StringMapper func(*http.Request) string

StringMapper functions are used to extract string values from incoming messages. They are used to define policy mappers.

type StructMapper

type StructMapper func(*http.Request) *structpb.Struct

StructMapper functions are used to extract structured data from incoming message. The optional resource mapper is a StructMapper.