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.

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.

---

Hands on - Creating a CO Unique Identifier

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.

Create a unique identifier type

REQUIRED ROLE: CMP Administrator👑 OR CO Administrator👑

First you will create a unique identifier type (an extended type) that you will use for your CO.

3. Select the Configuration menu pick from the left menu to display the CO configuration list.

4. Select the “Extended Types” link to display the list of attribute types.

   

5. Select the “Identifiers (CO Person)” types as the attributes and click “filter” to show the list of Identifier attributes. This list displays the identifier attribute types that are shipped with COmananage.

   

6. Select the Add Extended Type at the top of the table to generate a new identifier attribute type.

7. Give the new type a unique name, and click ADD.

   

Navigate to the Identifier Assignment List

REQUIRED ROLE: CMP Administrator👑 OR CO Administrator👑

8. Select the Configuration menu pick from the left menu to display the CO configuration list.

9. Select the “Identifier Assignments” link to display the Identifier Assignments list.

   

Create a new Identifier Assignment rule

REQUIRED ROLE: CMP Administrator👑 OR CO Administrator👑

10. 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”	the identifier type that you just created
    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

11. Save the Identifier Assignment rule by clicking the ADD button at the bottom of the form.

Using manually assign identifiers

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.

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

13. On the menu to the right of the CO Person form, click on the Autogenerate Identifiers link.

     

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

15. Confirm that your newly generated identifier is present in the identifiers section of the CO Person⚙️.

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]

---

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.

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.

---