Update README.md

README.md

@@ -1,2 +1,105 @@
 # person-identifiers
-Analysis and Recommendation on Person Identifiers in IAM Infrastructure
+### Analysis and Recommendation on Person Identifiers in IAM Infrastructure
+
+== Person Identifiers
+
+:Date:      2021-04-09
+:Revision:  01
+:SelfLink:  https://github.internet2.edu/api-schema/person
+:Editor:    Keith Hazelton
+:Email:     hazelton@internet2.edu
+
+[INFO]
+====
+Revision: {Revision}, ({Date}) +
+Self-link: {SelfLink} +
+Editor: {Editor}, {Email}
+====
+
+==== Issues and Observations
+
+*Person identifier handling in
+COmanage, Grouper, midPoint, LDAP, and AD
+
+identifier characteristics: Definitive statement for HE and Research: https://wiki.shibboleth.net/confluence/display/CONCEPT/NameIdentifiers
+
+. unique across the IdPs population Y/N
+
+G does have its own internal-only identifier
+  identifier is a tuple, sourceID + personID from that source
+  enter ePPN, or link in email for new ppl being added
+  id to label person in system, but also identifiers for looking them up: email, name,....LoginID
+  id and identifier (anything that can uniquely identify a person
+  Grouper external users is where the ePPN for a new member
+
+COm: In general, a multi-values list of identifiers paired with a source identifier; there is a non-shared internal ID
+  Grouper: 
+
+  Refereence ID: two match modes: Match up front; config. COmanage to match based on RefID. registry gets a ref id, and stores it 
+
+  Match API backend is just a database that understands ref id and sourceID
+
+  provision to LDAP, point Grouper subject source at LDAP;
+
+
+mp: OID is permanent, not shared name is a name-based identifier (other could be added), can change if needed, could be a campus id that users tend to know
+- globally unique by inclusion of a scope element or domain identifier
+- mP can generate any other unique id and share with external systems
+
+. name-based or otherwise recognizable? Y/N
+internal id: No
+. opaque (not name-based or otherwise recognizable) Y/N
+
+- permanent (changes are rare or non-existent)
+can be merged if necessary.
+
+- re-assignable (once assigned, a given identifier value will never be reused and assigned to another person)
+
+
+- pairwise (formerly called targeted): A person has a different identifier for each service or resource provider with which they interact
+
+
+. What is the primary, wholly internal person identifier in your package?
+
+COm: identifier modules to generate identifiers with the desired characteristics; 
+
+KeithL: If you make a REST call: here's user, get the OID, use that in the actual REST call
+
+. What identifier(s) do you expose to other packages? Internal ID plus tuple source/identifier
+generate anything you want, configurable; DO NOT USE OID; mP API is a case where you could use OID, 
+
+- Do you maintain a crosswalk between each external system identifier and your internal identifier?
+ correlation rule: connector says how the id in system maps to id in mP; midPoint maintains link over subsequent change
+
+. How do you handle changes to name-based identifiers
+-
+connectors can work w opaque: UID (used to link to the midPoint user, and another identifier, perhaps name based; mP can update the name identifier
+
+If UID link breaks, correlation can relink.
+
+
+- - -
+
+Hypothetical Precondition:
+
+A person was just now added to a System of Record,
+midPoint has not yet processed this, so has no record of their existence
+
+Process A: A Grouper admin wants to manage groups for the new person
+. Grouper admin types something they know about the person (a name or email or other identifier) into Grouper
+.. Case 1: Subject lookup--not found. What happens then?
+.. Case 2: Person is found in subject source. What identifier is used when adding them as a member to a group?
+... What manages getting subjects into the subject source
+... How does midPoint associate this group member with a know user?
+
+"Solutions and tradeoffs"
+
+. Have Grouper subject source be provisioned by midPoint;
+.. Consequences: Grouper subject search will fail until new person appears in subject source
+
+. Have ID Match always return an identifier for the queried person
+.. works for cases where ID Match can definitively match a known identity or definitively be recognized as new, and return the identifier in either case
+.. If the result is multiple candidate matches that require human resolution, Id Match does not immediately return an identifier
+.. Fix: Have ID Match assign a new identifier to the person in question and return immediately while starting the identity resolution workflow
+... Consequence: If a match with an existing user is eventually found, an identifier correction needs to take place
+