02-orgIdentity.md

---
title: "The OrgIdentity Object"
teaching: 15
exercises: 10
questions:
- "Question here"
objectives:
- "List the objectives"
keypoints:
- "List the key takeaways for the episode"
---

# 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_.

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

* Link to `CO Person`:gear: 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`:gear:
* List of identifiers
* 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 `Organizational 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 `Organizational Identity Source Records`:gear: object, this item connects the `Organizational 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.

# 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`: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: (_At the moment this isn't actually supported_)

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

---

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`: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:

* 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`: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.

# 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`:gear: 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.

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. 

## `Identity Source Records`:gear: 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. 

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.

---

# 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 [ Modeling People :memo:](/files/handouts/CO310-ModelingPeople.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

## COmanage Objects :gear:

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 

## Worksheets

WORKSHEET | DESCRIPTION
--------- | -----------
[ Modeling People :memo:](/files/handouts/CO310-ModelingPeople.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: [3. Memberships](/_episodes/03-memberships.md) 

PREVIOUS SECTION: [1. The CO Person Object](/_episodes/01-COperson.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)