Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Re-working episodes
Change the general structure of CO310. completed the writing of episode 1: The CO Person Object.

Old episodes will be removed once incorporated into new ones.
  • Loading branch information
lpaglione committed Oct 26, 2019
1 parent d6d1683 commit 8d14bb8
Show file tree
Hide file tree
Showing 10 changed files with 219 additions and 8 deletions.
10 changes: 6 additions & 4 deletions README.md
@@ -1,11 +1,13 @@
![COmanage Logo](assets/img/COmanage-Logo-LG-onWhite.png)

CO306: Group and Role Management
================================
CO310: Modeling People in COmanage
==================================

A lesson from the COmanage Training set.
A lesson from the [COmanage Training set](https://github.internet2.edu/lpaglione/COmg-trainingOverview).

Please see <TBD> for a rendered version of this material. Planning materials for the training course can be found in the Google Doc file [COmanage Training Planning](https://docs.google.com/document/d/1sjw_KidTixvknx6Ev-nkk9z9SsVnzpzMyFA_a0KBS90/edit?usp=sharing)
COmanage is a registry for people. In this lesson you will learn how people are represented within COmanage. You will explore how COmanage stores and manages information about people and how this information is linked to systems outside of COmanage. You will learn the types of roles that people can play and the privileges that are granted in COmanage as a result. Also covered is how to manage user authentication.

Please see <TBD> for a rendered version of this material.

**Maintainer(s):**

Expand Down
111 changes: 111 additions & 0 deletions _episodes/01-COperson.md
@@ -0,0 +1,111 @@
---
title: "The COPerson Object"
teaching: 15
exercises: 10
questions:
- "Question here"
objectives:
- "List the objectives"
keypoints:
- "List the key takeaways for the episode"
---

# The CO Person

People are represented in COmanage by a :gear: `CO Person` object. Some information is stored in this object, and it is connected to several other types of useful objects.

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.
* List of names
* List of identifiers
* List of email addresses

This object also is connected to several other structural items that we will talk about in this lesson, including

* **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. Each :gear: `CO Person` must have at least one of these, though multiple are allowed.
* **Roles** - the roles that the person assumes within your organization.
* **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.

The status value will affect what someone is able to do, including affecting what information is shared with external systems for access and resource provisioning. We will review how status affects provisioning when we talk about provisioning in a later lesson.

Below is a table of the available statuses _< NOTE: This list should be simplified somehow - some of these statuses aren't really used for CO person, but are interim status during the enrollment flow - should include only the 'stable' status that a CO Person remains in for longer durations. For the others, we can allude to them, and explain them more fully where they are actually used. >_

Preference | Status | Description
---------- | ------ | -----------
1 | Active | Person or Role is an active member of the organization or collaboration
2 | GracePeriod | Primary association with the organization has ended, but services have not yet been deprovisioned
3 | Suspended | Association with the organization has been (manually) temporarily suspended
4 | Expired | Valid through date has been reached
5 | Approved |
6 | PendingApproval | The enrollment flow petition is pending approval
7 | Confirmed |
8 | PendingConfirmation | An invitation or email confirmation was sent via an enrollment flow
9 | Invited | An invitation was sent via default enrollment
10 | Pending |
11 | Denied | The enrollment flow petition was denied
12 | Declined | The invitation sent via default enrollment was declined
13 | Deleted |
14 | Duplicate | The record is a duplicate of another

# About names

Each :gear: `CO Person` object must include the person's name. :gear: `CO Person` objects can have more than one name, but exactly one of the names must be designated as the _primary name_. Names can be encoded in any one of several languages / character sets.

# About identifiers

_< NOTE: Laura wrote this section, but isn't sure about her understanding of identifiers for CO Person. From the documentation it sounds like the recommendation is to have one CO Person identifier that is auto assigned, and for this identifier to be used for provisioning to at least some kinds of services rather than tying that provisioning to an org identity (like eppn) that may change if affiliation does. BUT... this may be totally wrong. >_

Identifiers allow for unique identification. In COmanage, each :gear: `CO Person` may be associated with [an?] identifier[s?]. [These identifiers | The identifier] can be important when provisioning services to :gear: `CO Persons`.

We recommend that you configure at least one identifier for each :gear: `CO Person` to represent the person within COmanage. While it is possible to manually assign identifiers, we suggest that you allow COmanage to automatically assign these identifiers. You are able to configure what these identifiers will look like.

# About email addresses

COmanage can track email addresses, though it does very little with them directly. Email addresses can be verified from within COmanage (which we will not review during this workshop). Email addresses can also be used for mailing lists using the mailman provisioner (which we will review, time allowing.)

When storing email addresses, more than one can be associated with the :gear: `CO Person`, and can contain a type to help distinguish the conditions under which to use each. For example,

* **official** - the address to render in a directory entry, especially for use in a "To:" or "Cc:" field. _LDAP attribute: mail_
* **personal** - Alternate addresses to accept for mail delivery or forwarding. _LDAP attribute: mailAlternateAddress_
* **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

![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**.

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.

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".

[10 min]

---

# Terminology & resources

## COmanage Objects

OBJECT | DESCRIPTION
------ | -----------
:gear: `CO Person` | the representation of a person in COmanage
:gear: `Org Identity` | the representation of a person in other contexts outside of COmanage
:gear" `CO Group` | a specific COmanage organizational structure for representing certain collections of :gear: `CO Persons`

## Worksheets

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

## Slides
File renamed without changes.
File renamed without changes.
33 changes: 33 additions & 0 deletions _episodes/02-orgIdentity.md
@@ -0,0 +1,33 @@
---
title: "The OrgIdentity Object"
teaching: 20
exercises: 0
questions:
- "Question here"
objectives:
- "List the objectives"
keypoints:
- "List the key takeaways for the episode"
---


# About identifiers

Organization Identities also use identifiers. two types - authentication vs

Identifiers can be one of several different types

eppn: eduPersonPrincipalName
eptid: eduPersonTargetedID
mail: RFC 4524
openid: OpenID
uid: RFC 4519 uidObject (previously userid)


# Terminology

## COmanage Objects

OBJECT | DESCRIPTION
------ | -----------
:gear: `Org Identity` | the representation of a person in other contexts outside of COmanage
File renamed without changes.
File renamed without changes.
File renamed without changes.
53 changes: 53 additions & 0 deletions _episodes/05-roles.md
@@ -0,0 +1,53 @@
---
title: "About Roles"
teaching: 20
exercises: 0
questions:
- "Question here"
objectives:
- "List the objectives"
keypoints:
- "List the key takeaways for the episode"
---

# CO Person Role Status

As with the :gear: `CO Person` object, each :gear: `CO Person Role` object

## Calculated status value

Calculating the :gear: `CO Person` status from those of the :gear: `CO Person Role` object

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. (Onboarding)
* As part of an Organizational Identity Source and Pipeline sync.
* Due to an Expiration Policy. (Offboarding)
* 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 based on their status, as indicated in the table, below.

# Terminology

## COmanage Objects

OBJECT | DESCRIPTION
------ | -----------
:gear: `CO Person Role` | the representation of a person's role in COmanage. This object describe the person's role with the collections of people within your organization or collaboration. These objects are attached to :gear: `CO Person` objects; there may be any number of Roles.
20 changes: 16 additions & 4 deletions index.md
Expand Up @@ -3,24 +3,29 @@ layout: lesson
root: .
---

CO person roles - a table in the database that has specific attributes - COU (how you end up in an COU), affiliation column (which initially maps to the 8 terms found in eduPerson schema - describes the affiliation of the person in the COU, extendable). Roles are used for data tracking (validity, title, etc), Information about the person related specifically to the COU/affiliation combination. “Record keeping” - also get you automagic “groups” (groups are a table in COmanage) - basis for access control. You usually don’t use roles directly - but they are the basis for these groups that you would use for access control. In this lesson we will learn the purpose of “CO Person Roles”, their relationship to CO Groups, and how Roles and Groups are used to facilitate access to resources and services. This lesson will provide hands-on training on how to set up and manage Roles and Groups.
# CO310 - Modeling People in COmanage

Expiration policies - let you define policies that operate on Roles that allow you to expire group membership for individual - make this a separate course (policy definition, notifications, grace periods, transitioning from COU to COU, etc)
COmanage is a registry for people. In this lesson you will learn how people are represented within COmanage. You will explore how COmanage stores and manages information about people and how this information is linked to systems outside of COmanage. You will learn the types of roles that people can play and the privileges that are granted in COmanage as a result. Also covered is how to manage user authentication.

**WHO IS THIS COURSE FOR?** Application administrators.

> ## Prerequisites
> CO301 or equivalent
> [CO101: Getting to Know COmanage](https://github.internet2.edu/lpaglione/COmg-CO101-intro) or equivalent

> ## Top Things You Need To Know
>
> 0. More things you need to know will be added later
> 0. What is a person registry?
> 1. What is COmanage?
> 2. How to get to an installed version of COmanage

## Schedule

Time | Section | Description
---- | ------- | -----------
&nbsp; | [Setup](/setup.md) | Prepare for the lesson
00:25 | 1. [The CO Person Object](/episodes/01-COperson) | Understand the CO Person object - the primary object for representing people in COmanage. What does this object contain?


00:00 | 1. [Sub-units of COs](/episodes/01-dividingCOsAndCOUs) | Subdividing COs & COUs using Groups and Departments
00:10 | 2. [The Roles of COmanage](/episodes/02-comanageRoles) | Roles (Administrative and non-administrative)
00:00 | 3. [Creating Groups](/episodes/03-comanageGroups) | How & why to create groups in COmanage
Expand All @@ -30,3 +35,10 @@ Time | Section | Description

_The actual schedule may vary slightly depending on the topics and exercises chosen by the instructor._

2. [The OrgIdentity Object](/episodes/02-orgIdentity) - Sources & OrgIdentities
3. [About Attributes](/episodes/03-attributes)
4. [About Authenticators](/episodes/04-authenticators)
5. [About Roles](/episodes/05-roles)
6. [About Groups](/episodes/06-groups)
7. [Model Your Own People](/episodes/07-youTryModelPeople)
8. [Your first person](/episodes/08-youTryFirstPerson)

0 comments on commit 8d14bb8

Please sign in to comment.