Skip to content

Latest commit

 

History

History
90 lines (54 loc) · 4.48 KB

policy-providers.md

File metadata and controls

90 lines (54 loc) · 4.48 KB
Raw

Policy Providers

Policies get loaded into matrix-corporal by various providers.

A policy would normally be generated by some external service (say your intranet system). In general, there are 2 ways that a policy can reach matrix-corporal:

  • pull -- matrix-corporal will fetch the policy by itself.

  • push -- your external service will send the policy to matrix-corporal's HTTP API.

Regardless of which policy provider you use, a policy always looks the same and contains the same fields, according to the policy documentation.

Pull-style policy providers

The simplest way to use matrix-corporal is with a pull-style policy provider.

It involves pointing matrix-corporal to a static file or HTTP URL, and have it load the policy from there.

Static file pull-style policy provider

To load a policy from a static file, use the following matrix-corporal configuration:

"PolicyProvider": {
	"Type": "static_file",
	"Path": "path/to/policy.json"
}

matrix-corporal will load this file and also monitor it for changes. Should the file get changed, matrix-corporal will automatically reload the policy and immediately apply it.

HTTP pull-style policy provider

To load a policy from an external URL, use the following matrix-corporal configuration:

"PolicyProvider": {
	"Type": "http",
	"Uri": "https://intranet.example.com/matrix/policy",
	"AuthorizationBearerToken": "SOME_SECRET",
	"CachePath": "var/last-policy.json",
	"ReloadIntervalSeconds": 1800,
	"TimeoutMilliseconds": 30000
}

Note: using this requires that the URL be reachable from matrix-corporal. If you cannot do that, you may want to look into using a push-style policy provider.

Configuration options:

  • Uri - the URL from which matrix-corporal will fetch the policy (a GET request is made).

  • AuthorizationBearerToken - the shared secret that matrix-corporal will send the request with (the GET request will be sent with a header of Authorization: Bearer SOME_SECRET)

  • CachePath - a path to a local file, where matrix-corporal will store the last-fetched policy. It's important to store it locally to prevent downtime in case the policy provider is temporarily unavailable for some reason. Can be set to null to disable caching (not recommended).

  • ReloadIntervalSeconds - an interval duration at which the policy provider will re-fetch the policy from the given URL. Can be set to 0 or null to disable reloading.

  • TimeoutMilliseconds - how long (in milliseconds) HTTP requests (from matrix-corporal to the policy-serving Uri) are allowed to take before being timed out. Can be set to null to allow for unlimited waits (not recommended).

Besides this interval-driven reloading, your external service can hit up matrix-corporal and tell it to reload the policy right now (outside of the regular schedule). To do this, enable Matrix Corporal's HTTP API and send a request to matrix-corporal's Policy-provider reload endpoint.

Push-style policy providers

If you want to keep your policy-generation service private, you can have it push new policies directly to matrix-corporal. This way, data is sent directly to matrix-corporal and it doesn't need to be able to reach your external service.

To do this, you need to enable Matrix Corporal's HTTP API and send policies to its Policy submission endpoint.

To make matrix-corporal store the last-seen policy locally and reload it when the server restarts, use the following matrix-corporal configuration:

"PolicyProvider": {
	"Type": "last_seen_store_policy",
	"CachePath": "var/last-seen-policy.json"
}

Push-style policy providers are helpeful for when your other server (the one providing the policy) is not reachable from matrix-corporal's side.

If your policy-generating server is reachable, it may be better to use a pull-style policy provider in combination with matrix-corporal's Policy-provider reload endpoint (to trigger reloading outside of the regular schedule).