Merge "Bug 2515 - Jersey to support JAX-RS 2.0"

[aaa.git] / README.md

diff --git a/README.md b/README.md
index bde3b66275e9813dcf294ccf407906941cab69df..f687fce8a07a1a609fa667765b80d903e1db64a8 100644 (file)
--- a/README.md
+++ b/README.md
@@ -6,6 +6,11 @@ This project is aimed at providing a flexible, pluggable framework with out-of-t
 * *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
 
 ### Building
@@ -35,9 +40,9 @@ 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:
+Install AAA AuthN features:
 
-       feature:install odl-aaa-all
+       feature:install odl-aaa-authn
 
 ### Protecting your REST/RestConf resources
 
@@ -45,7 +50,7 @@ Add the AAA `TokeAuthFilter` filter to your REST resource (RESTconf example):
 
     <servlet>
         <servlet-name>JAXRSRestconf</servlet-name>
-        <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
+        <servlet-class>org.glassfish.jersey.core.spi.container.servlet.ServletContainer</servlet-class>
         <init-param>
             <param-name>javax.ws.rs.Application</param-name>
             <param-value>org.opendaylight.controller.sal.rest.impl.RestconfApplication</param-value>
@@ -53,7 +58,7 @@ Add the AAA `TokeAuthFilter` filter to your REST resource (RESTconf example):
         
         <!-- Token Auth Filter -->
         <init-param>
-            <param-name>com.sun.jersey.spi.container.ContainerRequestFilters</param-name>
+            <param-name>org.glassfish.jersey.core.spi.container.ContainerRequestFilters</param-name>
             <param-value>
                 org.opendaylight.aaa.sts.TokenAuthFilter
             </param-value>
@@ -78,6 +83,15 @@ The access token can then be used to access protected resources on the controlle
 
     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
@@ -116,13 +130,44 @@ In this case, we use the IdP token directly as an access token to access protect
 
 ### Authorization & Access Control
 
-Upon successful authentication, an authentication context is created and is available for access via the OSGi service `org.opendaylight.aaa.api.AuthenticationService`.  The authentication context consists of the following information:
+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:
 
-* UserId/Name
-* DomainId/Name
-* Roles
+      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
 
-Based on the current authentication context, it is the responsibility of the OSGi applications within the controller to provide the appropriate access control, via bespoke logic or the MD-SAL security framework.  
 
 *More on MD-SAL authorization later...*