Documentation

Index

Constants

This section is empty.

Variables

View Source
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")
)
View Source
var (
	// ErrAuthorizerIsNil error is return when authorizer is nil in the auth scheme.
	ErrAuthorizerIsNil = errors.New("security/authz: authorizer is nil")
)

Functions

This section is empty.

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