Merge pull request #17 from docker/201906-201-updates

201906 201.2 and 201.3 updates

docs/201/201.1.rst

@@ -185,7 +185,7 @@ Exercise 201.1.7 What do you mean by "student"?
 
 The `student` reference group is used in access policy for student services.
 Being a "student" means access to a broad array of student services. This
-instutionally meaning cohort is well defined, easily understood, and capable
+instutionally meaningful cohort is well defined, easily understood, and capable
 of being extended in a rational way. Review the `students` reference group
 definition by using the Grouper Visualization feature. (students -> More
 actions -> Visualization)

docs/201/201.2.rst

@@ -1,13 +1,13 @@
-
-==============================
-GTE 201.2 Access Policy Groups
-==============================
+============================
+Access Policy Groups (201.2)
+============================
 
 -------------------
 Learning Objectives
 -------------------
 
-* Translate a natural language policy group into digital policy using access policy groups.
+* Translate a natural language policy group into digital policy using access
+  policy groups.
 * Understand the difference between policy groups and reference groups.
 
 --------------
@@ -23,91 +23,114 @@ Overview
 
 `NIST SP 800-162`_ describes how natural language policy, that is access policy
 stated in common language, must be converted to digital policy for any access
-control mechanism to effectively operate.  Digital policy is manifest in
+control mechanism to effectively operate. Digital policy is manifest in
 Grouper via access policy groups. Subject membership in an access policy group
-be indirect and represents a precomputed access policy decision based on subject
-attributes (i.e. the subject’s membership in various reference groups).
+should be indirect and represents a precomputed access policy decision based on
+subject attributes (i.e. a subject’s membership in various reference groups).
 
 An **access policy** group is a composite group whose membership is composed of
 an include group (i.e. the allow group) minus an exclude group (i.e. the deny
-group).  Subject membership in both the allow group and the deny group should be
-indirect (i.e. through reference groups) and have a clear mapping to the natural
-language policy.  When exceptions to policy are necessary, locally scoped
-reference groups should be added.
+group). Subject membership in both the allow group and the deny group should
+be indirect (i.e. through reference groups) and have a clear mapping to the
+natural language policy. When exceptions to policy are necessary, locally
+scoped reference groups should be added.
 
 Limiting policy groups to indirect membership assignments via reference groups
-ensures that as subject attributes change, effective membership is up to date and
-access control decisions are correct.  It also enables the direct mapping from
-natural language policy to digital policy and vice versa.  Individual exceptions to
-policy, while not expressly recommended, can be accommodated by adding subjects
-directly to the allow/deny groups.
+ensures that as subject attributes change, effective membership is up to date
+and access control decisions are correct. It also enables the direct mapping
+from natural language policy to digital policy and vice versa. Individual
+exceptions to policy, while not expressly recommended, can be accommodated by
+adding subjects directly to the allow/deny groups.
+
+Membership within an access policy group is often kept in sync directly with a
+target service or an intermediary like an LDAP based enterprise directory
+service. Services can also query Grouper directly for membership assignment.
+
+--------------------------------------------
+Exercise 201.2.1 Application folder template
+--------------------------------------------
+
+Generally, access policy groups are organzied in a set of folders following a
+common convention descripted in the Grouper Deployment Guide. A template for
+this structure is available in the Grouper UI. Use the Application Template to
+create a new structure for our VPN service policy.
 
-Membership within an access policy group is often kept in sync directly with a target
-service or an intermediary like an LDAP based enterprise directory service.
-Services can also query Grouper directly for membership assignment.
+#. Navigate to the `app` folder
+#. Create a new `vpn` application structure using the Application Template
+   (More actions -> New template)
 
-----------------
-Exercise 201.2.1
-----------------
+.. figure:: ../figures/201-new-vpn-app.png
 
-*Application folder structure*
+3. Navigate to the `app:vpn:service:policy` folder
 
