Merge branch 'main' of github.internet2.edu:internet2/iam-knowledge-bits

Documentation-as-DevOps.adoc

@@ -0,0 +1,24 @@
+=== Documentation-as-DevOps
+
+==== One Option
+
+. Review Evolveum Documentation: https://docs.evolveum.com/, and their writing processes: https://docs.evolveum.com/about/writing-documentation/, https://docs.evolveum.com/about/asciidoc/
+. Migrate existing content from Confluence XHTML to asciidoc: https://docs.asciidoctor.org/asciidoctor/latest/migrate/confluence-xhtml/ 
+. Create and edit new and existing files with asciidoc, push to a github repo
+. Include PlanntUML, C4, and output from additional diagramming tools with the asciidoctor extension for kroki: https://github.com/ggrossetie/asciidoctor-kroki, https://kroki.io/
+. Create an Antora site to host the asciidoc files
+. Anrtora Assembler: add-on library and extension that assembles content from multiple pages into aggregate documents, converts them to the specified output format, and publishes them alongside other files in the site https://gitlab.com/antora/antora-assembler 
+. Follow Antora guidance to create a pipeline to rebuild the site whenever content is added, edited, or deleted: https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=&ved=2ahUKEwiB5IfittT-AhWVk4kEHR9zBwQQFnoECBcQAQ&url=https%3A%2F%2Fdocs.antora.org%2Fantora%2Flatest%2Fpublish-to-gitlab-pages%2F&usg=AOvVaw3vOCafAF8DhwsRqTQbeFcm
+
+==== DevOps approach to Documentation: Reference materials
+- Evolveum documentation site: https://docs.evolveum.com
+- Asciidoc: https://asciidoc.org  
+- Markdown: https://www.markdownguide.org/
+- Antora: https://antora.org/ "multi-repository documentation site generator for tech writers writing in AsciiDoc"
+- Github Pages or Gitlab Pages (Auto Re-Publication on commit to repo)
+- https://pages.github.com, https://docs.gitlab.com/ee/user/project/pages/
+- Gitlab Demo ‘source’: https://gitlab.com/antora/demo 
+- Gitlab Demo published version: https://antora.gitlab.io/demo/docs-site/component-b/2.0/index.html
+- Pros and Cons of Markdown vs Asciidoc: https://www.slant.co/versus/1903/23065/~markdown_vs_asciidoc
+- Jeff Sandberg, "I wish asciidoc was more popular": https://pdx.su/blog/2023-02-05-asciidoc-and-markdown/
+

connector-howto.adoc

