Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
258 lines (179 sloc) 23.3 KB
title teaching exercises questions objectives keypoints workshopOverviewName workshopOverviewURL lessonOverviewName lessonOverviewURL previousEpisodeName previousEpisodeURL nextEpisodeName nextEpisodeURL
Getting started with identifiers
25
10
Question here
List the objectives
List the key takeaways for the episode
COmanage Workshop: Managing Identities & Collaborations
CO330 - Linking to Systems Outside of COmanage
../index.md
CO Services
/_episodes/02-coServices.md

1. Getting started with Identifiers⚙️

As we discussed when we were talking about modeling people in COmanage, Identifiers⚙️ can be attached to CO Person⚙️ or Org Identities⚙️. The main purpose of Identifiers⚙️ is to connect the information stored about people within the COmanage platform to representations of the same people in systems outside of COmanage so that the systems can be linked.

Identifiers⚙️ can also be attached to CO Groups⚙️ and CO Departments⚙️. With this use, they are used to connect the information in COmanage to representations of groups and departments in other systems.

The attributes (information) associated with the Identifiers⚙️ object typically includes

  • The value of the stored identifier
  • The identifier type
  • Indication of if this identifier can be used for signing into COmanage (only used when linked to Org Identity⚙️ objects)
  • The identifier status (active or suspended)

Constraints

  • Identifiers of a given type must be unique within a CO.
  • If a CO Person already has an identifier of a given type, no additional identifier will be created.
  • Identifier assignments generally assume a roman character set (i.e.: ASCII-7, not UTF-8).

Identifier types

There are identifiers of many types, each of which can contribute to satisfying the needs of particular use cases. Typical use cases include auto-assigning a COmanage platform (CMP) identifier for use with services and features specifically associated with the platform, an internal-to-the-organization identifier used across applications (since there may be situations where you might have multiple ePPNs for some registered people), a network identifier, one's email address, etc.

The type field helps to distinguish between the different types of identifiers that may be used for different purposes. There are several default types that are listed below. In addition, the types that can be specified can be extended beyond this default set to meet your needs. We generally won't be discussing the extension of the COmanage data model in this workshop, but we can include a discussion about it at the end of the workshop if there is interest and time.

Default identifier types

  • Badge
  • Enterprise
  • ePPN: eduPersonPrincipalName
  • ePTID: eduPersonTargetedID
  • ePUID
  • Mail: RFC 4524
  • National
  • Network
  • OpenID: OpenID
  • ORCID
  • ProvisioningTarget
  • Reference
  • SORID
  • UID: RFC 4519 uidObject (previously userid)

Where do Identifier⚙️ values come from?

Identifier⚙️ values are often established directly from Sources as can be found in Organizational Identity Source⚙️ and Organizational Identity Source Records⚙️ objects. These Source-based identifiers are usually of a particular type and have a format established outside of COmanage.

However, there are also times where you will want to have Identifier⚙️ values that are primarily used within COmanage or that can not be found in available Sources. In these situations, you will either be adding them directly to objects that use Identifiers, or you can specify Identifier Assignment rules to add Identifiers.

Using Identifier Assignment rules to create platform identifiers

It is good practice to configure at least one identifier that can be used within the platform as a CO Unique Identifier (for example, for CO Services⚙️, which we will discuss in the next section.) In addition, since some applications, particularly legacy applications, have specific requirements for user identifiers (eg. the identifier must take the form of an email address but can only have 8 characters) it is fairly common to configure more than one CO Unique Identifier to support a mix of general and specific application requirements.

While it is possible to manually assign Identifier⚙️ to be used as CO Unique Identifiers, doing so would be tedious and difficult to prevent duplicates (or "collisions".) COmanage provides the ability to specify Identifier Assignment rules. These rules provide a straight-forward way to have consistent formatting and conditions that meet your needs.

Some concepts

