-## 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:
+This project is aimed at providing a flexible, pluggable framework with out-of-the-box capabilities for Authentication, Authorization and Accounting.
-* *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
+## Caveats
+The following caveats are applicable to the current AAA implementation:
+ - The database (H2) used by ODL AAA Authentication store is not-cluster enabled. When deployed in a clustered environment each node needs to have its AAA
+ user file synchronised using out of band means.
## Quick Start
*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).
+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:
-Start the controller Karaf container:
-
- bin/karaf
-
-Install AAA repository from the Karaf shell:
-
- repo-add mvn:org.opendaylight.aaa/features-aaa/0.1.0-SNAPSHOT/xml/features
-
-Install all AAA features:
-
- feature:install odl-aaa-all
+ 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
-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.
-
-NOTE: The Helium 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 connnector configuration must
- be explicitly modified as follows:
-
- 0. Compile as per the above instructions
-
- 1. If you have already run ODL with Restconf or the mdsal-all feature package under karaf, then proceed as per below. Alternatively skip to step 2.
-
- 1a. consider deleting the assembly/data directory in your karaf install. This will require the re-activation of features at karaf startup.
-
- 1b. Delete the default restconf connector configuration file: "rm assembly/etc/opendaylight/karaf/10-rest-connector.xml"
-
- 2. Start karaf and install the odl-aaa-all feature as per the previous instructions
-
- 3. Start the odl-restconf feature via the command "feature:install odl-resctonf". An alternative can also be feature:install odl-mdsal-all
-
-
-To unistall authz:
-
- 1. Unistall the feature via "feature:uninstall feature:odl-aaa-authz"
- 2. Either:
- 2a. Locate and open in an editor the default 10-rest-connector.xml configuration file in assembly/etc/opendaylight/karaf/.
- Change the <dom-broker> configuration element
- FROM:
- <dom-broker>
- <type xmlns:dom="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">dom:dom-broker-osgi-registry</type>
- <name>authz-connector-default</name>
- </dom-broker>
- TO:
- <dom-broker>
- <type xmlns:dom="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">dom:dom-broker-osgi-registry</type>
- <name>dom-broker</name>
- </dom-broker>
- OR:
- 2b. Reinstall resctonf via the command "feature:install odl-resctonf"
-
-Legacy instructions for activating Authz in non karaf based ODL runtimes:
-
- 0. Build aaa project and copy all generated aaa jars to the plugins directory of your odl target install
- 1. Locate and open in an editor the default 10-rest-connector.xml configuration file. Default location is at 'configuration/initial'
- 2. Change the <dom-broker> configuration element
- FROM:
- <dom-broker>
- <type xmlns:dom="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">dom:dom-broker-osgi-registry</type>
- <name>dom-broker</name>
- </dom-broker>
- TO:
- <dom-broker>
- <type xmlns:dom="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">dom:dom-broker-osgi-registry</type>
- <name>authz-connector-default</name>
- </dom-broker>
- 3. Restart ODL
-
-Default authorization 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...*
+Authorization is implemented via the aaa-shiro modules. Currently, authorization 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
+
+### 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.
Code Review / aaa.git / blobdiff