Set access control policy



	This API is used to set access control policies.

Called by:

	A "data provider" with a valid class-3 or above certificate.


	The "previous" policies will be "overwritten"!

	The "acl/revert" API can be used to revert to "previous" policy.

	Please use the "acl/append" API instead to "acl/set" if you wish to
	add a policy to the existing set of policies.




	content-type : "application/json"

Body in JSON format:

		"policy" : "acl policy (a string) in aperture policy language"	// required

HTTP response code:

		If the policy has been successfully set.

		If the policy contains syntax errors.

Aperture policy language:

	The authorization rules are in "aperture" policy language, and is in the format:

			CAN access <resource id(s)>
			FOR <n> <second(s)/minute(s)/week(s)/month(s)/year(s)>
			IF <condition> AND/OR <more-conditions>

	Examples: can access for 2 hours

		*, * can access * if time > 18:00:00 AND time < 24:00:00

		all can access* if api = "/latest" AND country = "IN"

	Aperture vs RegEx:
		"*" in Aperture is equivalent to ".*" in RegEx

	Aperture also supports conditions such as:

		ip =

		latitude > 20.03 AND longitude > 40.22

		time::day in (Monday, Tuesday, Wednesday, Thursday, Friday)


	You may use a single "*", or "all", "everything", or "anything" to match any identifier.

	For example: can access *

	    all can access anything

	Multiple rules could be combined together using semicolons:

		rule-1; rule-2; .... ; rule-n

		In case of multiple rules, the first rule which matches will apply.

		Though, Aperture policy language supports RegEx, the "acl/set" or "acl/append" APIs
		"DO NOT" accept RegEx in policies.

Variables in policy language:

	Below are the variables available in rules, and its type.

	| Variable	    | Type   | Description							   |
	| api		    | string | The api the consumer is requesting to access on a resource id.      |
	| method	    | string | The method the consumer is requesting to access on the APIs.        |
	| body.*	    | string | The list of variables to be passed in the body of an API.	   |
	| time		    | time   | The time at which the data request was made.		   	   |
	| ip		    | ip     | The originating IP address of the token request.                    |
	|												   |
	| tokens_per_day    | number | The number of tokens issued today to the consumer For a resource.   |
	|												   |
	| country	    | string | consumer's country code from where the request has originated.      |
	| region	    | string | consumer's region from where the request has originated.	   	   |
	| timezone	    | string | consumer's timezone from where the request has originated.	   |
	| city		    | string | consumer's city from where the request has originated.	   	   |
	| latitude	    | number | consumer's latitude from where the request has originated.	   |
	| longitude	    | number | consumer's longitude from where the request has originated.   	   |
	|												   |
	| cert.class	    | string | consumer's certificate attributes				   |
	|	    | string | 									   |
	| cert.o	    | string | 									   |
	| cert.ou	    | string | 									   |
	| cert.c	    | string | 									   |
	|	    | string | 									   |
	|	    | string | 									   |
	|	    | string | 									   |
	| cert.title	    | string | 									   |
	|												   |
	|    | string | consumer's certificate issuer details				   |
	| cert.issuer.o	    | string | 									   |
	| | string | 									   |
	| cert.issuer.ou    | string |									   |
	| cert.issuer.c     | string | 									   |
	|    | string | 									   |

Resource IDs in policies:

	The "id" is the identifier of the resource (a data-set) the provider is interested in sharing with consumers.

	Data consumers typically get these "id"s from a catalogue server.

	An example catalog server is:

	And an example query to get ids is:

	The resource "id" consists of at least 4 parts seperated by a "/" indicating:

		1. The email domain of the data provider.

		2. SHA-1 hash of the data provider's email-id (to mask the provider's email).

		3. The hostname (FQDN) of the resource server where the resource is hosted.

		4. The name of the resource (which may contain additional "/"s).

	For example:

	However while writing rules the first 2 fields should be skipped
	for example, in the above id


	should be skipped.

	The rule would look like this:
		" can access"

Using pyIUDX SDK:

	from pyIUDX.auth import auth

	iudx_auth = auth.Auth("certificate.pem","private-key.pem")

	iudx_auth.set_policy("* can access")

CURL example:


		curl -XPOST

			--cert certificate.pem --key private-key.pem

			-H 'content-type: application/json'

			-d '{"policy":"* can access"}'


		200 OK
		content-type : "application/json"

			"success" : true

Known limitations:

	If the access control rules contain regex on "id"s, then an authorized
	consumer can get a token for "id"s which may not exist.

	This is by design. Having regex makes writing rules easier.
	Also, the provider doesn't have to remember all valid "id"s.

	This issue is expected to be handled by the resource server,
	by rejecting any queries to invalid "id"s.

	To be able to exploit this, the authorized consumer must guess the regex.

	As a safeguard:

	Auth server limits how many tokens can be generated per second; as well
	as Auth server's firewall blocks a IP address for some time if number of
	packets or connections cross a threshold.

See also:

	acl API:

	acl append API:

	acl revert API:

	node aperture at github: