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 AuthInfo
• type Authz
  • func New(roles []*Role) *Authz
  • func (a *Authz) AddRequesterJwtToOutgoingCtx(ctx context.Context) (context.Context, error)
  • func (a *Authz) Authorize(ctx context.Context, permission string, policies []*iampb.Policy, ...) (*AuthInfo, error)
  • func (a *Authz) AuthorizeFromResources(ctx context.Context, permission string, resources []string, cache interface{}) (*AuthInfo, error)
  • func (a *Authz) GetPermissions(ctx context.Context, policies []*iampb.Policy, permissions []string, ...) ([]string, error)
  • func (a *Authz) GetPermissionsFromResources(ctx context.Context, resources []string, permissions []string, ...) ([]string, error)
  • func (a *Authz) GetRequesterAuthInfo(ctx context.Context) (*AuthInfo, error)
  • func (a *Authz) GetRoles(ctx context.Context, policies []*iampb.Policy, cache interface{}) ([]string, error)
  • func (a *Authz) GetRolesFromResources(ctx context.Context, resources []string, cache interface{}) ([]string, error)
  • func (a *Authz) IsMember(ctx context.Context, authInfo *AuthInfo, member string, ...) (bool, error)
  • func (a *Authz) SetPolicy(ctx context.Context, resource string, policy *iampb.Policy, cache interface{}) (*iampb.Policy, error)
  • func (a *Authz) SkipAuthIfAuthJwtMissing() *Authz
  • func (a *Authz) WithMemberResolver(groupType string, ...) *Authz
  • func (a *Authz) WithPolicyReader(...) *Authz
  • func (a *Authz) WithSuperAdmins(superAdmins []string) *Authz
• type Role

Constants

const (
	AuthForwardingHeader  = "x-forwarded-authorization" // The header used by ESPv2 gateways and other neurons to forward the JWT token
	IAPJWTAssertionHeader = "x-goog-iap-jwt-assertion"  // The header used by IAP to forward the JWT token
	AuthorizationHeader   = "Authorization"             // The header used by clients to send the JWT token directly to cloudrun (without ESPv2 or IAP)
	AuthorizationHeader2  = "authorization"             // The header used by clients to send the JWT token directly to cloudrun (without ESPv2 or IAP)
	ServerlessAuthHeader1 = "X-Serverless-Authorization"
	ServerlessAuthHeader2 = "x-serverless-authorization"
)

Types

type AuthInfo

type AuthInfo struct {
	// The jwt token
	Jwt string
	// The principal id e.g. 123456789
	Id string
	// The principal email e.g. john@gmail.com
	Email string
	// Whether the principal is a super admin
	IsSuperAdmin bool
	// Principal is a service account; if false, principal is a user
	IsServiceAccount bool
	// Policy member in the format "user:123456789" or "serviceAccount:123456789"
	PolicyMember string

	// The principal roles
	Roles []string
}

type Authz

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

Authz is a struct that contains the dependencies required to validate access at the method level

func New

func New(roles []*Role) *Authz

New returns a new Authz object used to authorize a permission on a resource.

func (*Authz) AddRequesterJwtToOutgoingCtx

func (a *Authz) AddRequesterJwtToOutgoingCtx(ctx context.Context) (context.Context, error)

This method is used to add the JWT token to the outgoing context in the x-forwarded-authorization header. This might be useful if one service needs wants to make a grpc hit in the same product deployment as the requester, in stead of as itself.

func (*Authz) Authorize

func (a *Authz) Authorize(ctx context.Context, permission string, policies []*iampb.Policy, cache interface{}) (*AuthInfo, error)

Authorize first extracts the principal from the incoming context, also accomodating for IAP and ESPv2 forwarded JWT tokens. It then determines which roles will grant the required permission, based on the roles provided in the New method. Lastly it checks whether the principal is part of any of the roles that grant the required permission.

func (*Authz) AuthorizeFromResources

func (a *Authz) AuthorizeFromResources(ctx context.Context, permission string, resources []string, cache interface{}) (*AuthInfo, error)

AuthorizeFromResources does the exact same thing as Authorize, except that it also retrieves the policies for the resources using the policyReader function provided in WithPolicyReader. This is useful when you have a list of resources and you want to authorize a principal against all of them, without having to retrieve the policies manually.

func (*Authz) GetPermissions

func (a *Authz) GetPermissions(ctx context.Context, policies []*iampb.Policy, permissions []string, cache interface{}) ([]string, error)

