Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
initial info
lpaglione committed Nov 10, 2019
1 parent 03ddce3 commit ab6bbe5
Showing 3 changed files with 265 additions and 0 deletions.
224 changes: 224 additions & 0 deletions _episodes/01-prep.md
View file
@@ -0,0 +1,224 @@
---
title: "Installation Prep"
teaching: 25
exercises: 10
questions:
- "Question here"
objectives:
- "List the objectives"
keypoints:
- "List the key takeaways for the episode"
workshopOverviewName: "COmanage Workshop: Managing Identities & Collaborations"
workshopOverviewURL: "https://github.internet2.edu/lpaglione/COmg-trainingOverview/blob/master/README.md"
lessonOverviewName: "CO201 - Installing COmanage Using Docker Images"
lessonOverviewURL: "../index.md"
previousEpisodeName:
previousEpisodeURL:
nextEpisodeName: 2. Setting up variables"
nextEpisodeURL: "/_episodes/02-setupVariables.md"
---

# 1. Installation Prep

For this lesson, we will be installing COmanage from a Docker image onto a virtual machine that we have set up for this training. What you set up here will be available to you for 2 weeks after the workshop.

## VM & user assignments

At your station is a Workshop Reference Document that lists a virtual machine number and a list of three "users" that you will be using throughout the workshop as we explore COmanage. Each one of us has a different set.

Also on this Document is the password that we will be using for the workshop. This password will be used for every instance where a password is needed.

## Sign into your virtual machine

You will be using SSH to sign into your virtual machine. If you run into challenges during this process, please put a yellow post-it note on your computer so that we can see that you need help.

