perm

README

perm

API Documentation

This Permissions service ("perm") provides authorization features for the Cloud Foundry Platform. It answers various question forms of what particular identities are allowed to do. It works out the answers to these questions based on the roles assigned to users and the roles assigned to the groups they are a member of.

Even though the service was originally created to add authorization features to Cloud Controller, other components in the system are looking to migrate to storing their authorization rules in Perm.

Installation

To fetch all source code, including the Go client library:

go get -u code.cloudfoundry.org/perm

To fetch and install the server's CLI:

go get -u code.cloudfoundry.org/perm/cmd/perm

To fetch and install the monitor's CLI:

go get -u code.cloudfoundry.org/perm/cmd/perm-monitor

Running the Tests

Assuming you have the Perm source code in your $GOPATH:

go install code.cloudfoundry.org/perm/vendor/github.com/onsi/ginkgo/ginkgo
ginkgo -r -race -p -randomizeAllSpecs -randomizeSuites

Running the Perm Server

First, make sure that you have the CLI installed:

go get -u code.cloudfoundry.org/perm
go install code.cloudfoundry.org/perm/cmd/perm

To use an in-memory data store, e.g., for testing purposes:

perm serve --tls-cert <path> --tls-key <path> --db-driver in-memory

To use mysql:

perm migrate up --db-driver mysql --db-host <host> --db-port <port> --db-username <username> --db-password <password>
perm serve --tls-cert <path> --tls-key <path> --db-driver mysql --db-host <host> --db-port <port> --db-username <username> --db-password <password>

Running the Perm Monitor

The monitor is a small app that repeats the same basic workflow every interval, generating traffic and tracking some client-side metrics.

Make sure that you have the monitor's CLI:

go get -u code.cloudfoundry.org/perm
go install code.cloudfoundry.org/perm/cmd/perm-monitor

Make sure that you have a statsd daemon, e.g., with docker:

docker run -d -p 8125:8125 --name statsd hopsoft/graphite-statsd

Then, start the monitor:

perm-monitor --perm-tls-ca <path>

In Popular Culture

This repository is complemented by 2 other repositories.

• perm-release

  This is the BOSH release for deploying the perm service.

• perm-rb

  This is the Ruby library for interacting with perm. It is used by Cloud Controller to perform administration and checking of permissions.

For more information, check out our page on Repository Structure.

Usage

Not yet, please.

Documentation

Index

• Variables
• func NewErrorFromStatus(s *status.Status) error
• type Action
• type Actor
• type Client
  • func Dial(addr string, dialOpts ...DialOption) (*Client, error)
  • func (c *Client) AssignRole(ctx context.Context, roleName string, actor Actor) error
  • func (c *Client) AssignRoleToGroup(ctx context.Context, roleName string, group Group) error
  • func (c *Client) Close() error
  • func (c *Client) CreateRole(ctx context.Context, name string, permissions ...Permission) (Role, error)
  • func (c *Client) DeleteRole(ctx context.Context, name string) error
  • func (c *Client) HasPermission(ctx context.Context, actor Actor, action, resource string) (bool, error)
  • func (c *Client) ListResourcePatterns(ctx context.Context, actor Actor, action string) ([]string, error)
  • func (c *Client) UnassignRole(ctx context.Context, roleName string, actor Actor) error
  • func (c *Client) UnassignRoleFromGroup(ctx context.Context, roleName string, group Group) error
• type DialOption
  • func WithTLSConfig(config *tls.Config) DialOption
  • func WithTokenSource(tokenSource oauth2.TokenSource) DialOption
• type ErrAlreadyExists
  • func NewErrAlreadyExists(model string) ErrAlreadyExists
  • func (err ErrAlreadyExists) Error() string
• type ErrNotFound
  • func NewErrNotFound(model string) ErrNotFound
  • func (err ErrNotFound) Error() string
• type Group
• type Permission
• type Role

Variables

var (
	ErrFailedToConnect     = errors.New("perm: failed to connect")
	ErrUnauthenticated     = errors.New("perm: unauthenticated")
	ErrNoTransportSecurity = errors.New("perm: no transport security set (use perm.WithTLSConfig() to set)")
	ErrClientConnClosing   = errors.New("perm: the client connection is already closing or closed")

	ErrRoleNotFound      = NewErrNotFound("role")
	ErrRoleAlreadyExists = NewErrAlreadyExists("role")

	ErrAssignmentNotFound      = NewErrNotFound("assignment")
	ErrAssignmentAlreadyExists = NewErrAlreadyExists("assignment")
)

Functions

func NewErrorFromStatus

func NewErrorFromStatus(s *status.Status) error

Types

type Action

type Action struct {
	Name string
}

type Actor

type Actor struct {
	ID        string
	Namespace string
}

type Client

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

func Dial

func Dial(addr string, dialOpts ...DialOption) (*Client, error)

func (*Client) AssignRole

func (c *Client) AssignRole(ctx context.Context, roleName string, actor Actor) error

func (*Client) AssignRoleToGroup

func (c *Client) AssignRoleToGroup(ctx context.Context, roleName string, group Group) error

func (*Client) Close

func (c *Client) Close() error

func (*Client) CreateRole

func (c *Client) CreateRole(ctx context.Context, name string, permissions ...Permission) (Role, error)

func (*Client) DeleteRole

func (c *Client) DeleteRole(ctx context.Context, name string) error

func (*Client) HasPermission

func (c *Client) HasPermission(ctx context.Context, actor Actor, action, resource string) (bool, error)

func (*Client) ListResourcePatterns

func (c *Client) ListResourcePatterns(ctx context.Context, actor Actor, action string) ([]string, error)

func (*Client) UnassignRole

func (c *Client) UnassignRole(ctx context.Context, roleName string, actor Actor) error

func (*Client) UnassignRoleFromGroup

func (c *Client) UnassignRoleFromGroup(ctx context.Context, roleName string, group Group) error

type DialOption

type DialOption func(*options)

func WithTLSConfig

func WithTLSConfig(config *tls.Config) DialOption

func WithTokenSource

func WithTokenSource(tokenSource oauth2.TokenSource) DialOption

type ErrAlreadyExists

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

func NewErrAlreadyExists

func NewErrAlreadyExists(model string) ErrAlreadyExists

func (ErrAlreadyExists) Error

func (err ErrAlreadyExists) Error() string

type ErrNotFound

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

func NewErrNotFound

func NewErrNotFound(model string) ErrNotFound

func (ErrNotFound) Error

func (err ErrNotFound) Error() string

type Group

type Group struct {
	ID string
}

type Permission

type Permission struct {
	Action          string
	ResourcePattern string
}

type Role

type Role struct {
	Name string
}