Merge "Remove fabric testing from index"
diff --git a/developer/images/aether-config-log.png b/developer/images/aether-config-log.png
new file mode 100644
index 0000000..2b349ef
--- /dev/null
+++ b/developer/images/aether-config-log.png
Binary files differ
diff --git a/developer/images/aether-roc-gui-console-loggedin.png b/developer/images/aether-roc-gui-console-loggedin.png
new file mode 100644
index 0000000..0914fd2
--- /dev/null
+++ b/developer/images/aether-roc-gui-console-loggedin.png
Binary files differ
diff --git a/developer/images/aether-roc-gui-copy-api-key.png b/developer/images/aether-roc-gui-copy-api-key.png
new file mode 100644
index 0000000..90fa304
--- /dev/null
+++ b/developer/images/aether-roc-gui-copy-api-key.png
Binary files differ
diff --git a/developer/images/aether-roc-gui-user-details.png b/developer/images/aether-roc-gui-user-details.png
new file mode 100644
index 0000000..49a0b18
--- /dev/null
+++ b/developer/images/aether-roc-gui-user-details.png
Binary files differ
diff --git a/developer/images/dex-ldap-login-page.png b/developer/images/dex-ldap-login-page.png
new file mode 100644
index 0000000..746928d
--- /dev/null
+++ b/developer/images/dex-ldap-login-page.png
Binary files differ
diff --git a/developer/images/dex-ldap-umbrella-well-known.png b/developer/images/dex-ldap-umbrella-well-known.png
new file mode 100644
index 0000000..ba8c357
--- /dev/null
+++ b/developer/images/dex-ldap-umbrella-well-known.png
Binary files differ
diff --git a/developer/images/postman-auth-token.png b/developer/images/postman-auth-token.png
new file mode 100644
index 0000000..be6f88e
--- /dev/null
+++ b/developer/images/postman-auth-token.png
Binary files differ
diff --git a/developer/roc.rst b/developer/roc.rst
index 45ae27b..a460334 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
------------------------
@@ -45,25 +49,16 @@
cat > values-override.yaml <<EOF
import:
- onos-gui:
- enabled: true
+ onos-gui:
+ enabled: true
onos-gui:
- ingress:
- enabled: false
-
- sdcore-adapter-v3:
- prometheusEnabled: false
-
- sdcore-exporter:
- prometheusEnabled: false
-
- onos-exporter:
- prometheusEnabled: false
+ ingress:
+ enabled: false
aether-roc-gui-v3:
- ingress:
- enabled: false
+ ingress:
+ enabled: false
EOF
Installing the Aether-Roc-Umbrella Helm chart
@@ -209,6 +204,144 @@
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
+
+ROC Data Model Conventions and Requirements
+-------------------------------------------
+
+The MEGA-Patch described above will bring up a fully compliant sample data model.
+However, it may be useful to bring up your own data model, customized to a different
+site of sites. This subsection documents conventions and requirements for the Aether
+modeling within the roc.
+
+The ROC models must be configured with the following:
+
+* A default enterprise with the id `defaultent`.
+* A default ip-domain with the id `defaultent-defaultip`.
+* A default site with the id `defaultent-defaultsite`.
+ This site should be linked to the `defaultent` enterprise.
+* A default device group with the id `defaultent-defaultsite-default`.
+ This device group should be linked to the `defaultent-defaultip` ip-domain
+ and the `defaultent-defaultsite` site.
+
+Each Enterprise Site must be configured with a default device group and that default
+device group's name must end in the suffix `-default`. For example, `acme-chicago-default`.
+
Some exercises to get familiar
------------------------------
@@ -231,3 +364,5 @@
received)
.. |ROCGUI| image:: images/rocgui.png
+ :width: 945
+ :alt: ROC GUI showing list of VCS
diff --git a/index.rst b/index.rst
index 0d9d908..8e06e49 100644
--- a/index.rst
+++ b/index.rst
@@ -14,7 +14,6 @@
:glob:
operations/procedures
- operations/sop
operations/subscriber
.. toctree::
