-This file contains the list of required AAF permissions authorised for the request URI, permissions will be tested against the first matching URI.
-If the user doesn't have those permissions then the next matching URI will be tested until the list of URIs is exhausted.
-URIs will be matched in order as positioned in the configuration file. Wildcarding is supported as standard regular expression matches for both URIs and permissions.
+This file is used by the ReverseProxyAuthorization filter, the configurable authorization enforcement point, and contains the list
+of required AAF permissions needed for the request URI. The content of the file is in JSON format. Permissions will be tested against
+the first matching URI. If the user doesn't have those permissions then the next matching URI will be tested until the list of URIs
+is exhausted. URIs will be matched in order as positioned in the configuration file. All permissions listed in the configuration file
+for a request URI must have been granted to the user.
+
+The current implement of side car security retrieves user permissions from AAF. AAF permissions are composed of a type, instance and
+action and are returned from AAF as those values separated by the pipe (|) character e.g. org.onap.osaaf.resources.access|rest|read.
+Both instance and/or action can be wildcarded with an asterisk (*) e.g. org.onap.osaaf.resources.access|*|read,
+org.onap.osaaf.resources.access|rest|* or org.onap.osaaf.resources.access|*|*. If action or instance is wildcarded then a match
+between granted and needed permissions is found as long as the non wildcarded parts of the permission match too.
+
+Both URIs and permissions are matched using regular expressions which are defined in the uri-authorization.json file. Regular
+expression tests are applied to the whole permission unless AAF wildcarding has been used in which case the permissions are split
+into type, instance and action and the non wildcarded parts are tested individually. Note that owing to regular expression and JSON
+format that backslashes need to be escaped twice.