-#. Create `app:vpn:vpn_authorized`.
-#. Create `app:vpn:vpn_allow`.
-#. Create `app:vpn:vpn_deny`.
-#. Make `vpn_authorized` a composite of `vpn_allow` minus `vpn_deny`.
+4. Create a new vpn_authorized policy group using the Policy Group Template
+   (More actions -> New template)
 
-----------------
-Exercise 201.2.2
-----------------
+.. figure:: ../figures/201-new-vpn-policy.png
 
-*Create digital policy from natural language policy*
+[ this should be replaced with policy template when ready ]
 
-Natural language policy is "all faculty, staff have access to vpn, unless denied
-by CISO or the account is in a closure state".  Reference groups are already
-available.
+5. Create `app:vpn:vpn_authorized`.
+6. Create `app:vpn:vpn_allow`.
+7. Create `app:vpn:vpn_deny`.
+8. Make `vpn_authorized` a composite of `vpn_allow` minus `vpn_deny`.
+
+.. figure:: ../figures/201-vpn-composite.png
+
+-------------------------------------------------------------------
+Exercise 201.2.2 Create digital policy from natural language policy
+-------------------------------------------------------------------
+
+The natural language policy is "all faculty and staff have access to vpn,
+unless denied by CISO or the account is in a closure state".  Reference groups
+are already available.
 
 #. Add `ref:employee:fac_staff` to `vpn_allow`.
 #. Add `ref:security:locked_by_ciso` to `vpn_deny`.
 #. Add `ref:iam:closure` to `vpn_deny`.
+#. Review the `vpn_authorized` policy definition
+   (vpn_authorized -> More actions -> Visualization)
 
-----------------
-Exercise 201.2.3
-----------------
+.. figure:: ../figures/201-vpn-authorized.png
 
-*Update policy to also allow institutional review board members access to VPN*
+----------------------------------------------------------------------------
+Exercise 201.2.3 Update policy to include institutional review board members
+----------------------------------------------------------------------------
 
-New natural language policy is "all faculty, staff and members of the institutional
-review board have access to vpn, unless denied by CISO or the account is in a closure
-state".
+The new natural language policy is "all faculty, staff, and members of the
+institutional review board have access to vpn, unless denied by CISO or the
+account is in a closure state".
 
 #. Add `org:irb:ref:irb_members` to `vpn_allow`.
 #. Add *jsmith* to `org:irb:ref:irb_members`.
-#. Trace membership for *jsmith* from `vpn_authorized`.
-#. View the audit log on `vpn_allow`.
+#. Trace membership for *jsmith* from `vpn_authorized`. (jsmith -> Choose
+   action -> Actions -> Trace membership)
+
+.. figure:: ../figures/201-jsmith-trace.png
 
-----------------
-Exercise 201.2.4
-----------------
+4. View the audit log on `vpn_allow`. (vpn_allow -> More actions -> View audit
+   log)
 
-*Create security groups for policy*
+.. figure:: ../figures/201-vpn-allow-audit.png
 
-#. Create `ref:app:vpn:etc` folder.
-#. Create `ref:app:vpn:etc:vpn_admins` group.
-#. Assign **ADMIN** privilege to `vpn_admins` for `ref:app:vpn`.
-#. Inherit privileges to all sub folders (and objects).
+5. Review policy definition for `vpn_authorized`.
+   (vpn_authorized -> More actions -> Visualization)
 
-    #. Navigate to `app:vpn`.
-    #. :guilabel:`More` |rightarrow| :guilabel:`Privileges inherited to objects in folder`
-    #. Click :guilabel:`Add Members`, and add `vpn_admins`.
-    #. Add admin privileges for folder, group, and attributes.
+.. figure:: ../figures/201-vpn-authorized2.png
 
-#. Navigate to `ref:app:vpn:ref:vpn_allow`.
-#. Click :guilabel:`Privileges` |rightarrow| :guilabel:`Actions` |rightarrow| :guilabel:`Trace Priviliges`.
+------------------------------------------------------------
+Exercise 201.2.4 Review Application template security groups
+------------------------------------------------------------
 
