title

teaching

exercises

questions

objectives

keypoints

The OrgIdentity Object

Question here

List the objectives

List the key takeaways for the episode

2. The OrgIdentity Object

Because people in COmanage are represented by 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 Org Identity⚙️ objects, and are connected to Sources or Systems of Record.

The attributes (information) stored in Org Identity⚙️ objects typically includes

Link to CO Person⚙️ object
Status (the OrgIdentity status isn't really used to reflect external status as we rarely get that sort of information; this field is really to denote the status of the OrgIdentity wrt its OrgIdentitySource, if any)
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⚙️
List of identifiers
list of email addresses - Same as for CO Person⚙️
list of physical addresses - Same as for 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 Organizational 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 Organizational Identity Source Records⚙️ object, this item connects the Organizational Identity Source⚙️ to the Org Identity⚙️, 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⚙️ 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. >

(They're basically the identifiers asserted from the source. Most typically they'll be eppn/eptid)

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 Org Identity⚙️ (At the moment this isn't actually supported)

Identifiers for authentication

Identifiers attached to 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 (Probably best to use the formal name at least once: Organizational Identity) sources - information from external systems - and how they are captured and used in COmanage.

The relationship between `Org Identity`⚙️ 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:

for auditing where information about a person came from
for syncing with external systems to get the most up-to-date information
to connect with 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⚙️ objects and their COmanage-cached versions, 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:

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)

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

`Identity Source`⚙️ Object

Source attributes (information), once gathered, is stored in 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 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⚙️ Object.

`Identity Source Records`⚙️ Object

Information from an Identity Source⚙️ is connected to a 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 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

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 Modeling People 📝 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

COmanage Objects ⚙️

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

Worksheets

WORKSHEET	DESCRIPTION
Modeling People 📝	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: 3. Memberships

PREVIOUS SECTION: 1. The CO Person Object

LESSON OVERVIEW: CO310 - Modeling People in COmanage

WORKSHOP OVERVIEW: COmanage Workshop: Managing Identities & Collaborations

COmg-CO310-modelPeople/_episodes/02-orgIdentity.md