-## Welcome to the Opendaylight AAA Project!
+## Opendaylight AAA
-This project is aimed at providing a flexible, pluggable framework with out-of-the-box capabilities for:
-
-* *Authentication*: Means to authenticate the identity of both human and machine users (direct or federated).
-* *Authorization*: Means to authorize human or machine user access to resources including RPCs, notification subscriptions, and subsets of the datatree.
-* *Accounting*: Means to record and access the records of human or machine user access to resources including RPCs, notifications, and subsets of the datatree
+This project is aimed at providing a flexible, pluggable framework with out-of-the-box capabilities for Authentication, Authorization and Accounting.
## Caveats
The following caveats are applicable to the current AAA implementation:
*Prerequisite:* The followings are required for building AAA:
-- Maven 3
-- Java 7
+- Maven 3.3.9+
+- JDK8
Get the code:
### Installing
-AAA installs into an existing Opendaylight controller Karaf installation. If you don't have an Opendaylight installation, please refer to this [page](https://wiki.opendaylight.org/view/OpenDaylight_Controller:Installation).
-
-Start the controller Karaf container:
-
- bin/karaf
-
-Install AAA repository from the Karaf shell:
+AAA is automatically installed upon installation of odl-restconf. If you are using AAA from a non-RESTCONF context, you can install the necessary javax.servlet.Filter(s) through the following command:
- repo-add mvn:org.opendaylight.aaa/features-aaa/0.1.0-SNAPSHOT/xml/features
-
-Install AAA AuthN features:
-
- feature:install odl-aaa-authn
+ feature:install odl-aaa-shiro
### Protecting your REST/RestConf resources
-Add the AAA `TokeAuthFilter` filter to your REST resource (RESTconf example):
+Add the AAA `AAAShiroFilter` filter to your REST resource (RESTconf example):
<servlet>
<servlet-name>JAXRSRestconf</servlet-name>
<param-name>javax.ws.rs.Application</param-name>
<param-value>org.opendaylight.controller.sal.rest.impl.RestconfApplication</param-value>
</init-param>
-
<!-- Token Auth Filter -->
<init-param>
<param-name>com.sun.jersey.spi.container.ContainerRequestFilters</param-name>
<param-value>
- org.opendaylight.aaa.sts.TokenAuthFilter
+ org.opendaylight.aaa.shiro.filters.AAAShiroFilter
</param-value>
</init-param>
-
<load-on-startup>1</load-on-startup>
</servlet>
-Rebuild and re-install your REST resource.
+Rebuild and re-install your REST resource.
### Running
curl -s -H 'Authorization: Bearer d772d85e-34c7-3099-bea5-cfafd3c747cb' http://<controller>:<port>/restconf/operational/opendaylight-inventory:nodes
-The operational state of access tokens cached in the MD-SAL can also be obtained after enabling the restconf feature:
-
- feature:install odl-aaa-all
-
-At the following URL
-
- http://controller:8181/restconf/operational/aaa-authn-model:tokencache/
-
-
## Framework Overview
### Authentication
-Here, the Opendaylight controller takes on 3 respective roles:
-
-- *Identity Provider*: Authenticates a user given some credentials.
-- *Authorization Server*: Determines what roles/permissions an authenticated user has.
-- *Resource Provider*: Provides access to a given resource based on the user's roles/permissions.
-
-The built-in IdP for Opendaylight can be swapped out by a different implementation of the `org.opendaylight.aaa.api.CredentialAuth` API.
-
#### Federated
In the federated use-case, the responsibility of authentication is delegated to a third-party IdP (perhaps, an enterprise-level IdP):
### Authorization & Access Control
-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.
+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:
+
+{
+ "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 ("roles" in shiro.ini) which is 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) shiro.ini urls section Authorization roles filter (i.e., "RolesAuthorizationFilter"). [DEPRECATED]
-NOTE: The Lithium release features a trail of Authz functionality, in particular longest string matching is not implemented.
+Authorization is implemented via the aaa-shiro modules. RolesAuthorizationFilter (roles filter) is limited purely to RESTCONF (HTTP) and does not focus on MD-SAL.
-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:
+More information on how to configure authorization can be found on the Apache Shiro website:
- 0. Compile or obtain the ODL distribution
- 1. Start karaf and install the odl-aaa-authz feature
+ http://shiro.apache.org/web.html
- 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
+NOTE: Use of shiro.ini urls section to define roles requirements is discouraged! This is due to the fact that shiro.ini changes are only recognized on servlet container startup. Changes to shiro.ini are only honored upon restart.
-Default authorization policies are loaded from the configuration subsystem (TODO: Provide a default set)
-They are accessible and editable via the restconf interface at:
+NOTE: Use of shiro.ini 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).
- http://<odl address>/restconf/configuration/authorization-schema:simple-authorization/
+### Accounting
-The schema for policies is a list consisting of the following items:
+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.
- * 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
+Two noteworthy logging activities are:
+1) Enable debugging logging
+2) Enable successful/unsuccessful authentication attempts logging
-Some examples of resources are:
+#### Enable Debugging Logging
- 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
+For debugging purposes (i.e., to enable maximum verbosity), issue the following command:
+karaf> log:set TRACE org.opendaylight.aaa
-*More on MD-SAL authorization later...*
+#### 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:
-### Accounting
+karaf> log:set DEBUG org.opendaylight.aaa.shiro.filters.AuthenticationListener
-*More on Accounting later...*
+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.
Code Review / aaa.git / blobdiff