+Adminstrative access to the application template folders and groups is
+controlled by security groups in `app:vpn:security`. Security groups are
+essentially policy groups for Grouper access. Review the default privileges on
+`vpn_allow`.
 
+#. Naviage to `ref:app:vpn:service:policy:vpn_allow`.
+#. Click on the Privileges tab.
 
-.. |rightarrow| unicode:: U+2192
+.. figure:: ../figures/201-vpn-allow-privileges.png
 
 .. _NIST SP 800-162: https://csrc.nist.gov/publications/detail/sp/800-162/final
 .. _Grouper Deployment Guide: https://spaces.at.internet2.edu/display/Grouper/Grouper+Deployment+Guide+Work+-TIER+Program

docs/201/201.3.rst

@@ -1,7 +1,7 @@
 
-===================================
-GTE 201.3 ACM1 eduPersonAffiliation
-===================================
+=======================================================
+Access Control Model 1 eduPersonAffiliation (GTE 201.3)
+=======================================================
 
 -------------------
 Learning Objectives
@@ -27,17 +27,18 @@ Lab Components
 Overview
 --------
 
-`Grouper Deployment Guide`_ access control model 1 is all about subject attribute
-management.  This model is useful for cases where there exists a loose relationship
-between the institution and the service provider.  Assuming both are in a
-federation like InCommon, and a locally defined notion of eduPersonAffiliation_ is
-sufficient for access control, a broad set of services can be enabled fairly easily.
+`Grouper Deployment Guide`_ access control model 1 (ACM1) is all about subject
+attribute management. This model is useful for cases where there exists a loose
+relationship between the institution and the service provider. Assuming both
+are in a multilateral SAML federation like InCommon, and a locally defined
+notion of eduPersonAffiliation_ is sufficient for access control, a broad set
+of services can be enabled fairly easily.
 
 .. warning::
 
     This access control model is based on making subject attributes directly
     available to services and allowing the service to make access control decisions
-    based on those attributes.  This approach has several shortcomings:
+    based on those attributes. This approach has several shortcomings:
 
     * The subject attributes provided often lack sufficient **context** to make
       informed access control decisions.
@@ -62,38 +63,44 @@ sufficient for access control, a broad set of services can be enabled fairly eas
       affiliations based on the service provider requesting authentication (*policy
       decisions become opaque*).
     * Alternatively, exceptions may be handled by configuring them directly at
-      the service provider (*policy decisions become opaque*). 
+      the service provider (*policy decisions become opaque*).
 
-----------------
-Exercise 201.3.1
-----------------
+------------------------------------------------------------------
+Exercise 201.3.1 Create app folder for eduPersonAffiliation values
+------------------------------------------------------------------
+#. Navigate to the `app` folder
+#. Create a new `eduPersonAffiliation` application structure using the
+   Application Template (More actions -> New template)
 
-*Create app folder to master eduPersonAffiliation*
+.. figure:: ../figures/201-eduPersonAffiliation-app-template.png
 
-#. Create folder `app:eduPersonAffiliation`.
-#. Create groups `...:eduPersonAffiliation:ePA_student|staff|...` to represent
-   eduPersonAffiliation values. 
+#. Create the following policy groups in
+   `app:eduPersonAffiliation:service:policy:`
 
-----------------
-Exercise 201.3.2
-----------------
+* `ePA_student`
+* `ePA_faculty`
+* `ePA_staff`
 
-*Add reference groups that constitute local policy for eduPersonAffiliation values*
+.. figure:: ../figures/201-ePA-policy-groups.png
 
-    Therefore each institution will decide the criteria for membership in each
-    affiliation classification.  What is desirable is that a reasonable person
-    should find an institution's definition of the affiliation plausible.
+---------------------------------------------------------------------------
+Exercise 201.3.2 Add reference groups to eduPersonAffiliation policy groups
+---------------------------------------------------------------------------
 
