documentation/core: better rego documentation

[calebdoxsey]

Currently we have some documentation on using rego directly: https://www.pomerium.com/docs/capabilities/authorization#rego-support

However we don't document what the inputs and outputs are for policy evaluation. Without this information its hard to write correct policy. We should expand the documentation to include this reference information.

[calebdoxsey]

I will take a first stab at this and then we can move it or reformat it.

[calebdoxsey]

Reference

Outputs

Authorization policy written in Rego is expected to return results in allow and/or deny rules:

# a policy that always allows access
allow := true

# a policy that always denies access
deny := true

Access is granted according to the same rules as PPL:

Only two actions are supported: allow and deny. deny takes precedence over allow. More precisely: a user will have access to a route if at least one allow rule matches and no deny rules match.

allow and deny rules support four forms:

1. A simple boolean:

   allow := true

2. An array with a single boolean value:

   deny := [true]

3. An array with two values: a boolean and a reason.

   allow := [false, "user-unauthorized"]

4. An array with three values, a boolean, a reason and additional data:

   allow := [false, "user-unauthorized", { "key": "value" }]

The reason is useful for debugging since it appears in authorize logs. There are also 2 special reasons used to trigger functionality in Pomerium:

1. user-unauthenticated indicates that the user needs to login and results in a redirect to the authenticate service
2. device-unauthenticated indicates that the user needs to register a new device

Inputs

Rego scripts are evaluated with inputs available on the input object:

allow if input.http.method == "POST"

The following inputs are defined:

• http: object
  • method: string, the method in the HTTP request
  • hostname: string, the hostname in the HTTP request
  • path: string, the path in the HTTP request
  • url: string, the full url in the HTTP request
  • headers: object, the headers in the HTTP request
  • client_certificate: object, client certificate info
    • presented: boolean, true if the client presented a certificate
    • leaf: string, the leaf certificate provided by the client (unvalidated)
    • intermediates: string, the remainder of the client certificate chain
  • ip: string, the user's ip address
• session: object
  • id: string, the session id
• is_valid_client_certificate: boolean

Functions

The following additional functions are available in rego scripts:

• get_databroker_record(record_type, record_id): returns data from the databroker. For example:

  session := get_databroker_record("type.googleapis.com/session.Session", input.session.id)

[calebdoxsey]

@ZPain8464 hopefully that's enough to work with. Let me know if anything needs clarification. Thanks!

[ZPain8464]

@calebdoxsey I appreciate the effort here. I'll take a look at this soon and let you know if I need any more details. Thanks :)