1. SSH to the [AWS bastion host](https://aws.amazon.com/blogs/security/tag/bastion-host/) by typing the following command:

``` bash
ssh training@ssh.comanage.incommon.training
```

You will use the training session password when requested. As a reminder, you can find the password on the Workshop Reference Document.

2. Once on the bastion host, SSH into the virtual machine that you will be using for the workshop. Refer to the Workshop Reference Document to see the name of your virtual host. You will replace the letter 'N' in the command below, with the number for your virtual machine.

``` bash
ssh registryN-private
```

3. The docker files are already available to you, so you can run a few docker commands to check them.

First we'll see what docker nodes are available:

``` bash
docker node ls
```

which should result in something that looks like this:

``` bash
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION
8tuwrbfdci97tfn9nqoinic0o * registry1-private.comanage.incommon.training Ready Active Leader 19.03.4
```

You can also see the list of containers that are available by running the docker ps command. (NOTE, there shouldn't be any Docker containers because we haven't set them up yet. This command will confirm that this is true.)

``` bash
docker ps
```

which should result in just showing the headers for the list of containers. It will look something that looks like this

``` bash
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
```

_NOTE: You can also use `sudo` without a password, but you probably will not need it in this session. For example,_

``` bash
[training@registry1-private ~]$ sudo /usr/bin/whoami
root
```

When you are ready to move on, put the blue post-it note on your computer so that we can make sure to not move forward before everyone is ready.

# Hands on - Defining **Identifier Assignments** for a **CO Unique Identifier**

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

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`:gear: in our `CO`:gear:.

## Sign into the Registry

1. Using the credentials you specified as part of the COmanage setup (or the `CO Administrator`:crown: that you established in the last section), sign into the system.
2. Navigate to your `CO`:gear:. If necessary, select your `CO`:gear: by selecting **Collaborations** from the menu on the left, and then selecting your Collaboration.

## Navigate to the Identifier Assignment List

**REQUIRED ROLE**: `CMP Administrator`:crown: **OR** `CO Administrator`:crown:

3. Select the **Configuration** menu pick from the left menu to display the CO configuration list.
4. Select the "Identifier Assignments" link to display the Identifier Assignments list.

## Create a new **Identifier Assignment** rule

**REQUIRED ROLE**: `CMP Administrator`:crown: **OR** `CO Administrator`:crown:

5. Click the **Add Identifier Assignment** link above the table to display the configuration form.
* **Description** - Add a description for this rule that describes why it is being created. In this case, we'll use something like, "Identifier Assignment rule for general CO Unique Identifier"
* **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".
* **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))_
* **Algorithm** - The numbering method that will be used for Collision Numbers. Here you will choose between sequential and random numbering. For this example, let's use sequential so that it is easier to see how they are working.
* **Format** - 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.
* **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".
* **Minimum**: For random collision numbers (algorithm), the minimum value that may be assigned. For Sequential identifiers, the first value to be assigned.
* **Maximum**: For random collision numbers (algorithm), the maximum value that may be assigned.

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

# Hands on - Manually assign identifiers

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

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

7. Navigate back to the Identifier Assignments rules list. (You are probably there already after adding your new rule!).
8. Click the **Autogenerate Identifiers For All** link that appears above the table to initiate the process of assigning identifiers for all of the active `CO Persons`:gear:. Confirm that you want to initiate this process. This action will start a `Job`:factory: that will process the request. (we will talk more about jobs in a later lesson.)

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.

# A note about `Identifier`:gear: validation

By default, COmanage accepts identifiers of any format, as long as they are unique for a given type within a `CO`:gear:. That is, two `CO People`:gear: within the same `CO`:gear: 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 the Registry 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`: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.

This last item is important to understand, especially in a multi-tenant environment. When a person authenticates to COmanage Registry, it is expected that they are using an external or federated identity mechanism. The identifier returned by the authentication system is looked up in the list of `Identifiers`:gear: stored for `Org Identities`:gear:. If a corresponding identifier is found _that is enabled for login_, then that identifier is permitted to log in to the platform. The `Org Identity`:gear: that the `Identifier`:gear: is attached to is checked for its matching `CO Person`:gear:. When there is a match, the individual is signed into COmanage as that matching `CO Person`:gear:.

**When there are multiple `COs`:gear: in the platform** it is possible that someone's sign in `Identifer`:gear: is linked to `CO Person`:gear: objects in mutile `COs`:gear:. When this situation happens, the individual will have access to all `COs`:gear: 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`:gear:. If different organizations or collaborations expect to use different authentication systems, they cannot share the same platform.

## Use for provisioning

We recommend that `COs`:gear: 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`:gear: 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`:gear: 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](https://spaces.at.internet2.edu/display/COmanage/Understanding+Registry+People+Types) 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 :gear:

OBJECT | DESCRIPTION | Introduced in
------ | ----------- | -------------
`Identifier`:gear: | 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`:gear: | Services or applications that can be configured for `CO Persons`:gear: to have access to by participating in the organization or collaboration. | [CO330-02](/_episodes/02-coServices.md)
. | ****** CO320 - Modeling Your Organization in COmanage ****** | .
`CO`:gear: | 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](https://github.internet2.edu/lpaglione/COmg-CO320-modelOrg/blob/master/_episodes/01-co.md)
`COU`:gear: | 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](https://github.internet2.edu/lpaglione/COmg-CO320-modelOrg/blob/master/_episodes/02-cous.md)
`CO Group`:gear: | A specific COmanage organizational structure for representing certain collections of `CO Persons`:gear: | [CO320-03](https://github.internet2.edu/lpaglione/COmg-CO320-modelOrg/blob/master/_episodes/03-groups.md)
`CO Department`:gear: | 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](https://github.internet2.edu/lpaglione/COmg-CO320-modelOrg/blob/master/_episodes/04-departments.md)
. | ****** CO310 - Modeling People in COmanage ****** | .
`CO Person`:gear: | The representation of a person in COmanage | [CO310-01](https://github.internet2.edu/lpaglione/COmg-CO310-modelPeople/blob/master/_episodes/01-COperson.md)
`CO Group`:gear: | A specific COmanage organizational structure for representing certain collections of `CO Persons`:gear: | [CO320-03](https://github.internet2.edu/lpaglione/COmg-CO320-modelOrg/blob/master/_episodes/03-groups.md)
`Identity Source`:gear: | Information about a person as obtained from an external source such as LDAP, netFORUM or ORCID | [CO310-02](https://github.internet2.edu/lpaglione/COmg-CO310-modelPeople/blob/master/_episodes/02-orgIdentity.md)
`Identity Source Records`:gear: | COmanage's cached value of the values at the source | [CO310-02](https://github.internet2.edu/lpaglione/COmg-CO310-modelPeople/blob/master/_episodes/02-orgIdentity.md)
`CO Person Role`:gear: | 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 :gear: `CO Person` objects; there may be any number of Roles. | [C0310-04](https://github.internet2.edu/lpaglione/COmg-CO310-modelPeople/blob/master/_episodes/04-permissions.md)

## CO Person Roles :crown:

ROLE | DESCRIPTION | Introduced in
---- | ----------- | -------------
. | ****** CO320 - Modeling Your Organization in COmanage ****** | .
`CMP Administrators`:crown: | CMP Administrators are effectively super users, with the ability to perform almost all operations on the platform. | [CO320-01](https://github.internet2.edu/lpaglione/COmg-CO320-modelOrg/blob/master/_episodes/01-co.md)
`CO Administrators`:crown: | `CO`:gear: Administrators are super users _within a CO_. These individuals belong to the CO:admins group of the `CO`:gear:. | [CO320-01](https://github.internet2.edu/lpaglione/COmg-CO320-modelOrg/blob/master/_episodes/01-co.md)
`System Administrators`:crown: | System Administrators have privileges that enable them to maintain the COmanage application. | [CO320-01](https://github.internet2.edu/lpaglione/COmg-CO320-modelOrg/blob/master/_episodes/01-co.md)
`COU Administrators`:crown: | Individuals that have the ability to perform lifecycle management operations on the `CO People`:gear: who have `CO Person Roles`:gear: associated with the `COU`:gear:. | [CO320-02](https://github.internet2.edu/lpaglione/COmg-CO320-modelOrg/blob/master/_episodes/02-cous.md)

## Worksheets

WORKSHEET | DESCRIPTION | Introduced in
--------- | ----------- | -------------
. | ****** CO320 - Modeling Your Organization in COmanage ****** | .
[Modeling Organization :memo:](/files/handouts/CO320-ModelingOrgs.pdf) | Planning sheet used in this lesson for understanding how the parts of the COmanage Organization fit together | [CO320](https://github.internet2.edu/lpaglione/COmg-CO320-modelOrg/blob/master/index.md)
[CO Planning Worksheet :memo:](/files/handouts/CO320-01_COPlanningWorksheet.pdf) | Planning worksheet for creating your CO(s). Contains all of the configuration sections at a glance | [CO320-01](https://github.internet2.edu/lpaglione/COmg-CO320-modelOrg/blob/master/_episodes/01-co.md)
[COU Planning Worksheet :memo:](/files/handouts/CO320-02_COUPlanningWorksheet.pdf) | Planning worksheet for creating your CO(s). Contains all of the configuration sections at a glance. | [CO320-02](https://github.internet2.edu/lpaglione/COmg-CO320-modelOrg/blob/master/_episodes/02-cous.md)
[CO Group Planning Worksheet :memo:](/files/handouts/CO320-03_COGroupPlanningWorksheet.pdf) | Planning worksheet for creating your CO Group(s). Contains all of the configuration sections at a glance. | [CO320-03](https://github.internet2.edu/lpaglione/COmg-CO320-modelOrg/blob/master/_episodes/03-groups.md)
. | ****** CO310 - Modeling People in COmanage ****** | .
[ 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 | [CO310](https://github.internet2.edu/lpaglione/COmg-CO310-modelPeople/blob/master/index.md)

---

NEXT SECTION: [2. `CO Services`:gear: ](/_episodes/02-coServices.md)

---

LESSON OVERVIEW: [CO330 - Linking to Systems Outside of COmanage](../index.md)

WORKSHOP OVERVIEW: [COmanage Workshop: Managing Identities & Collaborations](https://github.internet2.edu/lpaglione/COmg-trainingOverview/blob/master/README.md)
41 changes: 41 additions & 0 deletions index.md
View file
@@ -0,0 +1,41 @@
---
layout: lesson
root: .
---

# CO201: Installing COmanage Using Docker Images

In this lesson, you will learn how to install COmanage and configure it for basic use.

**WHO IS THIS COURSE FOR?** System administrators.

> ## Prerequisites
> [CO101: Getting to Know COmanage](https://github.internet2.edu/lpaglione/COmg-CO101-intro) or equivalent
> ## Top Things You Need To Know
>
> 0. More things you need to know will be added later
## Schedule

Time | Section | Description
---- | ------- | -----------
  | [Setup](/setup/) | Prepare for the lesson
00:35 | [1. Identifiers](/_episodes/01-identifiers) | Learn the importance of identifiers within COmanage and their use when connecting to other systems as sources or for provisioning. Understand identifier formats and how to make identifier assignments to `CO Persons`:gear:
00:20 | [2. `CO Services`:gear: ](/_episodes/02-coServices.md) | Configure a group of services that can be accessed by those in your `CO`:gear:
00:30 | [3. Authenticators](/_episode/03-authenticators) | Learn how authenticators work to enable authenticated access to services. Understand what kinds are supported, and how alternate forms, like SSH keys, are supported.

_The actual schedule may vary slightly depending on the topics and exercises chosen by the instructor._

1. [1. Installation Prep](/_episodes/01-prep.md) | Get familiar with the process and understand what will be different when you install in your own environment.
2. [2. Setting up variables](/_episodes/02-setupVariables.md) | Using the stack file (compose file), set variables that you will need for initial configuration of COmanage.
3. [3. Deploy COmanage](/_episodes/03-deploy.md) | Deploy COmanage on your virtual machine
4. [4. First sign in](/_episodes/04-signin.md) | Sign into COmanage.

---

PREVIOUS LESSON: [CO101 - Getting to Know COmanage](https://github.internet2.edu/lpaglione/COmg-CO101-intro/blob/master/index.md)

NEXT LESSON: [CO310 - Modeling People in COmanage](https://github.internet2.edu/lpaglione/COmg-CO310-modelPeople/blob/master/index.md)

WORKSHOP OVERVIEW: [COmanage Workshop: Managing Identities & Collaborations](https://github.internet2.edu/lpaglione/COmg-trainingOverview/blob/master/README.md)
0 episodes/setup.md → setup.md
View file
File renamed without changes.

0 comments on commit ab6bbe5

Please sign in to comment.