The identifiers (optionally) will be based on information that can be found in the CO Person⚙️ object that the identifier gets attached to. To understand identifier formats, you should understand the following concepts:

  • Collision Numbers: A number used to take a string that is not unique and makes it unique. For example, the string j.smith with a collision number added becomes (eg) j.smith.3. Collision numbers can be assigned sequentially or randomly.
  • Parameters: In a format specification, a parameter is replaced with some other string.
  • Sequenced Segment: In a format specification, sequenced segments are incorporated into an identifier in order to generate a unique string. An identifier is first generated from a format without any sequenced segments. If that identifier is not unique, sequenced segments are added until a unique identifier is generated.

The parameters

BEGINNER

Parameter Replaced by Example
(#) "replace with a collision number". A collision number is the next number that will generate a unique identifier. If your identifier is assigned using the sequential algorithm, it is the next unassigned integer beginning with the minimum value you configured. For identifiers assigned using the random algorithm, the collision number is selected randomly. Only one collision number is permitted in a format. C(#) = the letter C followed by the collision number, for example, C109 or C523849
(#:n) replaced by a collision number with the length of 'n'. This length specifier for (#) specifies a fixed width padded with zeros C(#:8) = the letter C followed by an 8-digit collision number, for example, C00000109 or C00523788

INTERMEDIATE

Using parameters based on components of the CO Person⚙️ name. For example, (G).(F)@myvo.org might generate Albert.Einstein@myvo.org

Parameter Replaced by Example
(G) Given name .
(M) Middle Name .
(F) Family Name .
(g) Given Name (lowercased) .
(m) Middle Name (lowercased) .
(f) Family Name (lowercased) .
(G/M/F/g/m/f:n) The first 'n' letters in the name as stated above. Note that while a length specifier for (#) indicates a maximum width (g:1).(f)@myvo.org would generate a.einstein@myvo.org instead the value listed above
(I/name) Existing identifiers can be embedded in the format string, using the parameter (I/name) where name is the alphanumeric name of the identifier Extended Type (not the display name). Note that an identifier of the specified type must already exist or the Identifier Assignment will fail. Identifier Assignments can be ordered, so it is possible to ensure that the first identifier is generated before the second identifier that uses it. For example (I/uid)@myvo.org
add a (#) Using name-based formats can't guarantee a unique identifier if your organization is non-trivial in size, so a collision number should be added (G).(F)(#)@myvo.org would generate Albert.Einstein1@myvo.org

ADVANCED

You can create more complicated patterns to more specifically define your identifiers. With more complicated pattern, you might not want to append a number for the first Albert.Einstein, only for the second. Or you might want to try a middle name first. Finally, you may only want to make one pattern choice in some situations, and a different one in others. These are accomplished through Sequenced Segments. We will not review these in this workshop, though they are documented in the COmanage wiki.

Hands on - Define Identifier Assignments for a CO Unique Identifier

Interactive system activity

In this hands-on activity we will define an Identifier Assignment rule that will be used to provide a CO Unique Identifier for the CO Persons⚙️ in our CO⚙️.

Sign into COmanage

  1. Using the credentials you are using for the CO Administrator👑 persona, sign into the system.
  2. Navigate to your CO⚙️, if necessary.

Navigate to the Identifier Assignment List

REQUIRED ROLE: CMP Administrator👑 OR CO Administrator👑

  1. Select the Configuration menu pick from the left menu to display the CO configuration list.
  2. Select the "Identifier Assignments" link to display the Identifier Assignments list.

Create a new Identifier Assignment rule

REQUIRED ROLE: CMP Administrator👑 OR CO Administrator👑

  1. Click the Add Identifier Assignment link above the table to display the configuration form.
Field Description Example value
Description Add a description for this rule that describes why it is being created. "CO Unique Identifier rule"
Type Select the Type from the drop down input. Since this is being used for a CO Unique Identifier, we suggest using the type "Enterprise" "Enterprise"
Email Type / Login We will skip the Email Type field because we didn't use a Type of Mail. We also will skip the Login field because this identifier type will not be used to sign into COmanage. (In general, CO Person identifiers are not used to log in to COmanage services (Organizational Identities are)) Blank
Algorithm The numbering method that will be used for Collision Numbers. Here you will choose between sequential and random numbering. Sequential
Format Format for the identifier. Select one of the pre-configured patterns from the dropdown input, or you can try your hand at designating a pattern using the rules that we discussed. See the description field
Permitted Characters The substitutions described above are controlled by the permitted characters. Consider someone with the given name "Mary Anne" and the family name "Johnson-Smith". You might not want to allow spaces and dashes in the generated identifier, so specifying "AlphaNumeric Only" as the permitted characters will result in identifiers like "maryanne.johnsonsmith" instead of "mary anne.johnson-smith". "AlphaNumeric and Dot, Dash, Underscore" would generate "maryanne.johnson-smith". Any Character
Minimum For random collision numbers (algorithm), the minimum value that may be assigned. For Sequential identifiers, the first value to be assigned. 1
Maximum For random collision numbers (algorithm), the maximum value that may be assigned. Blank
  1. Save the Identifier Assignment rule by clicking the ADD button at the bottom of the form.

Hands on - Manually assign identifiers

Interactive system activity

In an earlier lesson you created a CO Person⚙️. Let's use this newly created Identifier Assignment rule to provide an identifier for this object.

  1. Navigate to the CO Person⚙️ that you created by clicking on People on the menu on the left, and selecting My Population. Click on the Edit button for the person to get to the edit screen.
  2. On the menu to the right of the CO Person form, click on the Autogenerate Identifiers link.

Screen Shot - Autogenerate Identifiers

  1. Confirm that you want to generate the identifiers to continue. This action will execute all of your Active Identifier Assignment rules in the order that they were created. But will not create another identifier of the same type for any CO Person. If the CO Person⚙️ already has an identifier of the type specified in your rule, no new one will be created.

In the next lesson we will be talking about enrollment workflows. Any Identifier Assignment rules that you have configured will be run automatically as part of these workflows.

[10 min]

Identifier Reassignment

Identifiers can be reassigned if the original identifier was actually deleted (as opposed to being set to status suspended). If you do not wish identifiers to be reassigned, set the status of identifiers that are no longer needed to suspended; do not actually delete them. Click the Edit button next to an Identifier that you created to review its status.

A note about Identifier⚙️ validation

By default, COmanage accepts identifiers of any format, as long as they are unique for a given type within a CO⚙️. That is, two CO People⚙️ within the same CO⚙️ may not have the same identifier of the same type. COmanage can be configured to perform additional validation to support the following use cases:

  • Extending availability checks beyond COmanage database. This is useful to (eg) prevent assignment of identifiers that conflict with identifiers managed by other systems, such as email aliases.
  • Verifying that a new identifier does not violate restrictions on formats imposed by integrated systems.

If you are interested in learning more about identifier validation, we can review them toward the end of the workshop if time.


Special uses for identifiers

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

Screen Shot - Org Identity Identifier edit screen

This last item is important to understand, especially in a multi-tenant environment. When there are multiple COs⚙️ in the platform it is possible that someone's sign in Identifer⚙️ is linked to CO Person⚙️ objects in mutile COs⚙️. When this situation happens, the individual will have access to all COs⚙️ of which they are a part. This arrangement is consistent with the current design, where the entire platform expects a single authentication system that applies to all COs⚙️. If different organizations or collaborations expect to use different authentication systems, they cannot share the same platform.

Use for provisioning

We recommend that COs⚙️ use a CO Unique Identifier (like what we just created) to provision (grant access to) the services that will be used by everyone in the CO⚙️ such as wikis, mail list managers, and domain specific applications. These common services are referred to as CO Servcies. We will be talking about CO Services in the next section.

The advantage of having federated applications consume the CO Unique Identifier and use it as the primary identifier or key for the user is that even if a user's organization changes, and hence her federated eduPersonPrincipalName (ePPN) changes, the new ePPN can be linked in COmanage to the existing CO Person⚙️ and the same CO Unique Identifier can continue to be provisioned to the application so that the user does not lose access to the application during the transition from one home organization to another.

An example

The CO administrator for the TestCO configures an identifier assignment so that each user in the CO is assigned an identifier of the form testcoXXXX where XXXX is an integer, starting at 1000 and assigned sequentially as users are enrolled in the CO.

Mandeep Kamala, a graduate student at Big University, later enrolls in the CO and is automatically assigned the identifier testco1241. Mandeep's eppn is mandeep.kamala@biguniversity.edu and that eppn is recorded during her enrollment to her organizational identity record that is linked to her CoPerson record. The TestCO wiki, however, is configured to consume testco1241 as the primary identifier for Mandeep.

Later Mandeep defends her thesis, graduates, and becomes faculty at Small University where her new eppn is mkamala7@smallu.edu. Mandeep executes a Registry identity linking enrollment flow and links her new organizational identity record with eppn mkamala7@smallu.edu to her existing CoPerson record.

The next time Mandeep accesses the wiki the SP queries the AA using her new eppn mkamala7@smallu.edu and the AA returns the same identifier testco1241 because her same CoPerson record is linked to her new organizational identity. Mandeep's access to the wiki is the same and continuous even though she has transitioned from Big University to Small University.


Terminology & resources

COmanage Objects ⚙️

OBJECT DESCRIPTION Introduced in
Identifier⚙️ Objects that enable one to connect the information stored about people within the COmanage platform to representations of the same people in systems outside of COmanage CO330-01 (this section)
CO Service⚙️ Services or applications that can be configured for CO Persons⚙️ to have access to by participating in the organization or collaboration. CO330-02
. ****** CO320 - Modeling Your Organization in COmanage ****** .
CO⚙️ any formal or informal group of individuals that work collaboratively in a digital setting. They have a goal of a shared infrastructure that supports their collaborations so that the traditional limitations of localized applications may be overcome. CO320-01
COU⚙️ an organizational structure within a CO that differs in how individuals join and/or leave the group, how applications get provisioned or deprovisioned, who manages person membership and privileges in the group, or in the information stored or used about members of the group. CO320-02
CO Group⚙️ A specific COmanage organizational structure for representing certain collections of CO Persons⚙️ CO320-03
CO Department⚙️ A COmanage object that is used to model organizational departments. They 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. CO320-04
. ****** CO310 - Modeling People in COmanage ****** .
CO Person⚙️ The representation of a person in COmanage CO310-01
CO Group⚙️ A specific COmanage organizational structure for representing certain collections of CO Persons⚙️ CO320-03
Organizational Identity Source⚙️ Information about a person as obtained from an external source such as LDAP, netFORUM or ORCID CO310-02
Organizational Identity Source Records⚙️ COmanage's cached value of the values at the source CO310-02
CO Person Role⚙️ The representation of a person's role in COmanage. This object describe the person's role with certain collections of people within your organization or collaboration. These objects are attached to ⚙️ CO Person objects; there may be any number of Roles. C0310-04

CO Person Roles 👑

ROLE DESCRIPTION Introduced in
. ****** CO320 - Modeling Your Organization in COmanage ****** .
CMP Administrators👑 CMP Administrators are effectively super users, with the ability to perform almost all operations on the platform. CO320-01
CO Administrators👑 CO⚙️ Administrators are super users within a CO. These individuals belong to the CO:admins group of the CO⚙️. CO320-01
System Administrators👑 System Administrators have privileges that enable them to maintain the COmanage application. CO320-01
COU Administrators👑 Individuals that have the ability to perform lifecycle management operations on the CO People⚙️ who have CO Person Roles⚙️ associated with the COU⚙️. CO320-02

Worksheets

WORKSHEET DESCRIPTION Introduced in
. ****** CO320 - Modeling Your Organization in COmanage ****** .
Modeling Organization 📝 Planning sheet used in this lesson for understanding how the parts of the COmanage Organization fit together CO320
CO Planning Worksheet 📝 Planning worksheet for creating your CO(s). Contains all of the configuration sections at a glance CO320-01
COU Planning Worksheet 📝 Planning worksheet for creating your CO(s). Contains all of the configuration sections at a glance. CO320-02
CO Group Planning Worksheet 📝 Planning worksheet for creating your CO Group(s). Contains all of the configuration sections at a glance. CO320-03
. ****** CO310 - Modeling People in COmanage ****** .
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 CO310

NEXT SECTION: 2. CO Services


LESSON OVERVIEW: CO330 - Linking to Systems Outside of COmanage

WORKSHOP OVERVIEW: COmanage Workshop: Managing Identities & Collaborations

You can’t perform that action at this time.