api.md

Protocol Documentation

Table of Contents

• aserto/authorizer/v2/api/identity_context.proto

  • IdentityContext

  • IdentityType

• aserto/authorizer/v2/api/policy_context.proto

  • PolicyContext

• aserto/authorizer/v2/api/decision_logs.proto

  • Decision
  • Decision.AnnotationsEntry
  • Decision.OutcomesEntry
  • DecisionPolicy
  • DecisionUser

• aserto/authorizer/v2/api/module.proto

  • Module

• aserto/authorizer/v2/authorizer.proto

  • CompileRequest

  • CompileResponse

  • Decision

  • DecisionTreeOptions

  • DecisionTreeRequest

  • DecisionTreeResponse

  • GetPolicyRequest

  • GetPolicyResponse

  • InfoRequest

  • InfoResponse

  • IsRequest

  • IsResponse

  • ListPoliciesRequest

  • ListPoliciesResponse

  • QueryOptions

  • QueryRequest

  • QueryResponse

  • PathSeparator

  • TraceLevel

  • Authorizer

• Scalar Value Types

Top

aserto/authorizer/v2/api/identity_context.proto

IdentityContext

Field	Type	Label	Description
identity	string
type	IdentityType

IdentityType

Identity types, describes the payload type of the identity field inside the IdentityContext message.

Name	Number	Description
IDENTITY_TYPE_UNKNOWN	0	Unknown, value not set, requests will fail with identity type not set error.
IDENTITY_TYPE_NONE	1	None, no explicit identity context set, equals anonymous.
IDENTITY_TYPE_SUB	2	Sub(ject), identity field contains an oAUTH subject.
IDENTITY_TYPE_JWT	3	JWT, identity field contains a JWT access token.
IDENTITY_TYPE_MANUAL	4	Manual, propagates thw identity field as-is, without validation, into the input object.

Top

aserto/authorizer/v2/api/policy_context.proto

PolicyContext

Field	Type	Label	Description
path	string		policy path aka package name
decisions	string	repeated	list (1..N) of policy decisions (aka rules)

Top

aserto/authorizer/v2/api/decision_logs.proto

Decision

represents a decision that an authorizer performed in the past

Field	Type	Label	Description
id	string		unique id, replay a decision starting with this, also useful to de-dup
timestamp	google.protobuf.Timestamp		UTC time when the decision was made
path	string		Policy path used in decision
user	DecisionUser		info about user for whom the decision as made
policy	DecisionPolicy		info about policy used for the decision
outcomes	Decision.OutcomesEntry	repeated	outcome of the decisions specified in the policy context
resource	google.protobuf.Struct		the resource context used in a decision
annotations	Decision.AnnotationsEntry	repeated	annotations that may be added to a decision

Decision.AnnotationsEntry

Field	Type	Label	Description
key	string
value	string

Decision.OutcomesEntry

Field	Type	Label	Description
key	string
value	bool

DecisionPolicy

information about a policy used in a decision

Field	Type	Label	Description
context	PolicyContext		policy context used in the decision
registry_service	string		registry service where policy was retrieved from (e.g. opcr.io)
registry_image	string		image of the policy in the registry, including org (e.g. acmecorp/peoplefinder-abac)
registry_tag	string		tag of the policy image (e.g. 0.8.2 or latest)
registry_digest	string		digest of the policy image

DecisionUser

information about a user on behalf of whom a decision was made

Field	Type	Label	Description
context	IdentityContext		identity context used in the decision
id	string		id of the user the identity resolved to
email	string		convenience human-readable identifier

Top

aserto/authorizer/v2/api/module.proto

Module

Field	Type	Label	Description
id	string	optional
raw	string	optional
package_path	string	optional
ast	google.protobuf.Value	optional
package_root	string	optional

Top

aserto/authorizer/v2/authorizer.proto

CompileRequest

Field	Type	Label	Description
query	string
input	string
unknowns	string	repeated
disable_inlining	string	repeated
options	QueryOptions	optional
policy_context	api.PolicyContext	optional
identity_context	api.IdentityContext	optional
resource_context	google.protobuf.Struct	optional

CompileResponse

Field	Type	Label	Description
result	google.protobuf.Struct
metrics	google.protobuf.Struct
trace	google.protobuf.Struct	repeated
trace_summary	string	repeated

Decision

Field	Type	Label	Description
decision	string
is	bool

DecisionTreeOptions

Field	Type	Label	Description
path_separator	PathSeparator

DecisionTreeRequest

Field	Type	Label	Description
policy_context	api.PolicyContext
identity_context	api.IdentityContext
options	DecisionTreeOptions
resource_context	google.protobuf.Struct

DecisionTreeResponse

Field	Type	Label	Description
path_root	string
path	google.protobuf.Struct

GetPolicyRequest

Field	Type	Label	Description
id	string
field_mask	google.protobuf.FieldMask

GetPolicyResponse

Field	Type	Label	Description
result	api.Module

InfoRequest

InfoResponse

Field	Type	Label	Description
version	string
commit	string
date	string
os	string
arch	string

IsRequest

Field	Type	Label	Description
policy_context	api.PolicyContext
identity_context	api.IdentityContext
resource_context	google.protobuf.Struct

IsResponse

Field	Type	Label	Description
decisions	Decision	repeated

ListPoliciesRequest

Field	Type	Label	Description
field_mask	google.protobuf.FieldMask

ListPoliciesResponse

Field	Type	Label	Description
result	api.Module	repeated

QueryOptions

Field	Type	Label	Description
metrics	bool		default false
instrument	bool		default false
trace	TraceLevel		default ExplainOffV1
trace_summary	bool		default false

QueryRequest

Field	Type	Label	Description
query	string
input	string
options	QueryOptions	optional
policy_context	api.PolicyContext	optional
identity_context	api.IdentityContext	optional
resource_context	google.protobuf.Struct	optional

QueryResponse

Field	Type	Label	Description
response	google.protobuf.Struct
metrics	google.protobuf.Struct
trace	google.protobuf.Struct	repeated
trace_summary	string	repeated

PathSeparator

Name	Number	Description
PATH_SEPARATOR_UNKNOWN	0	Value not set.
PATH_SEPARATOR_DOT	1	Dot "." path separator
PATH_SEPARATOR_SLASH	2	Slash "/" path separtor

TraceLevel

Name	Number	Description
TRACE_LEVEL_UNKNOWN	0	Value not set.
TRACE_LEVEL_OFF	1	ExplainOffV1 ExplainModeV1 = "off"
TRACE_LEVEL_FULL	2	ExplainFullV1 ExplainModeV1 = "full"
TRACE_LEVEL_NOTES	3	ExplainNotesV1 ExplainModeV1 = "notes"
TRACE_LEVEL_FAILS	4	ExplainFailsV1 ExplainModeV1 = "fails"

Authorizer

Method Name	Request Type	Response Type	Description
DecisionTree	DecisionTreeRequest	DecisionTreeResponse
Is	IsRequest	IsResponse
Query	QueryRequest	QueryResponse
Compile	CompileRequest	CompileResponse
ListPolicies	ListPoliciesRequest	ListPoliciesResponse
GetPolicy	GetPolicyRequest	GetPolicyResponse
Info	InfoRequest	InfoResponse

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)