authz

Documentation

Index

• Variables
• type AuthorizationInfo
  • func NewAuthorizationInfo() *AuthorizationInfo
  • func (a *AuthorizationInfo) AddPermission(permissions ...*Permission) *AuthorizationInfo
  • func (a *AuthorizationInfo) AddPermissionString(permissions ...string) *AuthorizationInfo
  • func (a *AuthorizationInfo) AddRole(roles ...string) *AuthorizationInfo
  • func (a *AuthorizationInfo) HasAllRoles(roles ...string) bool
  • func (a *AuthorizationInfo) HasAnyRole(roles ...string) bool
  • func (a *AuthorizationInfo) HasRole(role string) bool
  • func (a *AuthorizationInfo) IsPermitted(permission string) bool
  • func (a *AuthorizationInfo) IsPermittedAll(permissions ...string) bool
  • func (a *AuthorizationInfo) IsPermittedAllp(permissions ...*Permission) bool
  • func (a *AuthorizationInfo) IsPermittedp(permission *Permission) bool
  • func (a *AuthorizationInfo) Permissions() string
  • func (a *AuthorizationInfo) Roles() string
  • func (a AuthorizationInfo) String() string
• type Authorizer
• type Permission
  • func NewPermission(permission string) (*Permission, error)
  • func NewPermissioncs(permission string, caseSensitive bool) (*Permission, error)
  • func (p *Permission) Implies(permission *Permission) bool
  • func (p *Permission) Reset()
  • func (p Permission) String() string
• type Reason
  • func (r Reason) Error() string
  • func (r Reason) String() string

Variables

var (
	// ErrPermissionStringEmpty returned when empty permission string supplied to
	// methods `security.authz.NewPermission` or `security.authz.NewPermissioncs`.
	ErrPermissionStringEmpty = errors.New("security/authz: permission string is empty")

	// ErrPermissionImproperFormat returned when permission string is composed or
	// formatted properly.
	//    For e.g.:
	//    "printer:print,query:epsoncolor"     # properly formatted
	//    "printer::epsoncolor"                # improperly formatted
	//    "printer::"                          # improperly formatted
	ErrPermissionImproperFormat = errors.New("security: permission string cannot contain parts with only dividers")
)

var (
	// ErrAuthorizerIsNil error is return when authorizer is nil in the auth scheme.
	ErrAuthorizerIsNil = errors.New("security/authz: authorizer is nil")
)

Types

type AuthorizationInfo

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

AuthorizationInfo struct holds the information of Subject authorization. It performs authorization (access control) operations for any given Subject (aka 'application user').

Note that you can add and evaluate Permissions using string and instance. aah framework by default implementations do String-to-Permission conversion.

These string methods do forego type-safety for the benefit of convenience and simplicity, so you should choose which ones to use based on your preferences and needs.

func NewAuthorizationInfo

func NewAuthorizationInfo() *AuthorizationInfo

NewAuthorizationInfo method creates an `AuthorizationInfo` instance with zero values. Use the returned instance to add roles and permissions for the Subject (aka User).

func (*AuthorizationInfo) AddPermission

func (a *AuthorizationInfo) AddPermission(permissions ...*Permission) *AuthorizationInfo

AddPermission method assigns a permission to those directly associated with the account.

func (*AuthorizationInfo) AddPermissionString

func (a *AuthorizationInfo) AddPermissionString(permissions ...string) *AuthorizationInfo

AddPermissionString method assigns multiple permissions to those associated directly with the account.

func (*AuthorizationInfo) AddRole

func (a *AuthorizationInfo) AddRole(roles ...string) *AuthorizationInfo

AddRole method assigns a multiple-role to those associated with the account.

func (*AuthorizationInfo) HasAllRoles

func (a *AuthorizationInfo) HasAllRoles(roles ...string) bool

HasAllRoles method returns true if the Subject has all of the specified roles, otherwise false.

func (*AuthorizationInfo) HasAnyRole

func (a *AuthorizationInfo) HasAnyRole(roles ...string) bool

HasAnyRole method returns true if the Subject has any-one of the specified roles, otherwise false.

func (*AuthorizationInfo) HasRole

func (a *AuthorizationInfo) HasRole(role string) bool

HasRole method returns true if the Subject has the specified role, otherwise false.

func (*AuthorizationInfo) IsPermitted

func (a *AuthorizationInfo) IsPermitted(permission string) bool

IsPermitted method returns true if the Subject is permitted to perform an action or access a resource summarized by the specified permission string.

func (*AuthorizationInfo) IsPermittedAll

func (a *AuthorizationInfo) IsPermittedAll(permissions ...string) bool

IsPermittedAll method returns true if the Subject implies all of the specified permission strings, otherwise false.

