-Authorization is implemented via the aaa-authz modules, comprising of a yang based AuthZ policy schema, an MD-SAL AuthZ capable broker, an AuthZ
-service engine invoked by the broker and executing policies.
-
-NOTE: The Lithium release features a trail of Authz functionality, in particular longest string matching is not implemented.
-
-Initially the AuthZ functionality is only able to handle RestConf requests, and to do so the Restconf connector configuration must
- be explicitly modified as follows:
-
- 0. Compile or obtain the ODL distribution
- 1. Start karaf and install the odl-aaa-authz feature
-
- Note: At this stage, with a default configuration, there is no MD-SAL data to test against. To test you can install the toaster service using feature:install odl-toaster
-
-Default authorization policies are loaded from the configuration subsystem (TODO: Provide a default set)
-They are accessible and editable via the restconf interface at:
-
- http://<odl address>/restconf/configuration/authorization-schema:simple-authorization/
-
-The schema for policies is a list consisting of the following items:
-
- * Service : The application service that is the initiator of the request triggering an authorization check, eg Restconf.
- NOTE: The service field is currently not enforced, and a wildcard "*" is recommended.
- * Action: The action that is being authorized. Maps to one of: { create; read; update; delete; execute; subscribe; any }
- * Resource: The URI or Yang instance id of the resource, including wildcards (see examples below)
- * Role: The AuthN derived user role
-
-Some examples of resources are:
-
- Data : /operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:1
-
- Wildcarded data: /configuration/opendaylight-inventory:nodes/node/*/node-connector/*
-
- RPC: /operations/example-ops:reboot
-
- Wildcarded RPC: /operations/example-ops:*
-
- Notification: /notifications/example-ops:startup
-
-
-*More on MD-SAL authorization later...*
-
-### Accounting
-
-*More on Accounting later...*
+ODL supports two authorization engines at present, both of which are roughly similar in behavior. Namely, the two
+authorization engines are the MDSALDynamicAuthorizationFilter(1) and the RolesAuthorizationFilter(2). For several
+reasons explained further in this documentation, we STRONGLY encourage you to use the MDSALDyanmicAuthorizationFilter(1)
+approach over the RolesAuthorizationFilter(2).
+
+1) MDSALDyanmicAuthorizationFilter
+
+The MDSALDynamicAuthorizationFilter is a mechanism used to restrict access to partcular URL endpoint patterns. Users
+may define a list of policies that are insertion-ordered. Order matters for the list of policies, since the first
+matching policy is applied. This choice was made to emulate behavior of the Apache Shiro RolesAuthorizationFilter.
+
+A policy is a key/value pair, where the key is a resource (i.e., a "url pattern") and the value is a list of permissions
+for the resource. The following describes the various elements of a policy:
+
+resource: The resource is a string url pattern as outlined by Apache Shiro. For more information,
+ see http://shiro.apache.org/web.html.
+description: An optional description of the URL endpoint and why it is being secured.
+permissions list: A list of permissions for a particular policy. If more than one permission exists in the permissions
+ list, the permissions are evaluted using logical "OR".
+
+A permission describes the prerequisites to perform HTTP operations on a particular endpoint. The following describes
+the various elements of a permission:
+
+role: The role required to access the target URL endpoint.
+actions list: A leaf-list of HTTP permissions that are allowed for a Subject possessing the required role.
+
+---------
+Example:
+
+To limit access to the modules endpoint, issue the following:
+
+HTTP Operation: put
+URL: /restconf/config/aaa:http-authorization/policies
+Headers:
+ Content-Tye: application/json
+ Accept: application/json
+
+Body:
+```json
+{
+ "aaa:policies": {
+ "aaa:policies": [
+ {
+ "aaa:resource": "/restconf/modules/**",
+ "aaa:permissions": [
+ {
+ "aaa:role": "admin",
+ "aaa:actions": [
+ "get","post","put","patch","delete"
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+--------
+The above example locks down access to the modules endpoint (and any URLS available past modules) to the "admin" role.
+Thus, an attempt from the OOB admin user will succeed with 2XX HTTP status code, while an attempt from the OOB "user"
+user will fail with HTTP status code 401, as the "user" user is not granted the "admin" role.
+
+NOTE: "aaa:resource" value starts with "/restconf". Unlike the RolesAuthorizationFilter whichis relative to the
+ServletContext, The MDSALDyanmicAuthorizationFilter is relative to the Servlet Root (i.e., "/"). This is superior, as it
+is more specific and does not allow for ambiguity.
+
+2) aaa-app-config clustered application configuration "urls" section Authorization roles filter (i.e.,
+"RolesAuthorizationFilter"). [DEPRECATED]
+
+Authorization is implemented via the aaa-shiro modules. RolesAuthorizationFilter (roles filter) is limited purely to
+RESTCONF (HTTP) and does not focus on MD-SAL.
+
+More information on how to configure authorization can be found on the Apache Shiro website: http://shiro.apache.org/web.html
+
+NOTE: Use of aaa-app-config.xml urls section to define roles requirements is discouraged! This is due to the fact that
+aaa-app-config.xml changes are only recognized on servlet container startup. Changes to aaa-app-config.xml are only
+honored upon restart.
+
+NOTE: Use of aaa-app-config.xml urls section to define roles requirements is discouraged! This is due to the fact that
+url patterns are matched relative to the servlet context. This leaves room for ambiguity, since many endpoints may
+match (i.e., "/restconf/modules" and "/auth/modules" would both match a "/modules/**" rule).
+
+### Accounting
+
+Accounting is handled through the standard slf4j logging mechanisms used by the rest of OpenDaylight. Thus, one can
+control logging verbosity through manipulating the log levels for individual packages and classes directly through the
+karaf shell, JMX, or etc/org.ops4j.pax.logging.cfg. In normal operations, the default levels exposed do not provide
+much information about AAA services; this is due to the fact that logging can severely degrade performance.
+
+Two noteworthy logging activities are:
+1) Enable debugging logging
+2) Enable successful/unsuccessful authentication attempts logging
+
+#### Enable Debugging Logging
+
+For debugging purposes (i.e., to enable maximum verbosity), issue the following command:
+
+ karaf> log:set TRACE org.opendaylight.aaa
+
+#### Enable Successful/Unsuccessful Authentication Attempts Logging
+By default, successful/unsuccessful authentication attempts are NOT logged. This is due to the fact that logging can
+severely decrease REST performance. To enable logging of successful/unsuccessful REST attempts, issue the following
+command:
+
+ karaf> log:set DEBUG org.opendaylight.aaa.shiro.filters.AuthenticationListener
+
+It is possible to add custom AuthenticationListener(s) to the Shiro based configuration, allowing different ways to
+listen for successful/unsuccessful authentication attempts. Custom AuthenticationListener(s) must implement the
+org.apache.shiro.authc.AuthenticationListener interface.