External Policy Interface

Scrambls policy can be configured to reference an external server. This allows the owner of a group to divert policy decisions to his or her own server. When a user tries to view a post configured with such a policy, scrambls makes a real-time request to the server has group owner has specified. The request can be contain attribute tokens that scrambls will populate from the current context. The external server is responsible for responding with a boolean that determines whether the policy term is satisfied or not.

Creating a Group Policy with an External Server Term

  • From the scrambls logged-in home page select Define Groups
  • Click Define New Group
  • Click Add New Rule
  • In the rule dialog select the rule type Validate with External Service
  • In the entry field that appear type in the fully qualified URL to be called along with any parameters
  • Save the rule, give the group a name and save it.

Post Protocol

Scrambls issues an HTTP "GET" request with the given URL. The external server should be configured to conduct the conversation over SSL, but this is not required. The response header should identify the content as: application/json.

The response is a JSON structure containing the following attributes:

name type description
item string
inlist boolean set to true if the test is satisfied indicating to scrambls that this policy term has passed
cache integer determines the length in time, in seconds, that this response may be cached by scrambls. If set to 0, scrambls will not cache the response and will reach out to the external server on every request

Scrambls Attribute Tokens

Scrambls attribute tokens allow you to configure the URL of your policy test with information from the current context. Currently only one attribute is supported, email address. Other attributes and identifiers will become available over time.

Token Description
$(email) any instance of '$(email)' in the server URL will be replaced with the email address of the user requesting access

Examples

The following url configured as an external service will post a request to inlist on policy.myserver.com along with the paramter email

http://policy.myserver.com/TestPolicy/inlist?email=$(email)

If the current user is, say john@acme.com, then the call received by the external server from scrambls would be

http://policy.myserver.com/TestPolicy/inlist?email=john@acme.com

The server configures it's response in JSON, and assuming john@acme.com is to be granted access, returns:

{"item":"john@acme.com","inlist":true,"cache":0}

Sample Code

PolicyInterfacePerl - an implementation in Perl for use with TWiki