-#. Add `ref:student:students` to `...:eduPersonAffiliation:ePA_student`.
+The eduPerson object class specification states:
+  "Therefore each institution will decide the criteria for membership in each
+  affiliation classification. What is desirable is that a reasonable person
+  should find an institution's definition of the affiliation plausible."
 
-----------------
-Exercise 201.3.3
-----------------
+#. Add `ref:student:students` to `...:eduPersonAffiliation:ePA_student`.
 
-*Create "member"*
+----------------------------------------------------------------------
+Exercise 201.3.3 Create eduPersonAffiliation policy group for "member"
+----------------------------------------------------------------------
 
-The "member" affiliation MUST be asserted for people carrying one or more of
-the following affiliations: *faculty* or *staff* or *student* or *employee*.
+The eduPerson object class specification states:
+  "The "member" affiliation MUST be asserted for people carrying one or more of
+  the following affiliations: *faculty* or *staff* or *student* or *employee*."
 
 .. note:
 
@@ -102,32 +109,39 @@ the following affiliations: *faculty* or *staff* or *student* or *employee*.
     faculty, staff and students.
 
 #. Create `app:eduPersonAffiliation:ePA_member`.
-#. Add `...:ePA_faculty|staff|student|employee` to `...:ePA_member`.
+#. Add `...:ePA_faculty | staff | student` to `...:ePA_member`.
+#. Review `ePA_member` defintion (ePA_member -> More actions -> Visualization)
 
-----------------
-Exercise 201.3.4
-----------------
+.. figure:: ../figures/201-ePA-member-vis.png
 
-*Configure PSPNG to reflect ePA values to LDAP*
+--------------------------------------------------------------
+Exercise 201.3.4 Configure PSPNG to reflect ePA values to LDAP
+--------------------------------------------------------------
 
-#. Assign PSPNG *provision_to* attribute to `ePA_student` with a value of
-   **pspng_affiliations**.
-#. Configure PSPNG to sync group membership to LDAP values for 
+#. Configure PSPNG to sync group membership to LDAP values for
    **eduPersonAffiliation**.
 
    .. literalinclude:: examples/201-3-4.pspng-epa.grouper-loader.properties
         :language: properties
         :caption: grouper-loader.properties
         :linenos:
 
-----------------
-Exercise 201.3.5
-----------------
+#. Assign PSPNG *provision_to* attribute to `ePA_member` with a value of
+   **pspng_affiliations**.
+
+.. figure:: ../figures/201-ePA-pspng.png
+
+3. Review and "Run job now" the PSPNG affiliations change log consumer daemon
+   job (Miscellaneous -> All daemon jobs)
 
-*Releasing ePA in SAML*
+.. figure:: ../figures/201-ePA-pspng-run.png
 
-The demo shibboleth IdP has been configured to release the ePA attribute to
-the demo SP.  The relevant configuration is below:
+---------------------------------------------------------------------
+Exercise 201.3.5 Configure Shibboleth to release eduPersonAffiliation
+---------------------------------------------------------------------
+
+The demo Shibboleth IdP has been configured to release the ePA attribute to
+the demo SP. The relevant configuration is below:
 
 .. literalinclude:: examples/201-3-5.attribute-filter.xml
     :language: xml
@@ -136,13 +150,9 @@ the demo SP.  The relevant configuration is below:
     :emphasize-lines: 9
     :linenos:
 
-
-
-
-
-
-
+1. Log in to https://localhost:8443/app with username `aclark706` and password `password`.
 
+.. figure:: ../figures/201-ePA-attribute-release.png
 
 .. _eduPersonAffiliation: https://www.internet2.edu/media/medialibrary/2013/09/04/internet2-mace-dir-eduperson-201203.html#eduPersonAffiliation
 .. _Grouper Deployment Guide: https://spaces.at.internet2.edu/display/Grouper/Grouper+Deployment+Guide+Work+-TIER+Program