Hardwire Services in sts ServiceLocator

[aaa.git] / README.md

diff --git a/README.md b/README.md
index f035c61eae6f1e02d13c4c55c9bf2e36b2acde6f..86303e17b4c9c9b25a5a6a197712bd00b4f40a38 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
 
@@ -68,7 +73,7 @@ Rebuild and re-install your REST resource.
 
 Once the installation finishes, one can authenticates with the Opendaylight controller by presenting a username/password and a domain name (scope) to be logged into:
 
-    curl -s -d 'grant_type=password&username=admin&password=odl&scope=pepsi' http://<controller>:<port>/oauth2/token
+    curl -s -d 'grant_type=password&username=admin&password=admin&scope=sdn' http://<controller>:<port>/oauth2/token
 
 Upon successful authentication, the controller returns an access token with a configurable expiration in seconds, something similar to the followings:
 
@@ -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...*