GetPermissions extracts the principal from the incoming context, also accomodating for IAP and ESPv2 forwarded JWT tokens. It then determines which permissions the principal has, based on the roles provided in the New method. Use this for implementing TestIamPermissions in your grpc service. Note if the list of permissions is empty, all permissions will be returned.

func (*Authz) GetPermissionsFromResources

func (a *Authz) GetPermissionsFromResources(ctx context.Context, resources []string, permissions []string, cache interface{}) ([]string, error)

GetPermissionsFromResources does the exact same thing as GetPermissions, except that it also retrieves the policies for the resources Note if the list of permissions is empty, all permissions will be returned.

func (*Authz) GetRequesterAuthInfo

func (a *Authz) GetRequesterAuthInfo(ctx context.Context) (*AuthInfo, error)

func (*Authz) GetRoles

func (a *Authz) GetRoles(ctx context.Context, policies []*iampb.Policy, cache interface{}) ([]string, error)

func (*Authz) GetRolesFromResources

func (a *Authz) GetRolesFromResources(ctx context.Context, resources []string, cache interface{}) ([]string, error)

func (*Authz) IsMember

func (a *Authz) IsMember(ctx context.Context, authInfo *AuthInfo, member string, memberCache map[string]bool, cache interface{}) (bool, error)

func (*Authz) SetPolicy

func (a *Authz) SetPolicy(ctx context.Context, resource string, policy *iampb.Policy, cache interface{}) (*iampb.Policy, error)

SetPolicy first retrieves the current policy and if it exists it ensures the new policy's etag is the same as the current. It also generates a new etag.

func (*Authz) SkipAuthIfAuthJwtMissing

func (a *Authz) SkipAuthIfAuthJwtMissing() *Authz

Use SkipAuthIfAuthJwtMissing only if your service is behind some sort of auth proxy (e.g. a non-public cloudrun service, or a service behind ESPv2 or IAP). This is useful if your methods need to call each other with empty contexts, and you want to bypass authorization in those cases. If this is used, any method that calls Authorize or AuthorizeWithResources will need to check for nil authInfo (even if err==nil) and handle it accordingly.

func (*Authz) WithMemberResolver

func (a *Authz) WithMemberResolver(groupType string, resolver func(ctx context.Context, groupType string, groupId string, authInfo *AuthInfo, cache interface{}) (bool, error)) *Authz

WithMemberResolver registers a function to resolve whether a principal is a member of a principal group. There can be multiple different types of principal groups, e.g. "team:engineering" (groupType = "team",groupId="engineering") or "domain:example.com" (groupType = "domain",groupId="example.com"). A group always has a type, but does not always have an id, e.g. "allAuthenticatedUsers" or "allAlisBuilders". Group type of "user" and "serviceAccount" are reserved and should not be used. Results are cached per Authorize/GetRoles call, so if you need to resolve the same group multiple times, it will only be resolved once. The cache argument is passed to your policy reader function from the cache argument your program passes to the Authorize,AuthorizeFromResources,GetRoles,GetRolesFromResources,GetPermissions and GetPermissionsFromResources methods.

func (*Authz) WithPolicyReader

func (a *Authz) WithPolicyReader(policyReader func(ctx context.Context, resource string, cache interface{}) (*iampb.Policy, error)) *Authz

WithPolicyReader registers the function to read the IAM policy for a resource. This is required if you are planning on using the AuthorizeFromResources,GetRolesFromResources or GetPermissionsFromResources methods. The cache argument is passed to your policy reader function from the cache argument your program passes to the AuthorizeFromResources,GetRolesFromResources and GetPermissionsFromResources methods.

func (*Authz) WithSuperAdmins

func (a *Authz) WithSuperAdmins(superAdmins []string) *Authz

WithSuperAdmins registers the set of super administrators. Super admins do not need to be members of any role to have access. Super admins can forward authorization of other users in the x-forwarded-authorization header. Super admins might have special permissions in your business logic (can call List methods without providing a parent) Each needs to be prefixed by 'user:' or 'serviceAccount:' for example: ["user:10.....297", "serviceAccount:10246.....354"] It is recommended to only use the service accounts of your product deployment as super admins, and not individual users.

type Role

type Role struct {
	// The role name
	Name string
	// Permissions that this role has
	Permissions []string
	// Which other roles this role extends
	Extends []string
}