permissions

README

Permissions library

The permissions library determines whether a user has a particular permission. It can be used within middleware to apply permissions to an entire endpoint, or can be used within a handler for more fine grained permissions.

The library polls the permissions API in the background for permissions updates and keeps an in memory cache of the data for a set period of time.

Usage

Create a new instance of permissions.Checker

  import (
	"github.com/ONSdigital/dp-authorisation/v2/permissions"
  )
  
  ...
  
  permissionsAPIHost := "localhost:25400"
  cacheUpdateInterval := time.Minute
  expiryCheckInterval := time.Second * 5
  maxCacheTime := time.Minute * 5
	
  permissions.NewChecker(ctx, permissionsAPIHost, cacheUpdateInterval, expiryCheckInterval, maxCacheTime)

Parameter values should come from configuration. The example values have been left in for clarity.

• permissionsAPIHost: the hostname of the permissions API
• cacheUpdateInterval: how long between updates of the permissions cache
• expiryCheckInterval: how long between checks for expired cache data
• maxCacheTime: how long before the permissions cache data should be expired

Register the health checker function

err := healthCheck.AddCheck("permissions checker", permissionChecker.HealthCheck)
	

Any service that uses the permission library should register the health checker function with the service's health checks

Close the library when finished

err := permissionChecker.Close(ctx)

The Close function should be called on the library when it is no longer required. (usually when the service is shutdown)

Check if a user has a permission

  entityData := permsdk.EntityData{
    UserID: "1234",
    Groups: []string{"admin"},
  }
  permission := "legacy.read"
  attributes := map[string]string{"collection_id": "collection123"}

  hasPermission, err := permissionChecker.HasPermission(ctx, entityData, permission, attributes)
  if err != nil {
    return 
  }

• entityData: data for the user / service requesting the permission. For a user, the user ID and group list will come from the JWT token.
• permission: the permission that is being checked.
• attributes: other key/value attributes for use in access control decision, e.g. collectionID. These values are used when evaluating any conditions of a policy.

Low level detail

• permissions.Checker: retrieves permission data from the store, and determines if a user has a permission.
• permissions.Store: interface used by the checker to retrieve permission data.
• permissions.APIClient: Store implementation to get data from the permissions API.
• permissions.CachingStore: Store implementation wraps another store (i.e. the APIClient) and caches permission data in memory.
  • polls the underlying store in the background to update cache data.
  • expires cache data if it reaches a certain age.

Documentation

Overview

Package permissions provides library functions to determine if a user/service has a particular permission.

A user can be identified by the user ID, or the groups that it belongs to. A service 'user' is identified by a service ID. Users, groups and services are treated the same for permissions purposes, so have the common name Entities.

Entities are associated with permissions/roles via policies. For an entity to have a permission, there must be at least one policy that applies to that entity and permission. Policies can also have conditions that need to be met for the policy to apply. A policy with no conditions is equivalent to a policy where all conditions are met.

Index

• type Cache
• type CachingStore
  • func NewCachingStore(underlyingStore Store) *CachingStore
  • func (c *CachingStore) CheckCacheExpiry(ctx context.Context, maxCacheTime time.Duration)
  • func (c *CachingStore) Close(_ context.Context) error
  • func (c *CachingStore) GetPermissionsBundle(_ context.Context) (permsdk.Bundle, error)
  • func (c *CachingStore) HealthCheck(_ context.Context, state *health.CheckState) error
  • func (c *CachingStore) StartCacheUpdater(ctx context.Context, updateInterval, maxCacheTime time.Duration)
  • func (c *CachingStore) Update(ctx context.Context, maxCacheTime time.Duration) (permsdk.Bundle, error)
• type Checker
  • func NewChecker(ctx context.Context, permissionsAPIHost string, ...) *Checker
  • func NewCheckerForStore(cache Cache) *Checker
  • func (c Checker) Close(ctx context.Context) error
  • func (c Checker) HasPermission(ctx context.Context, entityData permsdk.EntityData, permission string, ...) (bool, error)
  • func (c Checker) HealthCheck(ctx context.Context, state *health.CheckState) error
• type Store

Types

type Cache

type Cache interface {
	Store
	Close(ctx context.Context) error
	HealthCheck(ctx context.Context, state *health.CheckState) error
}

Cache represents a cache of permissions data.

type CachingStore

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

CachingStore is a permissions store implementation that caches permission data in memory.

func NewCachingStore

func NewCachingStore(underlyingStore Store) *CachingStore

NewCachingStore constructs a new instance of CachingStore

func (*CachingStore) CheckCacheExpiry

func (c *CachingStore) CheckCacheExpiry(ctx context.Context, maxCacheTime time.Duration)

CheckCacheExpiry clears the cache data it it's gone beyond it's expiry time.

func (*CachingStore) Close

func (c *CachingStore) Close(_ context.Context) error

Close stops go routines and blocks until closed.

func (*CachingStore) GetPermissionsBundle

func (c *CachingStore) GetPermissionsBundle(_ context.Context) (permsdk.Bundle, error)

GetPermissionsBundle returns the cached permission data, or an error if it's not cached.

func (*CachingStore) HealthCheck

func (c *CachingStore) HealthCheck(_ context.Context, state *health.CheckState) error

func (*CachingStore) StartCacheUpdater

func (c *CachingStore) StartCacheUpdater(ctx context.Context, updateInterval, maxCacheTime time.Duration)

StartCacheUpdater starts a go routine to continually update cache data at time intervals.

• updateInterval - how often to update the cache data.

func (*CachingStore) Update

func (c *CachingStore) Update(ctx context.Context, maxCacheTime time.Duration) (permsdk.Bundle, error)

Update the permissions cache data, by calling the underlying permissions store

type Checker

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

Checker reads permission data and verifies that a user has a permission

func NewChecker

func NewChecker(
	ctx context.Context,
	permissionsAPIHost string,
	cacheUpdateInterval,
	maxCacheTime time.Duration) *Checker

NewChecker creates a new Checker instance that uses the permissions API client, wrapped in a CachingStore

func NewCheckerForStore

func NewCheckerForStore(cache Cache) *Checker

NewCheckerForStore creates a new Checker instance.

func (Checker) Close

func (c Checker) Close(ctx context.Context) error

Close resources used by the checker.

func (Checker) HasPermission

func (c Checker) HasPermission(
	ctx context.Context,
	entityData permsdk.EntityData,
	permission string,
	attributes map[string]string) (bool, error)

HasPermission returns true if one of the given entities has the given permission.

entityData - ID of the caller (user or service), as well as any associated groups
permission - the action or permission the user wants to take, e.g. `datasets:edit`
attributes - other key value attributes for use in access control decision, e.g. `collectionID`, `datasetID`, `isPublished`, `roleId`, etc

func (Checker) HealthCheck

func (c Checker) HealthCheck(ctx context.Context, state *health.CheckState) error

type Store

type Store interface {
	GetPermissionsBundle(ctx context.Context) (permsdk.Bundle, error)
}

Store represents a store of permission data The implementation can be a client of the permissions API, though a cache implementation can also be wrapped around it.