authz

README

Autz: A simple Authorization package based on the Google IAM Policy framework

Creating a simple Authorization package based on the Google IAM (Identity and Access Management) Policy framework involves defining and managing access controls for resources.

This package does not handle the identification / authn part of the IAM framework. It only deals with the Authorisation / Authz side of the framework. It authorises whether a particular Principal (user or service account) is able to perform a particular Permission (Get, Update, List, etc.) on a particular Resource. A resource is defined in the context of a Resource Driven development framework as defined at RDD inline with the API Improvement Proposals

Documentation

Overview

Package authz is a simple Authorization package based on the Google IAM (Identity and Access Management) Policy framework involves defining and managing access controls for resources.

This package does not handle the identification / authn part of the IAM framework. It only deals with the Authorisation / Authz side of the framework. It authorises whether a particular **Principal** (user or service account) is able to perform a particular **Permission** (Get, Update, List, etc.) on a particular **Resource**. A resource is defined in the context of a Resource Driven development framework as defined at [RDD](https://google.com) inline with the [API Improvement Proposals](https://aip.dev)

Index

• Constants
• type Authorizer
  • func (a *Authorizer) HasMethodAccess(policies []*iampb.Policy) bool
  • func (a *Authorizer) HasPermission(permission string, policies []*iampb.Policy) bool
  • func (s *Authorizer) NewPolicyFetcher(policySources []*PolicySource) *PolicyFetcher
  • func (a *Authorizer) PermissionDeniedError(resources ...string) error
• type HttpAuthorizer
  • func NewHttpAuthorizer(authHost string) *HttpAuthorizer
  • func (h *HttpAuthorizer) ForwardAuthorizationHeader(ctx context.Context) (context.Context, error)
  • func (h *HttpAuthorizer) HandleAuth(resp http.ResponseWriter, req *http.Request) bool
• type PolicyFetcher
  • func (f *PolicyFetcher) AddPolicy(resource string, policy *iampb.Policy) *PolicyFetcher
  • func (f *PolicyFetcher) GetPolicies() []*iampb.Policy
  • func (f *PolicyFetcher) RunAsync() *PolicyFetcher
  • func (f *PolicyFetcher) Skip(resources ...string) *PolicyFetcher
• type PolicySource
  • func NewClientPolicySource(resource string, ...) *PolicySource
  • func NewServerPolicySource(resource string, ...) *PolicySource
• type Requester
  • func (r *Requester) Email() string
  • func (r *Requester) HasRole(roleIds []string, policies []*iampb.Policy) bool
  • func (r *Requester) Id() string
  • func (r *Requester) IsGoogleIdentity() bool
  • func (r *Requester) IsMember(policyMember string) bool
  • func (r *Requester) IsServiceAccount() bool
  • func (r *Requester) IsSuperAdmin() bool
  • func (r *Requester) Jwt() string
  • func (r *Requester) LocalPolicySources(server openIam.UsersServiceServer, resourceTypes []string) []*PolicySource
  • func (r *Requester) Policy() *iampb.Policy
  • func (r *Requester) PolicyMember() string
  • func (r *Requester) PolicySources(usersClient openIam.UsersServiceClient, resourceTypes []string) []*PolicySource
  • func (r *Requester) UserName() string
• type Roles
  • func (r *Roles) Ids() []string
  • func (r *Roles) ResourceTypes() []string
• type ServerAuthorizer
  • func NewServerAuthorizer(roles []*openIam.Role, deploymentServiceAccountEmail string) *ServerAuthorizer
  • func (s *ServerAuthorizer) Authorizer(ctx context.Context) (*Authorizer, context.Context)
  • func (s *ServerAuthorizer) GetRolesThatGrantAccess(permission string) *Roles
  • func (s *ServerAuthorizer) PermissionDeniedError(permission string, resources ...string) error
  • func (s *ServerAuthorizer) WithMemberResolver(groupTypes []string, ...) *ServerAuthorizer

Constants

const (
	// One of the headers that cloudrun uses to send the JWT token of the authorized requester
	AuthHeader = "authorization"
	// One of the headers that cloudrun uses to send the JWT token of the authorized requester
	ServerlessAuthHeader = "x-serverless-authorization"
	// The header that this package uses to forward the JWT token of the authorized requester
	AuthzForwardingHeader = "x-alis-forwarded-authorization"
	// The header that Google Cloud ESPv2 proxy uses to forward the JWT token of the authorized requester
	ProxyForwardingHeader = "x-forwarded-authorization"
	// The header that Google Cloud IAP uses to forward the JWT token of the authorized requester
	IAPJWTAssertionHeader = "x-goog-iap-jwt-assertion"
)

Types

type Authorizer

type Authorizer struct {

	// The rpc method
	// Format: /package.service/method
	Method string
	// The Requester
	Requester *Requester
	// contains filtered or unexported fields
}

An authorizer lives for the duration of a grpc method call and is used to authorize the requester while providing access to the policy cache and the member cache to prevent redundant calls.

func (*Authorizer) HasMethodAccess

func (a *Authorizer) HasMethodAccess(policies []*iampb.Policy) bool

Checks if requester has access to the current method based on the provided policies.

func (*Authorizer) HasPermission

func (a *Authorizer) HasPermission(permission string, policies []*iampb.Policy) bool

Checks if the requester has the specified permission in the provided policies.

func (*Authorizer) NewPolicyFetcher

func (s *Authorizer) NewPolicyFetcher(policySources []*PolicySource) *PolicyFetcher

Creates a new PolicyFetcher for the given authorizer and policy sources.

func (*Authorizer) PermissionDeniedError

func (a *Authorizer) PermissionDeniedError(resources ...string) error

Returns a grpc error for this authorizer's method with the PermissionDenied code and an appropriate message.

type HttpAuthorizer

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

func NewHttpAuthorizer

func NewHttpAuthorizer(authHost string) *HttpAuthorizer

Creates a new HttpAuthorizer with the given authHost. Example authHost: "https://iam-auth-123456789.europe-west1.run.app".

func (*HttpAuthorizer) ForwardAuthorizationHeader

func (h *HttpAuthorizer) ForwardAuthorizationHeader(ctx context.Context) (context.Context, error)

Forwards the Authorization header in the incoming ctx to the outgoing ctx. Use this at the very top of your unary and streaming interceptors.

func (*HttpAuthorizer) HandleAuth

func (h *HttpAuthorizer) HandleAuth(resp http.ResponseWriter, req *http.Request) bool

Reverse proxies /auth/* requests to the authHost and validates the access_token cookie set by the authHost for all other requests. If the access token is valid, it also adds it as a header to the request.

Returns true if the request was handled, in which case you should return from the handler.

type PolicyFetcher

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

A PolicyFetcher is used to fetch/add policies that will be used for authorization.

func (*PolicyFetcher) AddPolicy

func (f *PolicyFetcher) AddPolicy(resource string, policy *iampb.Policy) *PolicyFetcher

Adds a policy that was fetched manually to the list of policies. Normally this was preceeded by a call to Skip(resource string) to avoid double fetching. The policy may be nil.

func (*PolicyFetcher) GetPolicies

func (f *PolicyFetcher) GetPolicies() []*iampb.Policy

Get the all the policies fetched or added so far. Will block if RunAsync has been called and not yet finished.

func (*PolicyFetcher) RunAsync

func (f *PolicyFetcher) RunAsync() *PolicyFetcher

Retrieves the policies (except the ones marked as skipped) asynchronously.

func (*PolicyFetcher) Skip

func (f *PolicyFetcher) Skip(resources ...string) *PolicyFetcher

Marks one/more resources to be skipped when fetching policies. This is useful if there is business logic that needs to read the resource with its policy from the database and thus avoids double fetching.

type PolicySource

type PolicySource struct {
	// The resource where the policy is stored
	Resource string
	// The policy getter function
	Getter func(ctx context.Context) (*iampb.Policy, error)
}

A source of an IAM policy, consisting of the resource name and a function to get the policy

func NewClientPolicySource

func NewClientPolicySource(resource string, clientMethod func(ctx context.Context, req *iampb.GetIamPolicyRequest, opts ...grpc.CallOption) (*iampb.Policy, error)) *PolicySource

Returns a new PolicySource for the given resource which is not implemented locally and thus requires a gRPC client to fetch the policy.

func NewServerPolicySource

func NewServerPolicySource(resource string, serverMethod func(ctx context.Context, req *iampb.GetIamPolicyRequest) (*iampb.Policy, error)) *PolicySource

Returns a new PolicySource for the given resource which is implemented locally and thus can be fetched directly from the locally implemented server.

type Requester

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

func (*Requester) Email

func (r *Requester) Email() string

func (*Requester) HasRole

func (r *Requester) HasRole(roleIds []string, policies []*iampb.Policy) bool

func (*Requester) Id

func (r *Requester) Id() string

func (*Requester) IsGoogleIdentity

func (r *Requester) IsGoogleIdentity() bool

Returns whether the requester used a google identity to authenticate.

func (*Requester) IsMember

func (r *Requester) IsMember(policyMember string) bool

Returns whether the requester is the same as the specified policy member or is a member of the specified policy member if its a group.

func (*Requester) IsServiceAccount

func (r *Requester) IsServiceAccount() bool

Returns whether the requester is a service account.

func (*Requester) IsSuperAdmin

func (r *Requester) IsSuperAdmin() bool

func (*Requester) Jwt

func (r *Requester) Jwt() string

func (*Requester) LocalPolicySources

func (r *Requester) LocalPolicySources(server openIam.UsersServiceServer, resourceTypes []string) []*PolicySource

Returns the local policy sources of the requester. Only used by the UsersService itself.

func (*Requester) Policy

func (r *Requester) Policy() *iampb.Policy

func (*Requester) PolicyMember

func (r *Requester) PolicyMember() string

Returns the policy member string of the requester. E.g. user:123456789 or serviceAccount:alis-build@...

func (*Requester) PolicySources

func (r *Requester) PolicySources(usersClient openIam.UsersServiceClient, resourceTypes []string) []*PolicySource

Returns the PolicySources of the requester if resourceTypes contain "alis.open.iam.v1.User" If usersClient is not nil, it will be used to fetch the policy from the Users service. If the user's provided JWT token contains a valid policy claim, it will be used instead of fetching the policy.

func (*Requester) UserName

func (r *Requester) UserName() string

Returns the user name of the requester. Format: users/{userId}

type Roles

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

An object that contains the role ids and the resource types where the roles could be stored in policies.

func (*Roles) Ids

func (r *Roles) Ids() []string

Returns the role ids that grant access to the given permission.

func (*Roles) ResourceTypes

func (r *Roles) ResourceTypes() []string

Returns the resource types where the roles could be stored in policies. E.g. alis.open.iam.v1.User and/or abc.de.library.v1.Book

type ServerAuthorizer

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

A server authorizer is setup once per grpc server and contains static information about the roles, permissions and functions to resolve group memberships.

func NewServerAuthorizer

func NewServerAuthorizer(roles []*openIam.Role, deploymentServiceAccountEmail string) *ServerAuthorizer

Create a new server authorizer from the given roles and deployment service account email.

func (*ServerAuthorizer) Authorizer

func (s *ServerAuthorizer) Authorizer(ctx context.Context) (*Authorizer, context.Context)

Creates a new authorizer which will live for the duration of the grpc method call.

func (*ServerAuthorizer) GetRolesThatGrantAccess

func (s *ServerAuthorizer) GetRolesThatGrantAccess(permission string) *Roles

Returns the roles that grant access to the given permission. The returned object contains the role ids and the resource types where the roles could be stored in policies.

func (*ServerAuthorizer) PermissionDeniedError

func (s *ServerAuthorizer) PermissionDeniedError(permission string, resources ...string) error

Returns a grpc error for the specified permission with the PermissionDenied code and an appropriate message.

func (*ServerAuthorizer) WithMemberResolver

func (s *ServerAuthorizer) WithMemberResolver(groupTypes []string, resolver func(ctx context.Context, groupType string, groupId string, principal *Authorizer) bool) *ServerAuthorizer

WithMemberResolver registers a function to resolve whether a requester is a member of a group. There can be multiple different types of groups, e.g. "team:engineering" (groupType = "team",groupId="engineering") A group always has a type, but does not always have an id, e.g. "team:engineering" (groupType = "team",groupId="engineering") vs "all" (groupType = "all",groupId=""). "user" and "serviceAccounts" are not allowed as group types. "domain" is a builtin group type that is resolved by checking if the requester's email ends with the group id. Results are cached per Authorizer.