diff --git a/_episodes/01-COperson.md b/_episodes/01-COperson.md index bb7065a..27fbf1c 100644 --- a/_episodes/01-COperson.md +++ b/_episodes/01-COperson.md @@ -18,10 +18,11 @@ The information stored in the :gear: `CO Person` object typically includes * The organization or collaboration of which the person is a part (in the form of an identifier) * The person's status within that organization or collaboration -* Minimal information about the person including the person's preferred time zone and date of birth. +* Minimal information about the person including the person's preferred time zone and date of birth, list of physical addresses. * List of names * List of identifiers * List of email addresses +* list of physical addresses This object also is connected to several other structural items that we will talk about in this lesson, including @@ -30,6 +31,8 @@ This object also is connected to several other structural items that we will tal * **Group Memberships** - membership in a specific COmanage organizational object called a :gear" `CO Group`. We will learn more about :gear" `CO Groups` in a later lesson. * **Authenticators** - methods for the person to sign into COmanage +--- + # CO Person status Each :gear: `CO Person` object has a status attached to it. This status is a calculated value based on the person's status in each of the Roles that the person has assumed in your organization or collaboration. We will review the calculation method when we talk about Roles. Status can be changed manually, or can change automatically based on conditions that you may set, or by workflows that you put in place. @@ -78,13 +81,19 @@ When storing email addresses, more than one can be associated with the :gear: `C * **delivery** - the delivery location (e.g., mailbox). _LDAP attribute: mailForwardingAddress_ * **forwarding** - Address to forward mail to, perhaps if there is no delivery address, or an official or personal address is not functioning. _LDAP attribute: mailForwardingAddress_ -# Hands on +# About physical addresses + +This information is not used by COmanage, but since it is handy to have physical address information in your registry, it is included. Any number of physical addresses may be associated with a :gear" `CO Person` object. + +--- + +# Hands on - Starting our person model ![Interactive system activity](../assets/img/hands-on-keyboard.png) -As we build our understanding of how people are modeled in COmanage, we will use people in your organization as examples. In your printed packet, there are sheets for :memo: **Modeling People**. +As we build our understanding of how people are modeled in COmanage, we will use people in your organization as examples. In your printed packet, there are sheets for [ :memo: Modeling People](/files/handouts/CO310_ExamplePerson.pdf). -Think of at least three people in your organization that you can use as examples. The three that you choose should assume different roles in your organization or collaboration. Maybe they have different levels of authority, have access to different kinds of systems or services, form and manage their own groups. +Think of at least three people in your organization that you can use as examples. The three that you choose should assume different roles in your organization or collaboration. Maybe they have different levels of authority, have access to different kinds of systems or services, form and manage their own groups. One of the people you choose may even work for a different organization, though collaborates with individuals in your organization. Once you have thought about who you will use as your examples, write their names (or an alias!) on the sheets, one name per sheet. The name goes in the center circle that is labeled "CO Person". @@ -105,7 +114,7 @@ OBJECT | DESCRIPTION WORKSHEET | DESCRIPTION --------- | ----------- -[ :memo: Modeling People](link_to_a_PDF_in_files>handouts) | Planning sheet used in this lesson for understanding how to model people in COmanage. This sheet is used to organize how specific people and their relationships would be expressed within COmanage +[ :memo: Modeling People](/files/handouts/CO310_ExamplePerson.pdf) | Planning sheet used in this lesson for understanding how to model people in COmanage. This sheet is used to organize how specific people and their relationships would be expressed within COmanage ## Slides @@ -113,7 +122,7 @@ To be included --- -NEXT SECTION: [The OrgIdentity Object](/_episodes/02-orgIdentity.md) +NEXT SECTION: [2. The OrgIdentity Object](/_episodes/02-orgIdentity.md) LESSON OVERVIEW: [CO310 - Modeling People in COmanage](../index.md) diff --git a/_episodes/01-old-dividingCOsAndCOUs.md b/_episodes/01-old-dividingCOsAndCOUs.md deleted file mode 100644 index aca8f01..0000000 --- a/_episodes/01-old-dividingCOsAndCOUs.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Sub-dividing COs & COUs" -teaching: 20 -exercises: 0 -questions: -- "Question here" -objectives: -- "List the objectives" -keypoints: -- "List the key takeaways for the episode" ---- - -## Difference between CO Groups and COUs - -The major differences between COUs and [CO Groups](https://spaces.at.internet2.edu/display/COmanage/CO+Groups+and+Group+Memberships) are - -* Any CO Person can create a CO Group; only CO Administrators can create COUs. -* CO Group Memberships attach at the CO Person level, whereas COU memberships attach at the CO Person Role level. -* Management of CO Group Memberships is simple (e.g., manual management by the CO Group Owner, self-opt in for open CO Groups, etc.), whereas COU memberships can be managed using [Enrollment Flows](https://spaces.at.internet2.edu/display/COmanage/Registry+Enrollment+Flow+Configuration) and [Expiration Policies](https://spaces.at.internet2.edu/display/COmanage/Expiration+Policies). -* COU memberships imply CO Group Memberships (in the _Members:COU group_). -* Email Addresses can be attached to CO Groups via [CO Email Lists](https://spaces.at.internet2.edu/display/COmanage/CO+Email+Lists). - -## About CO Groups - -COmanage Groups (CO Groups) are defined at the CO level, and CO Group Memberships attach to the CO Person. CO Groups are fairly basic, for more sophisticated needs COmanage can be connected to Grouper using the Grouper Provisioning Plugin. By default, any CO Person can create a new CO Group. - -## About CO Departments - -CO Departments are primary objects within Registry, which means that they are intended to store representations of external objects (just like CO People). CO Departments can attach to either a CO or a COU, and can be used to store a number of attributes about the department, including telephone numbers, email addresses, URLs, identifiers, and the sets of people associated with specific responsibilities within the department. CO Departments can be used to support various use cases: - -* In a VO deployment, CO Departments can be used to represent research groups. -* In an enterprise deployment, CO Departments can be used to represent the University department hierarchy. - -While there may typically be a one-to-one relationship between CO Departments and COUs, it is not strictly necessary. For example, a COU maybe made up of members spanning two departments. - -CO Departments are visible to anyone within the CO, by logging in to Registry, though only CO Administrators may edit their information. - -CO Departments are specifically intended to be used with [Registry Services](https://spaces.at.internet2.edu/display/COmanage/Registry+Services) and the Service Portal. - -## Comparison Summary - - | COU | CO Department | CO Group ----|-----|---------------|--------- -**Belongs To** | CO | CO; COU | CO; COU (for automatic groups only) -Has Many | CO Person Roles; CO Departments | |CO People (via CoGroupMember); CO Email List -HIerarchical | Yes | No ([CO-1523](https://bugs.internet2.edu/jira/browse/CO-1523)) | No ([CO-721](https://bugs.internet2.edu/jira/browse/CO-721)) -Object Type | Structural Object | Primary Registry Object | Primary Registry Object -Supported Attributes | None | Addresses; Email Addresses; Identifiers; Telephone Numbers; URLs; Leadership Group; Administrative Group; Support Group | Open / Closed; Managers (via CoGroupMember); Email Addresses (via CoEmailList); Identifiers (as of Registry v3.3.0) - -# Organizational Identities - - - -Also see [Organizational Identity Sources](https://spaces.at.internet2.edu/display/COmanage/Organizational+Identity+Sources) \ No newline at end of file diff --git a/_episodes/02-old-comanageRoles.md b/_episodes/02-old-comanageRoles.md deleted file mode 100644 index 421d0cc..0000000 --- a/_episodes/02-old-comanageRoles.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: "The Roles of COmanage" -teaching: 20 -exercises: 0 -questions: -- "Question here" -objectives: -- "List the objectives" -keypoints: -- "List the key takeaways for the episode" ---- - -# About People - -People are represented in COmanage by a CO Person object... - -See the table on the COmanage wiki for a [comparison chart of tasks](https://spaces.at.internet2.edu/display/COmanage/Roles) that each role can perform. - -## What can people do when they assume a role? - -COmanage uses roles to manage the functionality that different users can use. This functionality falls into the following broad categories: - -* **Collaborative Organization (CO) Management** - Management of the top-level object in COmanage. -* **Person Management** - The ability to add and edit the information about people in COmanage, and control their access to resources. -* **Role/ Group Management** - The ability to assign and adjust administrative roles and group membership -* **Provisioning** - Management of automated and manual provisioning - access to external resources -* **Content** - The ability to access certain types of COmanage content -* **Audit** - The ability to review and report on historical actions taken within COmanage -* **System Administration** - For the technical maintenance of COmanage - - NOTE: this list needs to be reconciled against the table of Registry Permissions](https://spaces.at.internet2.edu/display/COmanage/Registry+Permissions) - -## Administrator Roles - -COmanage Registry defines three types of administrators. - -### Platform (CMP) Administrators _(Also called Registry Admin in the documentation)_ - -Platform Administrators are effectively super users, with the ability to perform almost all operations on the platform. (Platform Administrators cannot execute enrollment flows for COs unless authorized by the enrollment flow.) - -Platform Administrators are configured by [adding the appropriate Organizational Identity](https://spaces.at.internet2.edu/display/COmanage/Default+Registry+Enrollment) to the COmanage CO, and then adding the corresponding person to the CO:admins group (v2.0.0 and later) or admin group (prior to v2.0.0) within the COmanage CO. - -The first user added as part of the [Registry Setup Script](https://spaces.at.internet2.edu/display/COmanage/Registry+Installation+-+Registry+Setup+Script) is automatically configured to be a Platform Administrator. - -### Collaboration (CO) Administrators - -Collaboration Administrators are super users _within a CO_. Collaboration Administrators are configured by adding the appropriate Organizational Identity to the CO (if not already done), and then adding the corresponding person to the CO:admins group (v2.0.0 and later) or admin group (prior to v2.0.0) within the CO. - -CO Administrators can manage any CO Group within their CO. - -### Unit (COU) Administrators - -Collaboration Administrators with sophisticated administrative requirements may optionally define Unit Administrators. Unit Administrators have limited privileges within the CO, generally related to the ability to enroll and manage populations within the CO Unit (COU). - -Unit Administrators are configured by adding the appropriate Organizational Identity to the CO (if not already done), and then adding the corresponding person to the _CO:COU:COU-Name:admins_ group (v2.0.0 and later) or _admin:COU-Name_ group (prior to v2.0.0) within the CO. - -COU Administrators can be defined for each COU, giving them the ability to perform lifecycle management operations on the CO People who have CO Person Roles associated with the COU that they manage (or any child COUs of that COU). - -### System Administrators - -System Administrators have privileges that enable them to maintain the COmanage application. These capabilities include the ability to provision cluster resources (for example, hardware, virtual machines, etc), Register and maintain IP Addresses, administer application upgrades, manage and conduct operating system upgrades and conduct backups. - -## Non-administrator roles - -### CO Participant - - - -### Guest - - - -### Group Owner - - - -### Group Member - - - -### CO Person - - - -### Anonymous - - - -### Sponsor - -Each [CO Person Role](https://spaces.at.internet2.edu/display/COmanage/Understanding+Registry+People+Types) can have a sponsor attached to it. The sponsor can be selected via an Enrollment Flow Attribute, or subsequently by manually editing the record. - -The pool of eligible sponsors can be configured via CO Settings as follows: - -CO Administrators -CO and COU Administrators -Members of a specified CO Group -Any valid CO Person -The sponsors capability may also be disabled. This may be advisable for deployments with large user populations, as disabling sponsors will reduce some database querying. - -If a sponsor subsequently becomes ineligible to be a sponsor, they will remain as sponsors for any existing records. However, they may not become sponsors of new records, and any existing record must specify a new sponsor if edited. - -Sponsor status may also be used in [Expiration Policies](https://spaces.at.internet2.edu/display/COmanage/Expiration+Policies). Note that expiration policies apply to the status of the sponsoring CO Person (ie: whether or not the CO Person is valid) and not to whether or not the CO Person is eligible to be a sponsor ([CO-1140](https://bugs.internet2.edu/jira/browse/CO-1140)). - -## Permissions - -Generally, Registry permissions are based on the type of user a person is. These types are generally based on group memberships, and include administrative users as well as non-administrative users. - -Permission | CMP Administrator | CO Administrator | COU Administrator | Group Owner | Group Member | CO Person | Anonymous ----------- | ----------------- | ---------------- | ----------------- | ----------- | ------------ | ------ | --------- -Configure COmanage platform | (tick) | | | | | | -Configure CO | (tick) | (tick) | | | | | -Start Enrollment | | (tick) | If configured | | If configured | If configured | If configured -Manage CO Person | (tick) | (tick) | (tick) within COU | | | See [Self Service Permissions](https://spaces.at.internet2.edu/display/COmanage/Self+Service+Permissions) -Create Group | (tick) | (tick) | | | | (tick) | -Manage Group | (tick) | (tick) | | (tick) | | | -Add Self To Open Group | | | | | | (tick) | -Remove Self From Group | | | | | (tick) | | - -## Managing Roles - -### CO Group Membership and Enrollment - -CO Group Memberships can be added as part of an [Enrollment Flow](https://spaces.at.internet2.edu/display/COmanage/Registry+Enrollment+Flow+Configuration) by adding an attribute of the appropriate type. For more details, see [Registry Enrollment Flow Configuration](https://spaces.at.internet2.edu/display/COmanage/Registry+Enrollment+Flow+Configuration). - -CO Group Memberships can also be added via [Organizational Identity Sources](https://spaces.at.internet2.edu/display/COmanage/Organizational+Identity+Sources) when connected to [Pipelines](https://spaces.at.internet2.edu/display/COmanage/Registry+Pipelines). - -### Making an existing member an administrator - ->> This needs to be vetted and screen shots are needed - -1. From the COmanage Registry home page, click on your CO. -2. From the CO welcome page, click on the drop down menu for 'People' and select 'My Population'. -3. Select the member that you would like to make into a CO admin. -4. On the member's page, click on 'Manage Group Memberships'. -5. Select 'member' on the admin group line. - -# CO Person and Person Role Status - -Each CO Person Role has a status attached to it, and each CO Person has an overall status that is generally calculated as the "most preferred" of the attached CO Person Role statuses. Statuses represent various states in the identity lifecycle, and various statuses have specific meanings within COmanage. - -Status can be changed under various circumstances: - -* As part of [Enrollment or Invitation](https://spaces.at.internet2.edu/display/COmanage/Understanding+Registry+Enrollment+and+Linking). -* As part of an [Organizational Identity Source](https://spaces.at.internet2.edu/display/COmanage/Organizational+Identity+Sources) and [Pipeline](https://spaces.at.internet2.edu/display/COmanage/Registry+Pipelines) sync. -* Due to an [Expiration Policy](https://spaces.at.internet2.edu/display/COmanage/Expiration+Policies). -* By updating CO Person Role validity dates. - * If a Role is in Pending status and the Valid From date is updated to be in the past, the Role will automatically change to Active status. - * If a Role is in Active status and the Valid From date is updated to be in the future, the Role will automatically change to Pending status. - * If a Role is in Expired status and the Valid Through date is updated to be in the future, the Role will automatically change to Active status. - * If a Role is in Active or Grace Period status and the Valid Through date is updated to be in the past, the Role will automatically change to Expired status. -* Manually. Note that manual changes will be overwritten when an automatic update would result in a different status. - -The status of a CO Person is generally calculated from the status of the CO Person Roles attached. This happens automatically under the following conditions: - -* When a CO Petition is approved/the Enrollee becomes active. -* When an Expiration Policy changes the status of a CO Person Role. -* When updating a CO Person Role Valid Through date causes the CO Person Role to become Active. -* When a Pipeline results in a status change. -* When a CO Person Role status is manually changed. - -The CO Person status is set to the "most preferred" status of the attached CO Person Roles. "Most preferred" is currently defined as the order in the table, below. In general, active statuses are most preferred, followed by expired statuses (since there may have been skeletal records provisioned that need to be maintained), followed by invitation statuses. - -CO Person and Person Role Records are passed to [Provisioners](https://spaces.at.internet2.edu/display/COmanage/Provisioning+From+Registry) based on their status, as indicated in the table, below. - -> This table is effective as of Registry v2.0.0. For earlier versions, see [this page](https://spaces.at.internet2.edu/pages/viewpage.action?pageId=107020614). - -> In Registry v2.x and v3.x, this table is only supported by certain provisioners (Ldap, Crowd, LdapServiceToken). ([CO-1740](https://todos.internet2.edu/browse/CO-1740)) - -Preference | Status | Description | Provisioning ------------| ------ | ----------- | ------------ -1 | Active | Person or Role is an active member in the CO | Person, Role, and Group data provisioned -2 | GracePeriod | Primary association with the CO has ended, but services have not yet been deprovisioned | Person, Role, and Group data provisioned -3 | Suspended | Association with the CO has been (manually) temporarily suspended | Person data and All Members Groups provisioned -4 | Expired | Valid through date has been reached | Person data and All Members Groups provisioned -5 | Approved | | No data provisioned -6 | PendingApproval | The enrollment flow petition is pending approval | No data provisioned -7 | Confirmed | | No data provisioned -8 | PendingConfirmation | An invitation or email confirmation was sent via an enrollment flow | No data provisioned -9 | Invited | An invitation was sent via default enrollment | No data provisioned -10 | Pending | | No data provisioned -11 | Denied | The enrollment flow petition was denied | No data provisioned -12 | Declined | The invitation sent via default enrollment was declined | No data provisioned -13 | Deleted | | No data provisioned -14 | Duplicate | The record is a duplicate of another | No data provisioned \ No newline at end of file diff --git a/_episodes/02-orgIdentity.md b/_episodes/02-orgIdentity.md index 28b2e61..048cf6d 100644 --- a/_episodes/02-orgIdentity.md +++ b/_episodes/02-orgIdentity.md @@ -1,7 +1,7 @@ --- title: "The OrgIdentity Object" -teaching: 20 -exercises: 0 +teaching: 15 +exercises: 10 questions: - "Question here" objectives: @@ -10,19 +10,118 @@ keypoints: - "List the key takeaways for the episode" --- +# 2. The OrgIdentity Object + +Because people in COmanage are represented by :gear: `CO Person` objects, it is helpful to link these objects to _external representations_ - representations of the person in other contexts outside of COmanage (including real life!) These representations include attributes and information about the person related to the other context. In COmanage, these external representations are captured in :gear: `Org Identity` objects, and are connected to _Sources_ or _Systems of Record_. + +The information stored in :gear: `Org Identity` objects typically includes + +* Link to :gear: `CO Person` object +* Status +* Personal information about the person + * Data of birth + * affiliation (eduPerson) + * source organization, department, & title +* Validity dates: from and through +* List of names - Same as for :gear: `CO Person` +* List of identifiers +* list of email addresses - Same as for :gear: `CO Person` +* list of physical addresses - Same as for :gear: `CO Person` + +This object also is connected to several other structural items that we will talk about in this lesson, including + +* **Source Information** - represented by an :gear: `Identity Source` object, this item contains details about how the source should be processed and the data gathered from the representation of the person at the source. +* **Cached Source Information** - represented by an :gear: `Identity Source Records` object, this item connects the :gear: `Identity Source` to the :gear: `Org Identity`, and is also used to cache data in COmanage from sources so that they are readily available. + +--- + +# About names, email addresses and physical addresses + +These lists of items are handled similarly to how they are used for :gear: `CO Person` objects. Because of their similarity, we won't review them in this section. # About identifiers -Organization Identities also use identifiers. two types - authentication vs +_< NOTE: Laura wrote this section, but isn't sure about her understanding of identifiers for Org Identity. The information here may be totally wrong. >_ + +:gear: `Org Identity` objects also use identifiers. The identifiers can be one of several different types + +* eppn: eduPersonPrincipalName +* eptid: eduPersonTargetedID +* mail: RFC 4524 +* openid: OpenID +* uid: RFC 4519 uidObject (previously userid) +* Or an extended type that is specific to the source related to the :gear: `Org Identity` + +## Identifiers for authentication + +Identifiers attached to :gear: `Org Identity` objects can potentially be used for signing into COmanage. A flag set on the identifier will indicate if it is used for sign in. + +--- + +Now we'll talk about sources - information from external systems - and how they are captured and used in COmanage. + +# The relationship between :gear: `Org Identity` objects and **sources** + +The :gear: `Org Identity` object is related to the source where its information came from. Often the source is from an external system, like LDAP, an authentication system, ORCID or even a CSV file. COmanage keeps track of this source for several reasons: + +* for auditing where information about a person came from +* for syncing with external systems to get the most up-to-date information +* to connect for performing actions that may happen outside of COmanage, for example, federated authentication. +* to provide information about the person provisioning access and privileges to external ("outbound") systems. + +COmanage has built-in capability to consume data and attributes from many of these sources, and can be extended to support additional sources. This information is managed through :gear: `Identity Source` objects and their COmanage-cached versions, :gear: `Identity Source Record` objects. + +Systems of Record (external sources) can be from anywhere. Common ones include LDAP servers, REST APIs, SQL databases, flat files, and so on. + +# Organizational Identity Sources - Supported sources + +There are several source types that are supported by COmanage: -Identifiers can be one of several different types +Source Type | Description +----------- | ----------- +Environment variables (Env) | Generally used to associate registered people with information and attributes generated by their use of web server authentication modules +CSV File data (File) | Used to associate registered people with information that may not be stored in a supported external system and can be provided by a CSV File +LDAP Server (LDAP) | Used to associate registered people with information from their representation on your LDAP server +ORCID Records (ORCID)| Used to associate registered people with information from their authenticated ORCID record via the ORCID API +NetForum Member Lists (netFORUM) | Used to associate registered people with information from their representation in your NetForum membership management system via the XML API (xWeb) +Salesforce (Salesforce) | Used to associate registered people with information from their representation in your Salesforce system via the Force.com REST API +API-based sources (API) | Used to associate registered people with information from other systems that can provide communication via a RESTful API (this plug in is experimental) -eppn: eduPersonPrincipalName -eptid: eduPersonTargetedID -mail: RFC 4524 -openid: OpenID -uid: RFC 4519 uidObject (previously userid) +> **Is your favorite source omitted from this list?** Not to worry! As with many features in COmanage, it is possible to extend the supported sources by creating a plug-in. We will learn more about plug-ins toward the end of the workshop. +# The Identity Source AND Identity Source Record Objects + +## :gear: Identity Source Object + +Source information, once gathered, is stored in :gear: `Identity Source` Objects. These objects contain details about how the source information should be processed and data gathered from the representation of the person at the source. + +The information stored in :gear: `Identity Source` objects typically includes: + +* **Descriptive information** - A description of the source, and its status +* **Processing information** - information about what information should be synced and under what conditions, what do if there is mis-matched information, how to handle this source when searching, and what to store when caching the source (for example, as a hash of the information or the full source record) +* **Connection information** - which source type is connected, and identifiers for the person used at the source + +In addition, specific data and attributes, customized for the source type, is attached to the :gear: `Identity Source` Object. + +## :gear: Identity Source Records Object + +Information from an :gear: `Identity Source` is connected to a :gear: `Org Identity` object via an :gear" `Org Identity Source Record` object. These objects are also used to cache data from sources so that they are readily available. + +In addition to the links to the related :gear: `Org Identity` and :gear" `Org Identity Source` objects, these objects also include information about when the data was last cached. + +--- + +# Hands on - Starting our person model + +![Interactive system activity](../assets/img/hands-on-keyboard.png) + +Think about the sources outside of COmanage where you store information about the people you may be registering. Use the individuals that you wrote down on the [ :memo: Modeling People](/files/handouts/CO310_ExamplePerson.pdf) worksheet to think of specific examples. + +In the **Org Identities** box, jot down one or more sources where there are representations for each of the people you have listed in the last exercise. All of the people you have listed may be represented in the same sources, or some may differ. Consider sources from systems, and also consider source like spreadsheet which may contain members of a project team. + +[10 min] + +--- # Terminology @@ -31,12 +130,24 @@ uid: RFC 4519 uidObject (previously userid) OBJECT | DESCRIPTION ------ | ----------- :gear: `Org Identity` | the representation of a person in other contexts outside of COmanage +:gear: `Identity Source` | Information about a person as obtained from an external source such as LDAP, netFORUM or ORCID. +:gear: `Identity Source Records` | COmanage's cached value of the values at the source + +## Worksheets + +WORKSHEET | DESCRIPTION +--------- | ----------- +[ :memo: Modeling People](/files/handouts/CO310_ExamplePerson.pdf) | Planning sheet used in this lesson for understanding how to model people in COmanage. This sheet is used to organize how specific people and their relationships would be expressed within COmanage + +## Slides + +To be included --- -NEXT SECTION: [About Attributes](/_episodes/03-attributes.md) +NEXT SECTION: [3. About Attributes](/_episodes/03-attributes.md) -PREVIOUS SECTION: [The CO Person Object](/_episodes/01-COperson.md) +PREVIOUS SECTION: [1. The CO Person Object](/_episodes/01-COperson.md) LESSON OVERVIEW: [CO310 - Modeling People in COmanage](../index.md) diff --git a/_episodes/03-attributes.md b/_episodes/03-attributes.md new file mode 100644 index 0000000..81b419b --- /dev/null +++ b/_episodes/03-attributes.md @@ -0,0 +1,186 @@ +--- +title: "About Attributes" +teaching: 15 +exercises: 10 +questions: +- "Question here" +objectives: +- "List the objectives" +keypoints: +- "List the key takeaways for the episode" +--- + +# 3. About Attributes + +< LDP NOTE - I don't know what the general information that one would need to know about attributes and how they related to CO Person and Org Identity objects. At this point in the workshop, the user will not know about enrollments or provisioning yet. If these are the only purposes for attributes, it may be better to just leave out their mention here, and bring them up later. Sources are covered in 02-orgIdentity.md > + +An Enrollment Flow can be thought of as a process for assembling attributes about a person and storing them in records used for day to day operations. Generally speaking, any attribute that can be managed operationally by COmanage Registry (whether attached to a CO Person, a CO Person Role, or an Organizational Identity) can be collected as part of an Enrollment Flow. + +## Required attributes + +The following attributes must be defined for a "complete" enrollment. While it is possible to make these attributes optional or unspecified, it is recommended that you not do so because they are needed for a complete enrollment. + +* COU, if COUs are enabled, and if a new CO Person Role is being created (eg: not needed for account linking) +* Org Identity Name - Exactly one Org Identity Name of type `Official` must be specified. +* CO Person Name - Exactly one CO Person Name of type `Official` must be specified. The CO person Name may be copied from the Org Identity value.) +* Org Identity Email Address +* CO Person Role Affiliation, if a new CO Person Role is being created (eg: not needed for account linking) +* Authenticated identifiers - this field is automatically added if authentication is enabled if not already part of the record. +* See also Configuring Registry Identifier Assignment (no need to explicitly define an attribute for this) +* See also Registry Platform Configuration + +## Collecting attributes + +Attributes can be collected from authoritative sources in several ways. These attributes can be used in COmanage in several ways: + +* to create Organizational Identities that are linked to an external source or "system of record" +* to populate default values during enrollment +* To set COmangage Platform (CMP) enrollment attributes +* to collect an authenticated identifier + +Some models for collecting these attributes include + +* [collection from Web Service environment variables](https://spaces.at.internet2.edu/display/COmanage/Consuming+External+Attributes+via+Web+Server+Environment+Variables) - A typical deployment pattern includes the collection of authoritative attributes provided from an external source, typically via a SAML or OIDC assertion, which are then passed to Registry via web server environment variables. +* through email confirmation and authentication +* [through organizational identity sources](https://spaces.at.internet2.edu/display/COmanage/Organizational+Identity+Sources) + +> not sure where this fits [Managing Apache Web Server Environment Variables](https://spaces.at.internet2.edu/display/COmanage/Managing+Apache+Web+Server+Environment+Variables) + +## Default values for Attributes + +Certain attributes configured as part of an Enrollment Flow can be assigned default values. When a Petition is created from the Enrollment Flow, the default values are pre-populated into the form. Default values can also be flagged as not modifiable, in which case the value loaded into the Petition cannot be changed by the Petitioner. + +Currently, the following types of attributes may have default values assigned: + +* Single valued Organizational Identity attributes (basically, those defined in [cm_org_identities](https://spaces.at.internet2.edu/display/COmanage/cm_org_identities)) +* Single valued CO Person Role attributes (basically, those defined in [cm_co_person_roles](https://spaces.at.internet2.edu/display/COmanage/cm_co_person_roles)) +* [Extended Attributes](https://spaces.at.internet2.edu/display/COmanage/Extending+the+Registry+Data+Model#ExtendingtheRegistryDataModel-ExtendingtheRegistryDataModel-ExtendedAttributes) (attributes that you have added to extend the data model) +* CO Group Memberships + * An Enrollee can only be added to a CO Group as a member ("CO Group Member"), and/or an owner ("CO Group Member and Owner"). For "CO Group Member and Owner", the Enrollee will be added as both a member and an owner, except for opt-in groups as described below + * By setting the default value to be not modifiable, the associated CO Group is fixed; otherwise a Petitioner can add the Enrollee to any available CO Group + * By setting a default value, flagging it as not modifiable, not hidden, and optional, the CO Group becomes opt-in (by the petitioner). For "CO Group Member and Owner", either or both roles may be selected for opt-in + +If the selected attribute has Attribute Enumerations defined for it, the default value can only be chosen from one of the enumerated options. + +Attributes that represent dates can receive default values based on + +* A fixed date (eg: June 30, 2013) +* The next occurrence of a date (eg: next June 30) +* A specific number of days from the creation of the petition (eg: in 90 days) + +In addition, if the Enrollment Flow is configured for Self matching (described below), the Petitioner's name will be pre-populated into the Organizational Identity name fields. + +## Attributes managed directly by users (self-service permissions) + +COmanage Registry allows certain attributes to be managed by users directly, via the Identity menu accessible from the top menu bar (the gear icon with the user's name). + +### Attributes Always Available For Self Service + +* CO Person NSF Demographic attributes +* CO Group Memberships (for open groups or groups owned by the CO Person) +* SSH Keys attached to a CO Person record +* CO Person Preferred Timezone (as of v1.0.0; requires logout to take effect) + +### Attributes That May Be Configured For Self Service + +* CO Person Name +* CO Person Role Address +* CO Person EmailAddress +* CO Person Role TelephoneNumber +* CO Person Identifier (as of v3.1.0) +* CO Person URL (as of v3.1.0) + +By default, these attributes are read only. To change these permissions, add a new Self Service Permission (Collaborations >> Co >> Configuration >> Self Service Permissions). Permissions may be granted on a per-Attribute (default) basis, or on a per-Attribute-per-Type basis. If permission is set to None, the user will not be able to see the current value of the matching attribute. + +> Prior to Registry v3.1.0, users can only add a new attribute when any type is permitted. ie: It is not possible to allow a user to add only (say) a preferred name, and not an official name. (CO-1254) + +### Attributes Never Available For Self Service + +* CO Person Status +* CO Person Identifiers (prior to v3.1.0) +* CO Person Role attributes, including Extended Attributes +* All attributes attached to an Organizational Identity record + +## Attribute Release for COmanage Services + +To access either the COmanage Registry or the associated collaboration tools, a user's Identity Provider (IdP) must release the eduPersonPrincipleName (ePPN) attribute to the collaboration platform. Ask your IdP's administrative contact either to support the [REFEDS Research & Scholarship entity category](https://refeds.org/category/research-and-scholarship/) (most preferred) or to release ePPN directly to the Registry and associated applications. + +To support the R&S entity category, an IdP has to perform a few simple tasks. Alternatively, to release ePPN directly to the Registry and Wiki, an IdP should follow the instructions below. + +The following is an example of the configuration that the staff managing an institutional Identity Provider would need to add to the "attribute-filter.xml" Shibboleth IdP configuration file in order to release the needed attribute (ePPN). There are actually two examples, one that just releases ePPN, and a second one that releases ePPN plus some additional attributes that would be useful to improve the user experience within the platform, if your institution is so willing. (As noted before, if your institution already releases attributes to any service that has been approved to be in the "entity category" of Research & Scholarship, nothing more is needed – none of this additional configuration is required.) + +**Minimally needed attribute release for accessing a collaboration services/environment for the MFA Cohortium Collaboration:** (what is "cohortium"? or is this a typo?) + +``` +* + + + + + +```` + +OR the following (required plus optional useful attributes): + +```` + + + + + + + + + + + + + +```` + +--- + +# Hands on - Starting our person model + +![Interactive system activity](../assets/img/hands-on-keyboard.png) + +< TO BE UPDATED > + +Think about the sources outside of COmanage where you store information about the people you may be registering. Use the individuals that you wrote down on the [ :memo: Modeling People](/files/handouts/CO310_ExamplePerson.pdf) worksheet to think of specific examples. + +In the **Org Identities** box, jot down one or more sources where there are representations for each of the people you have listed in the last exercise. All of the people you have listed may be represented in the same sources, or some may differ. Consider sources from systems, and also consider source like spreadsheet which may contain members of a project team. + +[10 min] + +--- +< TO BE UPDATED > + +# Terminology + +## COmanage Objects + +OBJECT | DESCRIPTION +------ | ----------- +:gear: `Org Identity` | the representation of a person in other contexts outside of COmanage +:gear: `Identity Source` | Information about a person as obtained from an external source such as LDAP, netFORUM or ORCID. +:gear: `Identity Source Records` | COmanage's cached value of the values at the source + +## Worksheets + +WORKSHEET | DESCRIPTION +--------- | ----------- +[ :memo: Modeling People](/files/handouts/CO310_ExamplePerson.pdf) | Planning sheet used in this lesson for understanding how to model people in COmanage. This sheet is used to organize how specific people and their relationships would be expressed within COmanage + +## Slides + +To be included + +--- + +NEXT SECTION: [4. About Authenticators](/_episodes/04-authenticators.md) + +PREVIOUS SECTION: [2. The OrgIdentity Object](/_episodes/02-orgIdentity.md) + +LESSON OVERVIEW: [CO310 - Modeling People in COmanage](../index.md) + +WORKSHOP OVERVIEW: [COmanage Workshop: Managing Identities & Collaborations](https://github.internet2.edu/lpaglione/COmg-trainingOverview/blob/master/README.md) \ No newline at end of file diff --git a/_episodes/03-old-comanageGroups.md b/_episodes/03-old-comanageGroups.md deleted file mode 100644 index ab3c5cc..0000000 --- a/_episodes/03-old-comanageGroups.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: "How & Why to Create Groups" -teaching: 20 -exercises: 0 -questions: -- "Question here" -objectives: -- "List the objectives" -keypoints: -- "List the key takeaways for the episode" ---- - -# Plan your groups - -## Why you want to use groups - -Groups are used for a variety of reasons, but generally they are used to manage permissions and access, or to manage contact lists. COmanage handles basic groups; for more complex group structures, Grouper integration is required. - -COmanage Groups (CO Groups) are defined at the CO level, and CO Group Memberships attach to the [CO Person](https://spaces.at.internet2.edu/display/COmanage/Understanding+Registry+People+Types). CO Groups are fairly basic, for more sophisticated needs COmanage can be connected to [Grouper](http://grouper.internet2.edu/) using the [Grouper Provisioning Plugin](https://spaces.at.internet2.edu/display/COmanage/Grouper+Provisioning+Plugin). By default, any CO Person can create a new CO Group. - -## What you need to consider - -CO Groups provide basic group functionality enabling actions to be applied to all members of the group at the same time, for example, granting access to an application, joining a mailing list, or expiring membership at the same time. - -Some will require more sophisticated group management than what is available in COmanage. For these needs, COmanage can be connected to [Grouper](http://grouper.internet2.edu/) using the [Grouper Provisioning Plugin](https://spaces.at.internet2.edu/display/COmanage/Grouper+Provisioning+Plugin). - -# Implement a group! - -// NOTE: this section needs to be confirmed & screen shots added. - - -## Create a Group - -![Interactive system activity](../assets/img/hands-on-keyboard.png) - -**REQUIRED ROLE**: Platform Administrator (or maybe this is "Any CO Person?", at least by default.) - -// NOTE: this section needs to be confirmed & screen shots added. - -1. Login to the COmanage Registry and select your CO from the list. -2. Select 'All Groups' from the Group drop-down menu. -3. On the Groups page, select 'Add Groups', located above the Groups table. -4. Fill in the fields: - a. **The name of your Group.** This name will be displayed when your group is referenced. It is a good idea for this name to be descriptive, but relatively short. - b. **Description.** Write a short description of your group. This description will be helpful to users and future administrators to understand the purpose of the group. - c. **Open.** This is a check box to indicate whether anyone can join, or if users may only be added by the group owner. An open group is one that allows anyone to join. Participants can self-join, no administrator action is required. Memberships in a closed group can only be set by the group owner. - c. **Status.** There are three choices for the status: - * Active - you will select this one. Your group will be immediately active upon its creation. - * Suspended - Useful if you are not ready for your group to be active. -5. Click 'Add'. - -## Group Attributes - -### Open vs Closed - -An _open_ group is one that allows anyone to join. Participants can self-join, no administrator action is required. Memberships in a _closed_ group can only be set by the group owner. - -In addition, CO Administrators can manage any CO Group within their CO. - -### Automatic Groups - -_Automatic Groups_ are those which Registry automatically manages the memberships of. - -# Group Members - -A group member is simply a participant in the group. A group owner has permission to add and remove members to and from the group, including closed groups. A CO Person can be a member, and owner, both, or neither. - -The CO Person who creates a CO Group is automatically set as both a member and owner of the new group. - -## Add a Group Member - -There are several ways to add individuals to groups. This may be done as part of the enrollment process, or it may be done after enrollment is complete and the individuals are already in the Registry. The instructions below assume enrollment has been completed and the individual is being added by a CO administrator to a new group. - -1. Login to the COmanage Registry (if you haven't already) and select your CO from the list. -2. Select 'My Population' from the People drop-down menu. -3. Select a user and click on 'Manage Group Memberships'. This will show a list of available groups and you can add the individual as a group member or as a group owner by clicking on the appropriate box in the 'Actions' column. -4. Click 'Save'. - -## Using Enrollment flows for CO Group Memberships - -CO Group Memberships can be added as part of an [Enrollment Flow](https://spaces.at.internet2.edu/display/COmanage/Registry+Enrollment+Flow+Configuration) by adding an attribute of the appropriate type. For more details, see [Registry Enrollment Flow Configuration](https://spaces.at.internet2.edu/display/COmanage/Registry+Enrollment+Flow+Configuration). - -CO Group Memberships can also be added via [Organizational Identity Sources](https://spaces.at.internet2.edu/display/COmanage/Organizational+Identity+Sources) when connected to [Pipelines](https://spaces.at.internet2.edu/display/COmanage/Registry+Pipelines). - -## Nested Group membership - -As of Registry v3.3.0, Nested Groups allow the members of one group (the "nested" or source group) to automatically be included as members of another group (the "target" group). Nested Groups only confer group membership, they cannot be used to manage group ownership. Currently, Nested Groups are additive only, it is not possible to specify certain members to be excluded from the target group ([CO-1585](https://bugs.internet2.edu/jira/browse/CO-1585)). - -To nest a group, edit the target group and click **Add Nested Group**. Select the desired source group. Currently, only CO and COU admins can create or remove nestings. - -Nested Groups do not imply any sort of hierarchy ([CO-1223](https://bugs.internet2.edu/jira/browse/CO-1223)). - -> Nested Groups are not designed to scale to very large groups, and in particular manual reconciliation of a very large group with one or more Nested Groups may be problematic. The exact threshold will vary according to the specifics of a given deployment. Deployments experiencing problems reconciling large groups may wish to consider a solution such as [Grouper](http://grouper.internet2.edu/). - -## Remove a Group Member - -There are several ways to remove an individual from group membership, either by managing that individual directly (follow the directions for Adding a Group Member and click on the appropriate box to de-select that entry) or by managing the group as a whole. The instructions below assume direct group management instead of per-individual management. - -1. Login to the COmanage Registry (if you haven't already) and select your CO from the list. -2. Select 'My Groups' from the Group drop-down menu. -3. Select the group you are changing (note that you must be an owner of that group to adjust membership). -4. Click on 'Delete' for each member you are removing from the group, and 'Remove' from the verification pop-up. - -As of v3.1.0, it is possible for a CO Person to add or remove themselves from the CO Group associated with a Service directly from the Service Portal, using the _Join_ and _Leave_ buttons. Using _Join_ and _Leave_ is functionally equivalent to navigating to My Groups, finding the appropriate group, and ticking the Member button. This is only available when the CO Group associated with a Service is an open group. - -> Administrators cannot use this interface on behalf of a CO Person, but must instead use the regular group management interfaces. - -## Reconciling group memberships - -In general, nested group memberships and memberships of automatic groups are updated in real time as needed. However, If an automatic group or a group with nested groups appears to have incorrect group memberships, the group may be manually reconciled to fix incorrect memberships. To reconcile a group, edit the desired group and click **Reconcile**. - -Manually reconciling a group will not automatically reconcile related groups. For example, if Group A has nested Group B which in turn has nested Group C, and Group C is manually reconciled, it will probably be necessary to also manually reconcile Group B. - -## CO Group Membership Attributes - -### Member vs Owner - -A group member is simply a participant in the group. A group owner has permission to add and remove members to and from the group, including closed groups. A CO Person can be a member, and owner, both, or neither. - -The CO Person who creates a CO Group is automatically set as both a member and owner of the new group. \ No newline at end of file diff --git a/_episodes/04-authenticators.md b/_episodes/04-authenticators.md new file mode 100644 index 0000000..c52f544 --- /dev/null +++ b/_episodes/04-authenticators.md @@ -0,0 +1,137 @@ +--- +title: "About Authenticators" +teaching: 15 +exercises: 10 +questions: +- "Question here" +objectives: +- "List the objectives" +keypoints: +- "List the key takeaways for the episode" +--- + +# 4. About Authenticators + +< This episode needs to be edited > + +Authenticators are used to prove a CO Person's identity to an application or service. An Authenticator combined with an Identifier is a credential. Although COmanage is built around the concept of external identity, there are a number of use cases where it makes sense for collaboration managed credentials to be used to access services, including + +* Using SSH Keys ([CO-1493](https://bugs.internet2.edu/jira/browse/CO-1493)) or Passwords to log in to unix based servers. +* Certificate access to grid computing resources. +* Multi factor authentication, using a collaboration issued second factor. + +Authenticators are available as of registry v3.1.0. + +## Terminology + +There are multiple concepts with similar names. For clarity, here are their definitions: + +* **Authenticator Plugin**: A [COmanage Plugin](https://spaces.at.internet2.edu/display/COmanage/Authenticator+Plugins), that implements the interfaces to a specific authentication technology (such as Passwords or SSH Keys). +* **Authenticator Backend**: An [instantiated](https://spaces.at.internet2.edu/display/COmanage/Writing+Registry+Plugins#WritingRegistryPlugins-WritingRegistryPlugins-InstantiatedvsNon-Instantiated) Authenticator Plugin. That is, an Authenticator Plugin with a specific configuration. +* **Authenticator**: A specific instance of an authenticator attached to a CO Person. eg: A given person's password. + +## How Authenticators Work + +Because Authenticators are collaboration issued, they are attached to the CO Person, not to Organizational Identities (as for [external credentials](https://spaces.at.internet2.edu/display/COmanage/Understanding+Registry+People+Types)). In general, Registry does not know how to validate Authenticators, they (or metadata about them) are simply stored in the Registry database. Authenticators are passed to the [provisioning infrastructure](https://spaces.at.internet2.edu/display/COmanage/Provisioning+From+Registry), so that [Provisioning Plugins](https://spaces.at.internet2.edu/display/COmanage/Writing+Registry+Plugins) may use the Authenticator information to populate downstream services. For example, the [LDAP Provisioner Plugin](https://spaces.at.internet2.edu/display/COmanage/LDAP+Provisioning+Plugin) may write a user password or SSH key attribute using Authenticator data. + +### Single vs Multiple Values + +Authenticator Backends can support single or multiple values, as determined by the Authenticator Plugin. In general, whether an Authenticator Plugin supports multiple values depends on whether it makes sense for the CO Person to be able to manage multiple Authenticators of the same type for themselves. + +For example, the [Password Authenticator Plugin](https://spaces.at.internet2.edu/display/COmanage/Password+Authenticator+Plugin) is single valued, meaning each instantiated backend may only have one password associated with it. (A given PasswordAuthenticator hasOne Password per CO Person.) If you want to support multiple passwords to be managed, you can instantiate multiple Backends. A CO Person cannot create a second password for themselves. + +On the other hand, the Certificate Authenticator Plugin is multi-valued, meaning each instantiated backend may support multiple certificates. (A given CertificateAuthenticator hasMany Certificate per CO Person.) This allows a CO Person to upload multiple certificates to attach to their operational record. (In general, there is no need to multiply instantiate an Authenticator Plugin that supports multiple values, although it is technically possible to do so.) + +## Authenticator Operations + +Registry supports the following operations on Authenticators for a CO Person: + +* **Manage**: Set or change the current Authenticator (for example, change a password). This operation may be performed by the CO Person (self service) or an administrator. +* **Lock**: Lock the Authenticator so it may not be changed or used. When locked, the Authenticator is not available to provisioners. This operation may only be performed by an administrator. For Authenticator Backends that support multiple values, locking applies to the entire Authenticator Backend (ie: all Authenticators for the CO Person, including the ability to add new ones). +* **Unlock**: Unlock the Authenticator so it may again be changed or used. If previously set, the original value will be maintained. This operation may only be performed by an administrator. For Authenticator Backends that support multiple values, unlocking applies to the entire Authenticator Backend. +* **Reset**: Clear the current Authenticator. This operation may only be performed by an administrator. Once reset, the CO Person may again manage the authenticator (if it is not locked). This operation is not supported for Authenticator Backends that support multiple values, although individual values maybe edited or deleted. + +Upon any operation, the provisioning infrastructure is executed so that the Provisioners may perform any necessary actions. Authenticators may be manually reprovisioned by the usual [manual reprovisioning process](https://spaces.at.internet2.edu/display/COmanage/Provisioning+From+Registry#ProvisioningFromRegistry-ProvisioningFromRegistry-ManualProvisioning). + +As of Registry v3.3.0, Authenticators may be collected as part of an [Enrollment Flow](https://spaces.at.internet2.edu/display/COmanage/Registry+Enrollment+Flow+Configuration#RegistryEnrollmentFlowConfiguration-RegistryEnrollmentFlowConfiguration-EstablishingAuthenticators). + +## Using Authenticators To Log Into Registry + +Because Authenticators are attached to the CO Person, not to Organizational Identities, and because Registry does not know how to validate Authenticators, they cannot be directly used to log into Registry. The following additional steps are necessary: + +1. Set up an authentication service (eg: [Shibboleth](http://shibboleth.net/products/identity-provider.html), [CAS](https://www.apereo.org/projects/cas), or [mod_authnz_ldap](https://httpd.apache.org/docs/2.4/mod/mod_authnz_ldap.html)) that allows for web based authentication using the Authenticators as provisioned to a suitable target (such as LDAP), and configure [Apache to use this authentication service](https://spaces.at.internet2.edu/display/COmanage/Registry+Installation+-+Source#RegistryInstallation-Source-RegistryInstallation-Source-IntegrateWebServerAuthentication) for Registry. +2. For each CO Person, create an Org Identity (or use an existing one) with an attached Identifier flagged for login. + +# Specific Authentication Services + +## Shibboleth + +### Configuring the Shibboleth Embedded Discovery Service Plugin + +> For configuration instructions for COmanage Registry v0.9.4 and earlier, see [Configuring the Shibboleth Embedded Discovery Service Plugin (0.9.x)](https://spaces.at.internet2.edu/pages/viewpage.action?pageId=68485126). + +If you have chosen to use a SAML2 service provider (SP) for authentication to the Registry and you expect users to want to use more than one login server (identity provider or IdP), you will most likely want to use a SAML2 discovery service to help users choose which IdP to use for login. + +COmanage Registry includes a Shibboleth Embedded Discovery Service (EDS) that you may choose to use as the discovery service. Customization is via _Platform > CMP Enrollment Configurations_. The default COmanage EDS assumes the discovery service feed is available at /Shibboleth.sso/DiscoFeed. For more information on the EDS, see the [EDS documentation](https://wiki.shibboleth.net/confluence/display/EDS10/Embedded+Discovery+Service). + +The discovery service URL is + +``` +https:///registry/pages/eds/index +``` + +If you are using a Shibboleth Native Service Provider (SP) you can configure the SP to use the discovery service by configuring the discoveryProtocol and discoveryURL attributes for the element. For example + +``` + +SAML2 + +``` + + +--- + +# Hands on - Starting our person model + +![Interactive system activity](../assets/img/hands-on-keyboard.png) + +< TO BE UPDATED> + +Think about the sources outside of COmanage where you store information about the people you may be registering. Use the individuals that you wrote down on the [ :memo: Modeling People](/files/handouts/CO310_ExamplePerson.pdf) worksheet to think of specific examples. + +In the **Org Identities** box, jot down one or more sources where there are representations for each of the people you have listed in the last exercise. All of the people you have listed may be represented in the same sources, or some may differ. Consider sources from systems, and also consider source like spreadsheet which may contain members of a project team. + +[10 min] + +--- +< TO BE UPDATED > + +# Terminology + +## COmanage Objects + +OBJECT | DESCRIPTION +------ | ----------- +:gear: `Org Identity` | the representation of a person in other contexts outside of COmanage +:gear: `Identity Source` | Information about a person as obtained from an external source such as LDAP, netFORUM or ORCID. +:gear: `Identity Source Records` | COmanage's cached value of the values at the source + +## Worksheets + +WORKSHEET | DESCRIPTION +--------- | ----------- +[ :memo: Modeling People](/files/handouts/CO310_ExamplePerson.pdf) | Planning sheet used in this lesson for understanding how to model people in COmanage. This sheet is used to organize how specific people and their relationships would be expressed within COmanage + +## Slides + +To be included + +--- + +NEXT SECTION: [5. About Roles](/_episodes/05-roles.md) + +PREVIOUS SECTION: [3. About Attributes](/_episodes/03-attributes.md) + +LESSON OVERVIEW: [CO310 - Modeling People in COmanage](../index.md) + +WORKSHOP OVERVIEW: [COmanage Workshop: Managing Identities & Collaborations](https://github.internet2.edu/lpaglione/COmg-trainingOverview/blob/master/README.md) \ No newline at end of file diff --git a/_episodes/04-old-specialGroups.md b/_episodes/04-old-specialGroups.md deleted file mode 100644 index 0106591..0000000 --- a/_episodes/04-old-specialGroups.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: "Special Groups in COmanage" -teaching: 20 -exercises: 0 -questions: -- "Question here" -objectives: -- "List the objectives" -keypoints: -- "List the key takeaways for the episode" ---- - -## Admin Groups - -Admin Groups are used to determine [Registry Administrators](https://spaces.at.internet2.edu/display/COmanage/Registry+Administrators). Admin Groups are automatically created when a CO or COU is created. The Platform Administrator typically sets the initial CO Administrator, and then the CO Administrators. - -Since v2.0.0: - -* The admin group is indicated by the group type GroupEnum::Admins and a null cou_id. The default name for the group is CO:admins. -* The admin groups for COUs are indicated by the group type GroupEnum::Admins and a non-null cou_id. The default name for COU admin groups is CO:COU:COU_Name:admins. - -Prior to v2.0.0: - -* The admin group determines CO Administrators. -* Groups of the form admin:couname determine COU Administrators. - -## Members Groups - -Members Groups are automatic groups that are updated with all members of the CO or COU. Members Groups are automatically created and updated. - -Since v2.0.0: - -* Members of the CO in Active or Grace Period status are available in the group identified by the group type GroupEnum::ActiveMembers and a null cou_id. The default name for the group is CO:members:active. -* All members of the CO (except those in Deleted status) are available in the group identified by the group type GroupEnum::AllMembers and a null cou_id. The default name for the group is CO:members:all. -* Members of a given COU with an Active or Grace Period status role are available in the group identified by the group type GroupEnum::ActiveMembers and a non-null cou_id. The default name for the group is CO:COU:COU_Name:members:active. -* All members of a given COU (except those with only roles in Deleted status) are available in the group identified by the group type GroupEnum::AllMembers and a non-null cou_id. The default name for the group is CO:COU:COU_Name:members:all. - -Prior to v2.0.0: - -* The members group holds all CO People within the CO. -* Groups of the form members:couname hold all CO People with a role in the specified COU. \ No newline at end of file diff --git a/_episodes/05-roles.md b/_episodes/05-roles.md index a74ea53..1c9feee 100644 --- a/_episodes/05-roles.md +++ b/_episodes/05-roles.md @@ -10,6 +10,122 @@ keypoints: - "List the key takeaways for the episode" --- +## Managing Roles + +See the table on the COmanage wiki for a [comparison chart of tasks](https://spaces.at.internet2.edu/display/COmanage/Roles) that each role can perform. + +## What can people do when they assume a role? + +COmanage uses roles to manage the functionality that different users can use. This functionality falls into the following broad categories: + +* **Collaborative Organization (CO) Management** - Management of the top-level object in COmanage. +* **Person Management** - The ability to add and edit the information about people in COmanage, and control their access to resources. +* **Role/ Group Management** - The ability to assign and adjust administrative roles and group membership +* **Provisioning** - Management of automated and manual provisioning - access to external resources +* **Content** - The ability to access certain types of COmanage content +* **Audit** - The ability to review and report on historical actions taken within COmanage +* **System Administration** - For the technical maintenance of COmanage + + NOTE: this list needs to be reconciled against the table of Registry Permissions](https://spaces.at.internet2.edu/display/COmanage/Registry+Permissions) + +## Administrator Roles + +COmanage Registry defines three types of administrators. + +### Platform (CMP) Administrators _(Also called Registry Admin in the documentation)_ + +Platform Administrators are effectively super users, with the ability to perform almost all operations on the platform. (Platform Administrators cannot execute enrollment flows for COs unless authorized by the enrollment flow.) + +Platform Administrators are configured by [adding the appropriate Organizational Identity](https://spaces.at.internet2.edu/display/COmanage/Default+Registry+Enrollment) to the COmanage CO, and then adding the corresponding person to the CO:admins group (v2.0.0 and later) or admin group (prior to v2.0.0) within the COmanage CO. + +The first user added as part of the [Registry Setup Script](https://spaces.at.internet2.edu/display/COmanage/Registry+Installation+-+Registry+Setup+Script) is automatically configured to be a Platform Administrator. + +### Collaboration (CO) Administrators + +Collaboration Administrators are super users _within a CO_. Collaboration Administrators are configured by adding the appropriate Organizational Identity to the CO (if not already done), and then adding the corresponding person to the CO:admins group (v2.0.0 and later) or admin group (prior to v2.0.0) within the CO. + +CO Administrators can manage any CO Group within their CO. + +### Unit (COU) Administrators + +Collaboration Administrators with sophisticated administrative requirements may optionally define Unit Administrators. Unit Administrators have limited privileges within the CO, generally related to the ability to enroll and manage populations within the CO Unit (COU). + +Unit Administrators are configured by adding the appropriate Organizational Identity to the CO (if not already done), and then adding the corresponding person to the _CO:COU:COU-Name:admins_ group (v2.0.0 and later) or _admin:COU-Name_ group (prior to v2.0.0) within the CO. + +COU Administrators can be defined for each COU, giving them the ability to perform lifecycle management operations on the CO People who have CO Person Roles associated with the COU that they manage (or any child COUs of that COU). + +### System Administrators + +System Administrators have privileges that enable them to maintain the COmanage application. These capabilities include the ability to provision cluster resources (for example, hardware, virtual machines, etc), Register and maintain IP Addresses, administer application upgrades, manage and conduct operating system upgrades and conduct backups. + +### Making an existing member an administrator + +>> This needs to be vetted and screen shots are needed + +1. From the COmanage Registry home page, click on your CO. +2. From the CO welcome page, click on the drop down menu for 'People' and select 'My Population'. +3. Select the member that you would like to make into a CO admin. +4. On the member's page, click on 'Manage Group Memberships'. +5. Select 'member' on the admin group line. + +## Non-administrator roles + +### CO Participant + + + +### Guest + + + +### Group Owner + + + +### Group Member + + + +### CO Person + + + +### Anonymous + + + +### Sponsor + +Each [CO Person Role](https://spaces.at.internet2.edu/display/COmanage/Understanding+Registry+People+Types) can have a sponsor attached to it. The sponsor can be selected via an Enrollment Flow Attribute, or subsequently by manually editing the record. + +The pool of eligible sponsors can be configured via CO Settings as follows: + +CO Administrators +CO and COU Administrators +Members of a specified CO Group +Any valid CO Person +The sponsors capability may also be disabled. This may be advisable for deployments with large user populations, as disabling sponsors will reduce some database querying. + +If a sponsor subsequently becomes ineligible to be a sponsor, they will remain as sponsors for any existing records. However, they may not become sponsors of new records, and any existing record must specify a new sponsor if edited. + +Sponsor status may also be used in [Expiration Policies](https://spaces.at.internet2.edu/display/COmanage/Expiration+Policies). Note that expiration policies apply to the status of the sponsoring CO Person (ie: whether or not the CO Person is valid) and not to whether or not the CO Person is eligible to be a sponsor ([CO-1140](https://bugs.internet2.edu/jira/browse/CO-1140)). + +## Permissions + +Generally, Registry permissions are based on the type of user a person is. These types are generally based on group memberships, and include administrative users as well as non-administrative users. + +Permission | CMP Administrator | CO Administrator | COU Administrator | Group Owner | Group Member | CO Person | Anonymous +---------- | ----------------- | ---------------- | ----------------- | ----------- | ------------ | ------ | --------- +Configure COmanage platform | (tick) | | | | | | +Configure CO | (tick) | (tick) | | | | | +Start Enrollment | | (tick) | If configured | | If configured | If configured | If configured +Manage CO Person | (tick) | (tick) | (tick) within COU | | | See [Self Service Permissions](https://spaces.at.internet2.edu/display/COmanage/Self+Service+Permissions) +Create Group | (tick) | (tick) | | | | (tick) | +Manage Group | (tick) | (tick) | | (tick) | | | +Add Self To Open Group | | | | | | (tick) | +Remove Self From Group | | | | | (tick) | | + + # CO Person Role Status As with the :gear: `CO Person` object, each :gear: `CO Person Role` object diff --git a/_episodes/08-youTryFirstPerson.md b/_episodes/08-youTryFirstPerson.md new file mode 100644 index 0000000..d4da76d --- /dev/null +++ b/_episodes/08-youTryFirstPerson.md @@ -0,0 +1,22 @@ +--- +title: "Your first person" +teaching: 15 +exercises: 10 +questions: +- "Question here" +objectives: +- "List the objectives" +keypoints: +- "List the key takeaways for the episode" +--- + +# Managing Organizational Identity Source Records + +The terminology used by Registry can be a little confusing when looking at person records related to Organizational Identity Sources. + +* **View Organizational Identity**: Retrieves the current Org Identity operational record used by Registry in normal operations. +* **View Organizational Identity Source**: Performs a live query against the Org Identity Source backend and retrieves the current data as known to the backend. ie: This is the source's current data. +* **View Organizational Identity Source Record**: Retrieves the last data retrieved from the backend and used to create or update an Org Identity. ie: This is Registry's copy of the source data. +* **Add New Org Identity From Source**: Create a new Org Identity based on the Org Identity Source's data. In addition, this will create an Organizational Identity Source Record. +* **Resync Org Identity From Source**: Update the Org Identity and Organizational Identity Source Record using the latest (current) data available from the Org Identity Source. +* **Configuration >> Organizational Identity Sources**: Manage the plugins used to define and query one or more Org Identity Sources. \ No newline at end of file diff --git a/_episodes/05-old-groupFeatures.md b/_episodes/CO370_05-old-groupFeatures.md similarity index 100% rename from _episodes/05-old-groupFeatures.md rename to _episodes/CO370_05-old-groupFeatures.md diff --git a/files/handouts/CO310_ExamplePerson.pdf b/files/handouts/CO310_ExamplePerson.pdf new file mode 100644 index 0000000..8207d03 Binary files /dev/null and b/files/handouts/CO310_ExamplePerson.pdf differ diff --git a/index.md b/index.md index 296af65..6ef531d 100644 --- a/index.md +++ b/index.md @@ -23,15 +23,15 @@ COmanage is a registry for people. In this lesson you will learn how people are Time | Section | Description ---- | ------- | -----------   | [Setup](/setup.md) | Prepare for the lesson -00:25 | 1. [The CO Person Object](/_episodes/01-COperson.md) | Understand the CO Person object - the primary object for representing people in COmanage. What does this object contain? - -2. [The OrgIdentity Object](/_episodes/02-orgIdentity.md) - Sources & OrgIdentities -3. [About Attributes](/_episodes/03-attributes.md) -4. [About Authenticators](/_episodes/04-authenticators.md) -5. [About Roles](/_episodes/05-roles.md) -6. [About Groups](/_episodes/06-groups.md) -7. [Model Your Own People](/_episodes/07-youTryModelPeople.md) -8. [Your first person](/_episodes/08-youTryFirstPerson.md) +00:25 | [1. The CO Person Object](/_episodes/01-COperson.md) | Understand the CO Person object - the primary object for representing people in COmanage. What does this object contain? +00:25 | [2. The Org Identity Object](/_episodes/02-orgIdentity.md) | Understanding Org Identity Objects and how they are connected to representations of people external to COmanage. + +3. [3. About Attributes](/_episodes/03-attributes.md) +4. [4. About Authenticators](/_episodes/04-authenticators.md) +5. [5. About Roles](/_episodes/05-roles.md) +6. [6. About Groups](/_episodes/06-groups.md) +7. [7. Model Your Own People](/_episodes/07-youTryModelPeople.md) +8. [8. Your first person](/_episodes/08-youTryFirstPerson.md) _The actual schedule may vary slightly depending on the topics and exercises chosen by the instructor._