@@ -0,0 +1,231 @@
+=== connector-howto.adoc
+
+SEE workbench.adoc +
+permalink: https://github.internet2.edu/internet2/iam-knowledge-bits/blob/main/connector-howto.adoc +
+next] LDAP/AD provisioning with midPoint
+
+- - -
+_2023-03-22 19:12:40 Connector Howto_
+
+*- Reset Workbench to pristine state -*
+
+```
+ssh csprootuser@khazelton.workbench.incommon.org
+cd  /csp-tap/InCommonTAP-Examples/Workbench
+
+docker-compose down -v
+docker-compose up -d
+```
+
+==== Add the Artists' Collective, a new CSV resource, to the Workbench
+
+*- First, Where is the MIDPOINT_HOME directory? -*
+
+` In the Workbench host for the containers, MIDPOINT_HOME is: +
+` /csp-tap/InCommonTAP-Examples/Workbench/midpoint_server/container_files/mp-home
+
+` Everything in MIDPOINT_HOME is mapped to +
+` /opt/midpoint/var +
+` inside the running container
+
+
+*- Artists Collective demo -*
+
+` User schema extension .xsd files go into MIDPOINT_HOME/schema +
+` .csv data file for the Artist Collective resource also goes into MIDPOINT_HOME +
+
+```
+cd $MIDPOINT_HOME
+ls -la schema
+ls -la usertype_export.csv
+```
+
+*- Complete the Artists' Collective resource definition, 100-mnt0.xml -*
+
+` Edit resource definition file on local computer: +
+` ~/opt/kh-wb/objects/resources/100-mnt0.xml
+
+` fill in the essential parameter definitions section by section:
+
+` Connector section +
+` Schema section +
+` Schema Handling section +
+` Capabilities section +
+` Synchronization section +
+
+*- The Artist Collective resource config goes into MIDPOINT_HOME/post-initial-objects/resources on the Workbench host -*
+
+` Use MidPoint Studio to connect to the workbench host and upload the above files to their proper locations +
+
+*- Once the files are in place, Open the Workbench UI and select Midpoint -*
+
+` go to Resources / Import Resource Definition, Browse to 100-mnt0.xml on local host +
+` click Import +
+
+` Back to 'All Resources / TMNT System', select Accounts, scroll down and press the Import button +
+` Open 'Accounts' on the new resource, Scroll down to the list of users and select one for viewing
+
+*- Now browse to the Users tab, scroll to 2nd page and note that Cesare Borgia from the Artists' Collective is now recognized as a User in midPoint
+
+*- This process can be used as a template for adding any other csv-based resource -*
+
+*- TBD: native install -*
+
+` replicate artist/hr resource on MBProMax: ~/opt/midpoint-4.6 +
+` ~/Users/khazelton/opt/midpoint-4.6 <- MIDPOINT_HOME +
+` MIDPOINT_HOME/bin <- All the start/stop/etc scripts 
+
+```
+cd $MIDPOINT_HOME
+./bin/start.sh <- To Start midPoint
+```
+- - -
+
+next: replicate artist/hr resource on MBProMax:midpoint-4.6
+
+- - -
+_2023-03-22 14:36:48 csv connector, resource configuration_
+
+/csp-tap/InCommonTAP-Examples/Workbench/midpoint_server/container_files/mp-home
+/csp-tap/InCommonTAP-Examples/Workbench/midpoint_server/container_files/mp-home/post-initial-objects/
+resources/100-mnt.xml
+
+if you make changes in the midpoint files on the host running docker, you must bring the running containers down with the option that clears out the existing mapped files in the container:
+
+```
+docker-compose down -v
+...
+docker-compose up -d
+```
+*- working tmnt resource def -* +
+~/opt/kh.wb/objects/resources/SourceTMNTSystem.xml
+
+- - -
+_2023-03-21 17:42:32 csv connector, resource configuration_
+
+*- Host for containerize workbench -*
+
+```
+Workbench/midpoint_server/container_files/mp-home
+
+COPY ../Workbench/midpoint_server/container_files/mp-home/   /opt/midpoint/var/
+                     |                                             |
+                base in container host                      base inside connector
+```
+
+*- in the container -*
+
+```
+├── container_files
+│   ├── csv
+│   │   ├── source-hr.csv
+│   │   └── UserType_export.csv          //  <-
+│   ├── httpd
+│   │   ├── 00-shib.conf
+│   │   ├── host-cert.pem
+│   │   ├── host-key.pem
+│   │   ├── midpoint-shib.conf
+│   │   └── vhosts.conf
+│   ├── mp-home
+│   │   ├── config.xml
+│   │   ├── cs-portal.csv
+│   │   ├── faculty-portal.csv
+│   │   ├── icf-connectors
+│   │   │   ├── connector-grouper-rest-0.7.jar
+│   │   │   ├── connector-rest-wordpress-.23-SNAPSHOT.jar
+│   │   │   ├── connector-sympa-1.0.2-connector.jar
+│   │   │   └── net.tirasa.connid.bundles.db.scriptedsql-2.2.-SNAPSHOT.jar
+│   │   ├── lib
+│   │   │   ├── mariadb-java-client-3.0.jar
+│   │   │   └── mysql-connector-java-8.0.30.jar
+│   │   ├── mailing-lists.csv
+│   │   ├── post-initial-objects
+│   │   │   ├── archetypes
+│   │   │   │   ├── 300-archetype-affiliation.xml
+│   │   │   │   ├── 300-archetype-course.xml
+│   │   │   │   ├── 300-archetype-department.xml
+│   │   │   │   ├── 300-archetype-external-person.xml
+│   │   │   │   ├── 300-archetype-generic-grouper-group.xml
+│   │   │   │   ├── 300-archetype-mailing-list.xml
+│   │   │   │   ├── 300-archetype-midpoint-group.xml
+│   │   │   │   ├── 300-archetype-sis-person.xml
+│   │   │   │   ├── 400-archetype-guest-person.xml
+│   │   │   │   └── 500-archetype-hr-person.xml
+│   │   │   ├── bulkActions
+│   │   │   │   ├── 900-test-all-resources.xml
+│   │   │   │   └── 910-recompute-grouper-objects.xml
+│   │   │   ├── functionLibraries
+│   │   │   │   └── 100-function-library-grouper.xml
+│   │   │   ├── objectTemplates
+│   │   │   │   └── 100-template-user.xml
+│   │   │   ├── ordering.txt
+│   │   │   ├── orgs
+│   │   │   │   ├── 100-org-affiliations.xml
+│   │   │   │   ├── 100-org-courses.xml
+│   │   │   │   ├── 100-org-departments.xml
+│   │   │   │   ├── 100-org-generic-groups.xml
+│   │   │   │   ├── 100-org-mailing-lists.xml
+│   │   │   │   ├── 100-org-midpoint-groups.xml
+│   │   │   │   ├── 400-org-grouper-sysadmin.xml
+│   │   │   │   ├── 500-org-hr-sor.xml
+│   │   │   │   └── 600-org-guest-sor.xml
+│   │   │   ├── resources                              // <-
+│   │   │   │   ├── 100-connector-rest-wordpress.xml
+│   │   │   │   ├── 100-grouper.xml
+│   │   │   │   ├── 100-guest-db.xml
+│   │   │   │   ├── 100-ldap-main.xml
+│   │   │   │   ├── 100-source-hr-sor.xml
+│   │   │   │   ├── 100-source-sis-persons.xml
+│   │   │   │   ├── 100-target-cs-portal.xml
+│   │   │   │   ├── 100-target-faculty-portal.xml
+│   │   │   │   └── 100-target-mailing-lists.xml
+│   │   │   ├── roles
+│   │   │   │   ├── 200-metarole-grouper-provided-group.xml
+│   │   │   │   ├── 200-metarole-ldap-group.xml
+│   │   │   │   ├── 200-metarole-role-wordpress-admin.xml
+│   │   │   │   ├── 200-metarole-role-wordpress-editor.xml
+│   │   │   │   ├── 200-role-ldap-basic.xml
+│   │   │   │   ├── 300-direct-wordpress-role-admin.xml
+│   │   │   │   └── 300-direct-wordpress-role-editor.xml
+│   │   │   ├── securityPolicy
+│   │   │   │   └── 000-security-policy.xml
+│   │   │   ├── systemConfigurations
+│   │   │   │   └── 010-system-configuration.xml
+│   │   │   ├── tasks
+│   │   │   │   ├── 300-task-hr-import.xml
+│   │   │   │   ├── 300-task-import-guests-sql.xml
+│   │   │   │   ├── 300-task-import-sis-persons.xml
+│   │   │   │   ├── 500-task-import-guests-sql-livesync.xml
+│   │   │   │   ├── 995-task-group-scavenger.xml
+│   │   │   │   ├── 997-task-async-update-grouper.xml
+│   │   │   │   ├── 998-task-reconciliation-grouper-groups.xml
+│   │   │   │   └── 999-task-recomputation-users.xml
+│   │   │   └── users
+│   │   │       └── 600-user-banderson.xml
+│   │   ├── res
+│   │   │   └── sis-persons
+│   │   │       ├── SchemaScript.groovy
+│   │   │       ├── SearchScript.groovy
+│   │   │       └── TestScript.groovy
+│   │   ├── schema
+│   │   │   ├── fanner.xsd
+│   │   │   └── internet2.xsd
+│   │   ├── source-external.csv
+│   │   ├── staff-portal.csv
+│   │   └── UserType_export.csv
+│   ├── shibboleth
+│   │   ├── attribute-map.xml
+│   │   ├── idp-metadata.xml
+│   │   ├── shibboleth2.xml
+│   │   ├── shibd.logger
+│   │   ├── sp-encrypt-cert.pem
+│   │   ├── sp-encrypt-key.pem
+│   │   ├── sp-signing-cert.pem
+│   │   └── sp-signing-key.pem
+│   └── system
+│       └── setservername.sh
+└── Dockerfile
+```
+
+- - -
+

connectors.adoc

@@ -1,5 +1,5 @@
 === connectors.adoc
-permalink: https://github.internet2.edu/internet2/iam-knowledge-bits/blob/main/connectors.adoc +
+permalink: https://github.internet2.edu/internet2/iam-knowledge-bits/blob/main/connector-howto.adoc +
 next] LDAP/AD provisioning with midPoint
 
 - - -

iamPatterns.adoc

@@ -1,5 +1,10 @@
 ### IAM Patterns Ideas
 
+https://docs.google.com/spreadsheets/d/1c7k2871uY6fm_Wz7M-bW-e1ZP511-uYWJf0tCbABGOQ/edit#gid=44522133
+ <- iamCapFunc +
+ https://drive.google.com/file/d/14N45a0Wu0BeapmChRxj27uILA1OJqf_L/view?usp=sharing
+ <- T&I Reference Architecture +
+
 #### Level X: Use Cases with base architecture
 
 *- Use Case 1 - Federation Enablement -* +

id/Internet2/edu.adoc

@@ -0,0 +1,40 @@
+== Initial Proposal for a Trust and Identity Registry of Namespaces and Identifiers
+
+===== T&I namespaces and assigned identifiers belong to one of the following Types
+
+
+* OIDs
+* URNs
+* URLs
+* Namespaces
+* Specs
+* Schema
+* Fed entities(?)
+
+===== Consolidated registry for the above
+
+
+* Construct a Trust and Identity registry tree, top level of which should be 'https://id.internet2.edu/ti'.  
+* Next path element under /ti is selected from the extensible controlled vocabulary:  oid', 'urn', 'url', 'namespace', 'spec', 'schema', 'fed?'
+** E.g.'https://id.internet2.edu/ti/urn'
+* Final fragment (after #) is an identifier of the type labeled by the parent node and must be unique within the scope of that parent
+** E.g. https://id.internet2.edu/ti/urn#mace:osu.edu
+* All Registry URLs must be
+** Under a single entry point
+** Resolvable
+** Immutable
+* What should https://id.internet2.edu/ti resolve to?
+** A home page with a navigable and foldable tree of registry contents
+* What should each unique identifier (leaf) resolve to? 
+** A populated instance of a defined data structure TBD
+
+* Open Issue: What should be included in the Entry data structure?
+
+====== Management of the Registry
+
+* There must be defined processes for assigning URLs of each Type
+** The current process for assigning MACE URNs provides a starting point model for such processes
+* There should be a Registrar responsible for Registry operations overall
+* Delegated admins may be assigned responsibilities for specific entry Types
+* Processes must be reliable and timely
+