AETHER-2044 add section on securing ROC to developer section
Change-Id: I1c3d1aae02affcf57a1be9e116cf6097c3e3ccc0
diff --git a/developer/roc.rst b/developer/roc.rst
index 45ae27b..3b1391d 100644
--- a/developer/roc.rst
+++ b/developer/roc.rst
@@ -13,6 +13,10 @@
As an alternative to the developer’s local machine, a remote environment can be set up, for example on
cloud infrastructure such as cloudlab.
+.. note:: When ROC is deployed it is unsecured by default, with no Authentication or Authorization.
+ To secure ROC so that the Authentication and Authorization can be tested, follow the Securing ROC
+ guide below :ref:`securing_roc`
+
Installing Prerequisites
------------------------
@@ -209,6 +213,123 @@
kubectl -n micro-onos logs sdcore-adapter-v3-7468cc58dc-ktctz sdcore-adapter-v3
+.. _securing_roc:
+
+Securing ROC
+------------
+
+When deploying ROC with the **aether-roc-umbrella** chart, secure mode can be enabled by
+specifying an OpenID Connect (OIDC) issuer like::
+
+ helm -n micro-onos install aether-roc-umbrella sdran/aether-roc-umbrella \
+ --set onos-config.openidc.issuer=http://dex-ldap-umbrella:5556 \
+ --set aether-roc-gui-v3.openidc.issuer=http://dex-ldap-umbrella:5556
+
+The choice of OIDC issuer in this case is **dex-ldap-umbrella**
+
+dex-ldap-umbrella
+~~~~~~~~~~~~~~~~~
+
+Dex is a cloud native OIDC Issuer than can act as a front end to several authentication systems
+e.g. LDAP, Crowd, Google, GitHub
+
+Dex-LDAP-Umbrella is a Helm chart that combines a Dex server with an LDAP installation, and an
+LDAP administration tool. It can be deployed in to the same cluster namespace as **aether-roc-umbrella**.
+
+Its LDAP server is populated with 7 different users in the 2 example enterprises - *starbucks* and *acme*.
+
+When running it should be available at *http://dex-ldap-umbrella:5556/.well-known/openid-configuration*.
+
+See `dex-ldap-umbrella <https://github.com/onosproject/onos-helm-charts/tree/master/dex-ldap-umbrella#readme>`_
+for more details.
+
+As an alternative there is a public Dex server connected to the ONF Crowd server, that allows
+ONF staff to login with their own credentials:
+See `public dex <https://dex.aetherproject.org/dex/.well-known/openid-configuration>`_ for more details.
+
+.. note:: Your RBAC access to ROC will be limited by the groups you belong to in Crowd.
+
+Role Based Access Control
+~~~~~~~~~~~~~~~~~~~~~~~~~
+When secured, access to the configuration in ROC is limited by the **groups** that a user belongs to.
+
+* **AetherROCAdmin** - users in this group have full read **and** write access to all configuration.
+* *<enterprise>* - users in a group the lowercase name of an enterprise, will have **read** access to that enterprise.
+* **EnterpriseAdmin** - users in this group will have read **and** write access the enterprise they belong to.
+
+ For example in *dex-ldap-umbrella* the user *Daisy Duke* belongs to *starbucks* **and**
+ *EnterpriseAdmin* and so has read **and** write access to items linked with *starbucks* enterprise.
+
+ By comparison the user *Elmer Fudd* belongs only to *starbucks* group and so has only **read** access to items
+ linked with the *starbucks* enterprise.
+
+Requests to a Secure System
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When configuration is retrieved or updated through *aether-config*, a Bearer Token in the
+form of a Json Web Token (JWT) issued by the selected OIDC Issuer server must accompany
+the request as an Authorization Header.
+
+This applies to both the REST interface of *aether-roc-api* **and** the *gnmi* interface of
+*aether-rconfig*.
+
+In the Aether ROC, a Bearer Token can be generated by logging in and selecting API Key from the
+menu. This pops up a window with a copy button, where the key can be copied.
+
+The key will expire after 24 hours.
+
+.. image:: images/aether-roc-gui-copy-api-key.png
+ :width: 580
+ :alt: Aether ROC GUI allows copying of API Key to clipboard
+
+Accessing the REST interface from a tool like Postman, should include this Auth token.
+
+.. image:: images/postman-auth-token.png
+ :width: 930
+ :alt: Postman showing Authentication Token pasted in
+
+Logging
+~~~~~~~
+The logs of *aether-config* will contain the **username** and **timestamp** of
+any **gnmi** call when security is enabled.
+
+.. image:: images/aether-config-log.png
+ :width: 887
+ :alt: aether-config log message showing username and timestamp
+
+Troubleshooting Secure Access
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+While every effort has been made to ensure that securing Aether is simple and effective,
+some difficulties may arise.
+
+One of the most important steps is to validate that the OIDC Issuer (Dex server) can be reached
+from the browser. The **well_known** URL should be available and show the important endpoints are correct.
+
+.. image:: images/dex-ldap-umbrella-well-known.png
+ :width: 580
+ :alt: Dex Well Known page
+
+If logged out of the Browser when accessing the Aether ROC GUI, accessing any page of the application should
+redirect to the Dex login page.
+
+.. image:: images/dex-ldap-login-page.png
+ :width: 493
+ :alt: Dex Login page
+
+When logged in the User details can be seen by clicking the User's name in the drop down menu.
+This shows the **groups** that the user belongs to, and can be used to debug RBAC issues.
+
+.. image:: images/aether-roc-gui-user-details.png
+ :width: 700
+ :alt: User Details page
+
+When you sign out of the ROC GUI, if you are not redirected to the Dex Login Page,
+you should check the Developer Console of the browser. The console should show the correct
+OIDC issuer (dex server), and that Auth is enabled.
+
+.. image:: images/aether-roc-gui-console-loggedin.png
+ :width: 418
+ :alt: Browser Console showing correct configuration
+
Some exercises to get familiar
------------------------------
@@ -231,3 +352,5 @@
received)
.. |ROCGUI| image:: images/rocgui.png
+ :width: 945
+ :alt: ROC GUI showing list of VCS