func (*AuthorizationInfo) IsPermittedAllp

func (a *AuthorizationInfo) IsPermittedAllp(permissions ...*Permission) bool

IsPermittedAllp method returns true if the Subject implies all of the specified permission strings, false otherwise.

func (*AuthorizationInfo) IsPermittedp

func (a *AuthorizationInfo) IsPermittedp(permission *Permission) bool

IsPermittedp method returns true if the Subject is permitted to perform an action or access a resource summarized by the specified permission string.

func (*AuthorizationInfo) Permissions

func (a *AuthorizationInfo) Permissions() string

Permissions method returns permissions in the string format.

func (*AuthorizationInfo) Roles

func (a *AuthorizationInfo) Roles() string

Roles method returns roles in the string format.

func (AuthorizationInfo) String

func (a AuthorizationInfo) String() string

String method is stringer interface implementation.

type Authorizer

type Authorizer interface {
	// Init method gets called by aah during an application start.
	Init(appCfg *config.Config) error

	// GetAuthorizationInfo method called by auth scheme after authentication
	// successful to get Subject's (aka User) access control information
	// such as roles and permissions.
	GetAuthorizationInfo(authcInfo *authc.AuthenticationInfo) *AuthorizationInfo
}

Authorizer interface is used to provide authorization info (roles and permissions) after successful authentication.

type Permission

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

Permission represents the ability to perform an action or access a resource. A Permission is the most granular, or atomic, unit in a system's security policy and is the cornerstone upon which fine-grained security models are built.

aah framework provides a very powerful security implementation that is inspired by `Shiro` security framework.

It is important to understand a Permission instance only represents functionality or access - it does not grant it. Granting access to an application functionality or a particular resource is done by the application's security configuration, typically by assigning Permissions to users, roles and/or groups.

Most typical systems are what the `aah framework` calls role-based in nature, where a role represents common behavior for certain user types. For e.g:, a system might have an Aministrator role, a User or Guest roles, etc.

But if you have a dynamic security model, where roles can be created and deleted at runtime, you can't hard-code role names in your code. In this environment, roles themselves aren't very useful. What matters is what permissions are assigned to these roles.

Under this paradigm, permissions are immutable and reflect an application's raw functionality (opening files, accessing a web URL, creating users, etc). This is what allows a system's security policy to be dynamic: because Permissions represent raw functionality and only change when the application's source code changes, they are immutable at runtime - they represent 'what' the system can do. Roles, users, and groups are the 'who' of the application. Determining 'who' can do 'what' then becomes a simple exercise of associating Permissions to roles, users, and groups in some way.

Most applications do this by associating a named role with permissions (i.e. a role 'has a' collection of Permissions) and then associate users with roles (i.e. a user 'has a' collection of roles) so that by transitive association, the user 'has' the permissions in their roles. There are numerous variations on this theme (permissions assigned directly to users, or assigned to groups, and users added to groups and these groups in turn have roles, etc, etc). When employing a permission-based security model instead of a role-based one, users, roles, and groups can all be created, configured and/or deleted at runtime. This enables an extremely powerful security model.

A benefit to `aah framework` is that, although it assumes most systems are based on these types of static role or dynamic role w/ permission schemes, it does not require a system to model their security data this way - all Permission checks are relegated to `Authorizer` interface to implementations, and only those implementations really determine how a user 'has' a permission or not. The `Authorizer` could use the semantics described here, or it could utilize some other mechanism entirely - it is always up to the application developer.

func NewPermission

func NewPermission(permission string) (*Permission, error)

NewPermission method creats the permission instance for the given permission string in incase-sensitive. If any error returns nil and error info.

func NewPermissioncs

func NewPermissioncs(permission string, caseSensitive bool) (*Permission, error)

NewPermissioncs method creats the permission instance for the given permission string in Case-Sensitive. If any error returns nil and error info.

func (*Permission) Implies

func (p *Permission) Implies(permission *Permission) bool

Implies method returns true if this current instance implies all the functionality and/or resource access described by the specified Permission argument otherwise false.

That is, this current instance must be exactly equal to or a superset of the functionality and/or resource access described by the given Permission argument. Yet another way of saying this would be:

If "permission1 implies permission2", i.e. permission1.implies(permission2), then any Subject granted permission1 would have ability greater than or equal to that defined by permission2.

func (*Permission) Reset

func (p *Permission) Reset()

Reset method resets the instance values for repurpose.

func (Permission) String

func (p Permission) String() string

String method `Stringer` interface implementation.

type Reason

type Reason struct {
	Func     string
	Expected string
	Got      string
}

Reason struct used to represent authorization failed details.

func (Reason) Error

func (r Reason) Error() string

Error method is error interface

func (Reason) String

func (r Reason) String() string

String method is Stringer interface