authorization

README

Docker authorization extension api.

Go handler to create external authorization extensions for Docker.

Usage

This library is designed to be integrated in your program.

1. Implement the authorization.Plugin interface.
2. Initialize a authorization.Handler with your implementation.
3. Call either ServeTCP or ServeUnix from the authorization.Handler.

Example using TCP sockets:

  p := MyAuthZPlugin{}
  h := authorization.NewHandler(p)
  h.ServeTCP("test_plugin", ":8080")

Example using Unix sockets:

  p := MyAuthZPlugin{}
  h := authorization.NewHandler(p)
  u, _ := user.Lookup("root")
  gid, _ := strconv.Atoi(u.Gid)
  h.ServeUnix("test_plugin", gid)

Full example plugins

• https://github.com/projectatomic/docker-novolume-plugin
• https://github.com/cpdevws/img-authz-plugin
• https://github.com/casbin/casbin-authz-plugin
• https://github.com/kassisol/hbm
• https://github.com/leogr/docker-authz-plugin

License

MIT

Documentation

Index

• Constants
• type Handler
  • func NewHandler(plugin Plugin) *Handler
• type PeerCertificate
  • func (pc *PeerCertificate) MarshalJSON() ([]byte, error)
  • func (pc *PeerCertificate) UnmarshalJSON(b []byte) error
• type Plugin
• type Request
• type Response

Constants

const (
	// AuthZApiRequest is the url for daemon request authorization
	AuthZApiRequest = "AuthZPlugin.AuthZReq"

	// AuthZApiResponse is the url for daemon response authorization
	AuthZApiResponse = "AuthZPlugin.AuthZRes"

	// AuthZApiImplements is the name of the interface all AuthZ plugins implement
	AuthZApiImplements = "authz"
)

Types

type Handler

type Handler struct {
	sdk.Handler
	// contains filtered or unexported fields
}

Handler forwards requests and responses between the docker daemon and the plugin.

func NewHandler

func NewHandler(plugin Plugin) *Handler

NewHandler initializes the request handler with a plugin implementation.

type PeerCertificate

type PeerCertificate x509.Certificate

PeerCertificate is a wrapper around x509.Certificate which provides a sane encoding/decoding to/from PEM format and JSON.

func (*PeerCertificate) MarshalJSON

func (pc *PeerCertificate) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoded pem bytes of a PeerCertificate.

func (*PeerCertificate) UnmarshalJSON

func (pc *PeerCertificate) UnmarshalJSON(b []byte) error

UnmarshalJSON populates a new PeerCertificate struct from JSON data.

type Plugin

type Plugin interface {
	AuthZReq(Request) Response
	AuthZRes(Request) Response
}

Plugin represent the interface a plugin must fulfill.

type Request

type Request struct {
	// User holds the user extracted by AuthN mechanism
	User string `json:"User,omitempty"`

	// UserAuthNMethod holds the mechanism used to extract user details (e.g., krb)
	UserAuthNMethod string `json:"UserAuthNMethod,omitempty"`

	// RequestMethod holds the HTTP method (GET/POST/PUT)
	RequestMethod string `json:"RequestMethod,omitempty"`

	// RequestUri holds the full HTTP uri (e.g., /v1.21/version)
	RequestURI string `json:"RequestUri,omitempty"`

	// RequestBody stores the raw request body sent to the docker daemon
	RequestBody []byte `json:"RequestBody,omitempty"`

	// RequestHeaders stores the raw request headers sent to the docker daemon
	RequestHeaders map[string]string `json:"RequestHeaders,omitempty"`

	// RequestPeerCertificates stores the request's TLS peer certificates in PEM format
	RequestPeerCertificates []*PeerCertificate `json:"RequestPeerCertificates,omitempty"`

	// ResponseStatusCode stores the status code returned from docker daemon
	ResponseStatusCode int `json:"ResponseStatusCode,omitempty"`

	// ResponseBody stores the raw response body sent from docker daemon
	ResponseBody []byte `json:"ResponseBody,omitempty"`

	// ResponseHeaders stores the response headers sent to the docker daemon
	ResponseHeaders map[string]string `json:"ResponseHeaders,omitempty"`
}

Request holds data required for authZ plugins

type Response

type Response struct {
	// Allow indicating whether the user is allowed or not
	Allow bool `json:"Allow"`

	// Msg stores the authorization message
	Msg string `json:"Msg,omitempty"`

	// Err stores a message in case there's an error
	Err string `json:"Err,omitempty"`
}

Response represents authZ plugin response