Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
First substantive commit
  • Loading branch information
lpaglione committed Sep 15, 2019
1 parent 12d08cf commit 29bc834
Show file tree
Hide file tree
Showing 18 changed files with 1,789 additions and 54 deletions.
6 changes: 6 additions & 0 deletions LICENSE.md
@@ -0,0 +1,6 @@
---
layout: page
title: "Licenses"
root: .
---
## To include the license for this material
28 changes: 7 additions & 21 deletions README.md
@@ -1,26 +1,12 @@
![COmanage Logo](https://registry-test.cilogon.org/registry/img/COmanage-Logo-LG-onWhite.png)
![COmanage Logo](assets/img/COmanage-Logo-LG-onWhite.png)

# CO306: Group and Role Management
CO306: Group and Role Management
================================

CO person roles - a table in the database that has specific attributes - COU (how you end up in an COU), affiliation column (which initially maps to the 8 terms found in eduPerson schema - describes the affiliation of the person in the COU, extendable). Roles are used for data tracking (validity, title, etc), Information about the person related specifically to the COU/affiliation combination. “Record keeping” - also get you automagic “groups” (groups are a table in COmanage) - basis for access control. You usually don’t use roles directly - but they are the basis for these groups that you would use for access control. In this lesson we will learn the purpose of “CO Person Roles”, their relationship to CO Groups, and how Roles and Groups are used to facilitate access to resources and services. This lesson will provide hands-on training on how to set up and manage Roles and Groups.
A lesson from the COmanage Training set.

Expiration policies - let you define policies that operate on Roles that allow you to expire group membership for individual - make this a separate course (policy definition, notifications, grace periods, transitioning from COU to COU, etc)
Please see <TBD> for a rendered version of this material. Planning materials for the training course can be found in the Google Doc file [COmanage Training Planning](https://docs.google.com/document/d/1sjw_KidTixvknx6Ev-nkk9z9SsVnzpzMyFA_a0KBS90/edit?usp=sharing)

**WHO IS THIS COURSE FOR?** Application administrators.
**Maintainer(s):**

> ## Prerequisites
> CO301 or equivalent

> ## Top Things You Need To Know
>
> 0. More things you need to know will be added later

## Schedule

Time | Section | Description
---- | ------- | -----------
&nbsp; | [Setup](/episodes/setup.md) | Prepare for the lesson
00:00 | 1. First episode | description
00:10 | 2. Second episode | description

_The actual schedule may vary slightly depending on the topics and exercises chosen by the instructor._
* [Laura Paglione](https://github.internet2.edu/lpaglione)
82 changes: 82 additions & 0 deletions _config.yml
@@ -0,0 +1,82 @@
#------------------------------------------------------------
# The structure of this site including this file was adapted
# from The Carpentries, who should receive attribution and
# credit for these configurations. They are covered by a
# Creative Commons Attribution license
# https://creativecommons.org/licenses/by/4.0/
#------------------------------------------------------------


#------------------------------------------------------------
# Values for this lesson.
#------------------------------------------------------------

# Overall title for pages.
title: "COmanage Training"

# Life cycle stage of the lesson
# possible values: "pre-alpha", "alpha", "beta", "stable"
life_cycle: "alpha"

#------------------------------------------------------------
# Generic settings (should not need to change).
#------------------------------------------------------------

# What kind of thing is this ("workshop" or "lesson")?
kind: "lesson"

# Magic to make URLs resolve both locally and on GitHub.
# See https://help.github.com/articles/repository-metadata-on-github-pages/.
# Please don't change it: <USERNAME>/<PROJECT> is correct.
repository: <USERNAME>/<PROJECT>

# Email address, no mailto:
email: "checkout@carpentries.org"

# Sites.
comanage_site: "https://spaces.at.internet2.edu/display/COmanage/"
carpentries_site: "https://carpentries.org/"

# Surveys.
pre_survey: ""
post_survey: ""

# Start time in minutes (0 to be clock-independent, 540 to show a start at 09:00 am)
start_time: 540

# Specify that things in the episodes collection should be output.
collections:
episodes:
output: true
permalink: /:path/index.html
extras:
output: true
permalink: /:path/index.html

# Set the default layout for things in the episodes collection.
defaults:
- values:
root: .
layout: page
- scope:
path: ""
type: episodes
values:
root: ..
layout: episode
- scope:
path: ""
type: extras
values:
root: ..
layout: page

# Files and directories that are not to be copied.
exclude:
- Makefile
- bin/

# Turn on built-in syntax highlighting.
highlighter: rouge

plugins: [jekyll-redirect-from]
48 changes: 48 additions & 0 deletions _episodes/01-dividingCOsAndCOUs.md
@@ -0,0 +1,48 @@
---
title: "Sub-dividing COs & COUs"
teaching: 20
exercises: 0
questions:
- "Question here"
objectives:
- "List the objectives"
keypoints:
- "List the key takeaways for the episode"
---

## Difference between CO Groups and COUs

The major differences between COUs and [CO Groups](https://spaces.at.internet2.edu/display/COmanage/CO+Groups+and+Group+Memberships) are

* Any CO Person can create a CO Group; only CO Administrators can create COUs.
* CO Group Memberships attach at the CO Person level, whereas COU memberships attach at the CO Person Role level.
* Management of CO Group Memberships is simple (e.g., manual management by the CO Group Owner, self-opt in for open CO Groups, etc.), whereas COU memberships can be managed using [Enrollment Flows](https://spaces.at.internet2.edu/display/COmanage/Registry+Enrollment+Flow+Configuration) and [Expiration Policies](https://spaces.at.internet2.edu/display/COmanage/Expiration+Policies).
* COU memberships imply CO Group Memberships (in the _Members:COU group_).
* Email Addresses can be attached to CO Groups via [CO Email Lists](https://spaces.at.internet2.edu/display/COmanage/CO+Email+Lists).

## About CO Groups

COmanage Groups (CO Groups) are defined at the CO level, and CO Group Memberships attach to the CO Person. CO Groups are fairly basic, for more sophisticated needs COmanage can be connected to Grouper using the Grouper Provisioning Plugin. By default, any CO Person can create a new CO Group.

## About CO Departments

CO Departments are primary objects within Registry, which means that they are intended to store representations of external objects (just like CO People). CO Departments can attach to either a CO or a COU, and 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. CO Departments can be used to support various use cases:

* In a VO deployment, CO Departments can be used to represent research groups.
* In an enterprise deployment, CO Departments can be used to represent the University department hierarchy.

While there may typically be a one-to-one relationship between CO Departments and COUs, it is not strictly necessary. For example, a COU maybe made up of members spanning two departments.

CO Departments are visible to anyone within the CO, by logging in to Registry, though only CO Administrators may edit their information.

CO Departments are specifically intended to be used with [Registry Services](https://spaces.at.internet2.edu/display/COmanage/Registry+Services) and the Service Portal.

## Comparison Summary

| COU | CO Department | CO Group
---|-----|---------------|---------
**Belongs To** | CO | CO; COU | CO; COU (for automatic groups only)
Has Many | CO Person Roles; CO Departments | |CO People (via CoGroupMember); CO Email List
HIerarchical | Yes | No ([CO-1523](https://bugs.internet2.edu/jira/browse/CO-1523)) | No ([CO-721](https://bugs.internet2.edu/jira/browse/CO-721))
Object Type | Structural Object | Primary Registry Object | Primary Registry Object
Supported Attributes | None | Addresses; Email Addresses; Identifiers; Telephone Numbers; URLs; Leadership Group; Administrative Group; Support Group | Open / Closed; Managers (via CoGroupMember); Email Addresses (via CoEmailList); Identifiers (as of Registry v3.3.0)
87 changes: 87 additions & 0 deletions _episodes/02-comanageRoles.md
@@ -0,0 +1,87 @@
---
title: "The Roles of COmanage"
teaching: 20
exercises: 0
questions:
- "Question here"
objectives:
- "List the objectives"
keypoints:
- "List the key takeaways for the episode"
---

# About People

People are represented in COmanage by a CO Person object... <more definition is needed>

See the table on the COmanage wiki for a [comparison chart of tasks](https://spaces.at.internet2.edu/display/COmanage/Roles) that each role can perform.

## What can people do when they assume a role?

COmanage uses roles to manage the functionality that different users can use. This functionality falls into the following broad categories:

* **Collaborative Organization (CO) Management** - Management of the top-level object in COmanage.
* **Person Management** - The ability to add and edit the information about people in COmanage, and control their access to resources.
* **Role/ Group Management** - The ability to assign and adjust administrative roles and group membership
* **Provisioning** - Management of automated and manual provisioning - access to external resources
* **Content** - The ability to access certain types of COmanage content
* **Audit** - The ability to review and report on historical actions taken within COmanage
* **System Administration** - For the technical maintenance of COmanage

## Administrator Roles

COmanage Registry defines three types of administrators.

### Platform (CMP) Administrators _(Also called Registry Admin in the documentation)_

Platform Administrators are effectively super users, with the ability to perform almost all operations on the platform. (Platform Administrators cannot execute enrollment flows for COs unless authorized by the enrollment flow.)

Platform Administrators are configured by [adding the appropriate Organizational Identity](https://spaces.at.internet2.edu/display/COmanage/Default+Registry+Enrollment) to the COmanage CO, and then adding the corresponding person to the CO:admins group (v2.0.0 and later) or admin group (prior to v2.0.0) within the COmanage CO.

The first user added as part of the [Registry Setup Script](https://spaces.at.internet2.edu/display/COmanage/Registry+Installation+-+Registry+Setup+Script) is automatically configured to be a Platform Administrator.

### Collaboration (CO) Administrators

Collaboration Administrators are super users _within a CO_. Collaboration Administrators are configured by adding the appropriate Organizational Identity to the CO (if not already done), and then adding the corresponding person to the CO:admins group (v2.0.0 and later) or admin group (prior to v2.0.0) within the CO.

CO Administrators can manage any CO Group within their CO.

### Unit (COU) Administrators

Collaboration Administrators with sophisticated administrative requirements may optionally define Unit Administrators. Unit Administrators have limited privileges within the CO, generally related to the ability to enroll and manage populations within the CO Unit (COU).

Unit Administrators are configured by adding the appropriate Organizational Identity to the CO (if not already done), and then adding the corresponding person to the _CO:COU:COU-Name:admins_ group (v2.0.0 and later) or _admin:COU-Name_ group (prior to v2.0.0) within the CO.

COU Administrators can be defined for each COU, giving them the ability to perform lifecycle management operations on the CO People who have CO Person Roles associated with the COU that they manage (or any child COUs of that COU).

### System Administrators

System Administrators have privileges that enable them to maintain the COmanage application. These capabilities include the ability to provision cluster resources (for example, hardware, virtual machines, etc), Register and maintain IP Addresses, administer application upgrades, manage and conduct operating system upgrades and conduct backups.

## Non-administrator roles

### CO Participant

<Needs a description>

### Guest

<Needs a description>

## Managing Roles

### CO Group Membership and Enrollment

CO Group Memberships can be added as part of an [Enrollment Flow](https://spaces.at.internet2.edu/display/COmanage/Registry+Enrollment+Flow+Configuration) by adding an attribute of the appropriate type. For more details, see [Registry Enrollment Flow Configuration](https://spaces.at.internet2.edu/display/COmanage/Registry+Enrollment+Flow+Configuration).

CO Group Memberships can also be added via [Organizational Identity Sources](https://spaces.at.internet2.edu/display/COmanage/Organizational+Identity+Sources) when connected to [Pipelines](https://spaces.at.internet2.edu/display/COmanage/Registry+Pipelines).

### Making an existing member an administrator

>> This needs to be vetted and screen shots are needed

1. From the COmanage Registry home page, click on your CO.
2. From the CO welcome page, click on the drop down menu for 'People' and select 'My Population'.
3. Select the member that you would like to make into a CO admin.
4. On the member's page, click on 'Manage Group Memberships'.
5. Select 'member' on the admin group line.
72 changes: 72 additions & 0 deletions _episodes/03-comanageGroups.md
@@ -0,0 +1,72 @@
---
title: "How & Why to Create Groups"
teaching: 20
exercises: 0
questions:
- "Question here"
objectives:
- "List the objectives"
keypoints:
- "List the key takeaways for the episode"
---

# Plan your groups

## Why you want to use groups

Groups are used for a variety of reasons, but generally they are used to manage permissions and access, or to manage contact lists. COmanage handles basic groups; for more complex group structures, Grouper integration is required.

## What you need to consider

CO Groups provide basic group functionality enabling actions to be applied to all members of the group at the same time, for example, granting access to an application, joining a mailing list, or expiring membership at the same time.

Some will require more sophisticated group management than what is available in COmanage. For these needs, COmanage can be connected to [Grouper](http://grouper.internet2.edu/) using the [Grouper Provisioning Plugin](https://spaces.at.internet2.edu/display/COmanage/Grouper+Provisioning+Plugin).

# Implement a group!

// NOTE: this section needs to be confirmed & screen shots added.


## Create a Group

![Interactive system activity](../assets/img/hands-on-keyboard.png)

**REQUIRED ROLE**: Platform Administrator (or maybe this is "Any CO Person?", at least by default.)

// NOTE: this section needs to be confirmed & screen shots added.

1. Login to the COmanage Registry and select your CO from the list.
2. Select 'All Groups' from the Group drop-down menu.
3. On the Groups page, select 'Add Groups', located above the Groups table.
4. Fill in the fields:
a. **The name of your Group.** This name will be displayed when your group is referenced. It is a good idea for this name to be descriptive, but relatively short.
b. **Description.** Write a short description of your group. This description will be helpful to users and future administrators to understand the purpose of the group.
c. **Open.** This is a check box to indicate whether anyone can join, or if users may only be added by the group owner. An open group is one that allows anyone to join. Participants can self-join, no administrator action is required. Memberships in a closed group can only be set by the group owner.
c. **Status.** There are three choices for the status:
* Active - you will select this one. Your group will be immediately active upon its creation.
* Suspended - Useful if you are not ready for your group to be active.
5. Click 'Add'.

# Group Members

A group member is simply a participant in the group. A group owner has permission to add and remove members to and from the group, including closed groups. A CO Person can be a member, and owner, both, or neither.

The CO Person who creates a CO Group is automatically set as both a member and owner of the new group.

## Add a Group Member

There are several ways to add individuals to groups. This may be done as part of the enrollment process, or it may be done after enrollment is complete and the individuals are already in the Registry. The instructions below assume enrollment has been completed and the individual is being added by a CO administrator to a new group.

1. Login to the COmanage Registry (if you haven't already) and select your CO from the list.
2. Select 'My Population' from the People drop-down menu.
3. Select a user and click on 'Manage Group Memberships'. This will show a list of available groups and you can add the individual as a group member or as a group owner by clicking on the appropriate box in the 'Actions' column.
4. Click 'Save'.

## Remove a Group Member

There are several ways to remove an individual from group membership, either by managing that individual directly (follow the directions for Adding a Group Member and click on the appropriate box to de-select that entry) or by managing the group as a whole. The instructions below assume direct group management instead of per-individual management.

1. Login to the COmanage Registry (if you haven't already) and select your CO from the list.
2. Select 'My Groups' from the Group drop-down menu.
3. Select the group you are changing (note that you must be an owner of that group to adjust membership).
4. Click on 'Delete' for each member you are removing from the group, and 'Remove' from the verification pop-up.
41 changes: 41 additions & 0 deletions _episodes/04-specialGroups.md
@@ -0,0 +1,41 @@
---
title: "Special Groups in COmanage"
teaching: 20
exercises: 0
questions:
- "Question here"
objectives:
- "List the objectives"
keypoints:
- "List the key takeaways for the episode"
---

## Admin Groups

Admin Groups are used to determine [Registry Administrators](https://spaces.at.internet2.edu/display/COmanage/Registry+Administrators). Admin Groups are automatically created when a CO or COU is created. The Platform Administrator typically sets the initial CO Administrator, and then the CO Administrators.

Since v2.0.0:

* The admin group is indicated by the group type GroupEnum::Admins and a null cou_id. The default name for the group is CO:admins.
* The admin groups for COUs are indicated by the group type GroupEnum::Admins and a non-null cou_id. The default name for COU admin groups is CO:COU:COU_Name:admins.

Prior to v2.0.0: <is this needed?>

* The admin group determines CO Administrators.
* Groups of the form admin:couname determine COU Administrators.

## Members Groups

Members Groups are automatic groups that are updated with all members of the CO or COU. Members Groups are automatically created and updated.

Since v2.0.0:

* Members of the CO in Active or Grace Period status are available in the group identified by the group type GroupEnum::ActiveMembers and a null cou_id. The default name for the group is CO:members:active.
* All members of the CO (except those in Deleted status) are available in the group identified by the group type GroupEnum::AllMembers and a null cou_id. The default name for the group is CO:members:all.
* Members of a given COU with an Active or Grace Period status role are available in the group identified by the group type GroupEnum::ActiveMembers and a non-null cou_id. The default name for the group is CO:COU:COU_Name:members:active.
* All members of a given COU (except those with only roles in Deleted status) are available in the group identified by the group type GroupEnum::AllMembers and a non-null cou_id. The default name for the group is CO:COU:COU_Name:members:all.

Prior to v2.0.0:

* The members group holds all CO People within the CO.
* Groups of the form members:couname hold all CO People with a role in the specified COU.

0 comments on commit 29bc834

Please sign in to comment.