Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Updates from working on CO320
  • Loading branch information
lpaglione committed Oct 31, 2019
1 parent c505780 commit a6b6c17
Show file tree
Hide file tree
Showing 6 changed files with 64 additions and 58 deletions.
22 changes: 11 additions & 11 deletions _episodes/01-COperson.md
Expand Up @@ -12,9 +12,9 @@ keypoints:

# 1. The CO Person

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

The attributes (information) stored in the `CO Person` :gear: object typically includes
The attributes (information) stored in the `CO Person`:gear: 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
Expand All @@ -26,7 +26,7 @@ The attributes (information) stored in the `CO Person` :gear: object typically i

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 `CO Person` :gear: must have at least one of these, though multiple are allowed.
* **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 `CO Person`:gear: 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
Expand All @@ -35,7 +35,7 @@ This object also is connected to several other structural items that we will tal

# CO Person status

Each `CO Person` :gear: 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.
Each `CO Person`:gear: 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.

Expand All @@ -60,21 +60,21 @@ Preference | Status | Description

# About name attributes

Each `CO Person` :gear: object must include the person's name. `CO Person` :gear: 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.
Each `CO Person`:gear: object must include the person's name. `CO Person`:gear: 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 identifier attributes

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

We recommend that you configure at least one identifier for each `CO Person` :gear: 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.
We recommend that you configure at least one identifier for each `CO Person`:gear: 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 address attributes

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 `CO Person` :gear:, and can contain a type to help distinguish the conditions under which to use each. For example,
When storing email addresses, more than one can be associated with the `CO Person`:gear:, 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_
Expand Down Expand Up @@ -103,12 +103,12 @@ Once you have thought about who you will use as your examples, write their names

# Terminology & resources

## COmanage Objects
## COmanage Objects :gear:

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

## Worksheets

Expand Down
46 changes: 23 additions & 23 deletions _episodes/02-orgIdentity.md
Expand Up @@ -12,64 +12,64 @@ keypoints:

# 2. The OrgIdentity Object

Because people in COmanage are represented by `CO Person`:gear: 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 `Org Identity` :gear: objects, and are connected to _Sources_ or _Systems of Record_.
Because people in COmanage are represented by `CO Person`:gear: 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 `Org Identity`:gear: objects, and are connected to _Sources_ or _Systems of Record_.

The attributes (information) stored in `Org Identity` :gear: objects typically includes
The attributes (information) stored in `Org Identity`:gear: objects typically includes

* Link to `CO Person` :gear: object
* Link to `CO Person`:gear: object
* Status
* Personal information about the person
* Date of birth
* affiliation (eduPerson)
* source organization, department, & title
* Validity dates: from and through
* List of names - Same as for `CO Person` :gear:
* List of names - Same as for `CO Person`:gear:
* List of identifiers
* list of email addresses - Same as for `CO Person` :gear:
* list of physical addresses - Same as for `CO Person` :gear:
* list of email addresses - Same as for `CO Person`:gear:
* list of physical addresses - Same as for `CO Person`:gear:

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

* **Source Information** - represented by an `Identity Source` :gear: 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 `Identity Source Records` :gear: object, this item connects the `Identity Source` :gear: to the `Org Identity` :gear:, and is also used to cache data in COmanage from sources so that they are readily available.
* **Source Information** - represented by an `Identity Source`:gear: 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 `Identity Source Records`:gear: object, this item connects the `Identity Source`:gear: to the `Org Identity`:gear:, and is also used to cache data in COmanage from sources so that they are readily available.

---

# About name, email address and physical address attributes

These lists of items are handled similarly to how they are used for `CO Person` :gear: objects. Because of their similarity, we won't review them in this section.
These lists of items are handled similarly to how they are used for `CO Person`:gear: objects. Because of their similarity, we won't review them in this section.

# About identifier attributes

_< NOTE: Laura wrote this section, but isn't sure about her understanding of identifiers for Org Identity. The information here may be totally wrong. >_

`Org Identity` :gear: objects also use identifiers. The identifiers can be one of several different types
`Org Identity`:gear: 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 `Org Identity` :gear:
* Or an extended type that is specific to the source related to the `Org Identity`:gear:

## Identifiers for authentication

Identifiers attached to `Org Identity` :gear: objects can potentially be used for signing into COmanage. A flag set on the identifier will indicate if it is used for sign in.
Identifiers attached to `Org Identity`:gear: 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 `Org Identity` :gear: objects and **sources**
# The relationship between `Org Identity`:gear: objects and **sources**

The `Org Identity` :gear: 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:
The `Org Identity`:gear: 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 `Identity Source` :gear: objects and their COmanage-cached versions, `Identity Source Record` :gear: objects.
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 `Identity Source`:gear: objects and their COmanage-cached versions, `Identity Source Record`:gear: objects.

Systems of Record (external sources) can be from anywhere. Common ones include LDAP servers, REST APIs, SQL databases, flat files, and so on.

Expand All @@ -93,21 +93,21 @@ API-based sources (API) | Used to associate registered people with information f

## :gear: Identity Source Object

Source attributes (information), once gathered, is stored in `Identity Source` :gear: 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.
Source attributes (information), once gathered, is stored in `Identity Source`:gear: 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 `Identity Source` :gear: objects typically includes:
The information stored in `Identity Source`:gear: 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 `Identity Source` :gear: Object.
In addition, specific data and attributes, customized for the source type, is attached to the `Identity Source`:gear: Object.

## :gear: Identity Source Records Object

Information from an `Identity Source` :gear: is connected to a `Org Identity` :gear: 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.
Information from an `Identity Source`:gear: is connected to a `Org Identity`:gear: 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 `Org Identity` :gear: and :gear" `Org Identity Source` objects, these objects also include information about when the data was last cached.
In addition to the links to the related `Org Identity`:gear: and :gear" `Org Identity Source` objects, these objects also include information about when the data was last cached.

---

Expand All @@ -129,9 +129,9 @@ In the **Org Identities** box, jot down one or more sources where there are repr

OBJECT | DESCRIPTION
------ | -----------
`Org Identity` :gear: | the representation of a person in other contexts outside of COmanage
`Identity Source` :gear: | Information about a person as obtained from an external source such as LDAP, netFORUM or ORCID.
`Identity Source Records` :gear: | COmanage's cached value of the values at the source
`Org Identity`:gear: | the representation of a person in other contexts outside of COmanage
`Identity Source`:gear: | Information about a person as obtained from an external source such as LDAP, netFORUM or ORCID.
`Identity Source Records`:gear: | COmanage's cached value of the values at the source

## Worksheets

Expand Down
4 changes: 2 additions & 2 deletions _episodes/03-memberships.md
Expand Up @@ -26,7 +26,7 @@ Consider the people that you have been working with on your worksheet [ :memo: M
* Are they in specific departments?
* What formal and informal groups are they in? For example, project groups, mailing lists, role groups (like department heads), collaborations (like the holiday party committee)

In the **Memberships** box of the worksheet, jot down several collections of people that each of your `CO Persons` :gear: are a part of.
In the **Memberships** box of the worksheet, jot down several collections of people that each of your `CO Persons`:gear: are a part of.

Share what you have written with someone else in the workshop. Is there anything that they considered that you might want to include on your sheet as well?

Expand All @@ -36,7 +36,7 @@ Share what you have written with someone else in the workshop. Is there anything

# Terminology

## COmanage Objects
## COmanage Objects :gear:

OBJECT | DESCRIPTION
------ | -----------
Expand Down

0 comments on commit a6b6c17

Please sign in to comment.