Skip to content

Commit

Permalink
Initial commit for Grouper V1.0.X
Browse files Browse the repository at this point in the history
  • Loading branch information
@sfox
sfox committed Oct 15, 2021
1 parent c869dcf commit 44fa66e
Show file tree
Hide file tree
Showing 2 changed files with 341 additions and 13 deletions.
352 changes: 340 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,343 @@
# midPoint-Grouper_connector
This is a connector that can read groups from a Grouper instance using REST calls.
Currently it supports these searches only:
- fetching all groups,
- fetching a group by name,
- fetching a group by UUID.

When fetching a group, a client can choose whether to get basic group data only (name, UUID, extension) or whether
to obtain a list of group members as well.
# Grouper Connector

Besides `search` operation the following ones are supported:
- `schema`
- `test`

This connector was tested with Grouper 2.4.
# 1 Overview

Open source connector for [Grouper](https://incommon.org/software/grouper/) that uses the [ConnId Framework from Tirasa](http://connid.tirasa.net/) for integration with Identity and Access Management (IAM) systems such as [Midpoint](https://evolveum.com/midpoint/).

The Grouper software enables project managers, departments, institutions and end users to create and manage institutional and personal groups, roles and permissions. It simplifies access management by maintaining a repository that lets you use the same group or role in many places in your organization.

This connector allows an IAM system to retrieve information from Grouper for automated provisioning of users, groups, systems, and services.

The current release is based on version 0.7 developed by Evolveum and Internet2. It was tested with Midpoint 4.2 and Grouper 2.4 and 2.5


# 2 Features

The grouper connector has the following features:



* The connector configuration is specified in the user interface
* The connectory supports two Types related to Grouper. These are Group Objects and Stem objects. A Stem object is also known within grouper as a folder.
* A Stem object has attributes and may contain child stems or child groups.
* A Group object has attributes and may contain members also known as subjects
* The connector retrieves and filters stems and groups which are children of the configured base stem
* The connector supports queries that retrieve an object by UUID or fully qualified name.
* Group object queries can be specified to include or exclude its members
* The connector retrieves all attribute assignments for Stems and Groups by default
* The connector retrieves all attribute assignment for a stem or group in a JSON formatted ARRAY of name/value pairs
* You can customize individual attribute names to import with stems or groups
* Attribute name customization is configurable separately for stems and groups
* Attribute name customization updates the schema of a stem object type or a group object type.
* The connector supports and was unit tested with attributes assignments that are NULL, Single Valued, or MultiValued
* The connector does not support and excludes AssignmentsOnAssignments
* The connector does not import attribute assignments that are disabled (ie time limited)
* The connector regards all attribute assignment values as strings
* The connector converts a multivalued attribute assignment into a single comma separated string
* The connector does not prevent import of an individual grouper stem or group if the uuid or fully qualified name is known to midpoint.


# 3 Getting Started

To begin using the connector you should have a [Grouper Web Service](https://spaces.at.internet2.edu/display/Grouper/Grouper+Web+Services) instance up and running. Such instances typically employ the SSL protocol over HTTPS with basic authentication.

Once you have acquired access to a Grouper instance you are ready to configure your connector. With Midpoint you must first copy the connector jar file to the **<MIDPOINT_HOME>/icf-connectors** directory.


# 4 Connector Configuration

The actual method of configuring a connector is largely dependent on the interface(s) provided by your Identity and Access management system. The configuration parameters are specified as follows:


<table>
<tr>
<td><strong>Item</strong>
</td>
<td><strong>Req’d</strong>
</td>
<td><strong>Description</strong>
</td>
</tr>
<tr>
<td>Base URL
</td>
<td>Yes
</td>
<td>The base URL of the Grouper Web Service
</td>
</tr>
<tr>
<td>Username
</td>
<td>Yes
</td>
<td>Username assigned to access the Grouper Web Service
</td>
</tr>
<tr>
<td>Password
</td>
<td>Yes
</td>
<td>Password assigned to access the Grouper Web Service
</td>
</tr>
<tr>
<td>Ignore SSL validation
</td>
<td>No
</td>
<td>When set to true the connector will validate whether the Grouper REST service is accessed through a valid SSL connection. Whether to ignore SSL validation of the base URL
</td>
</tr>
<tr>
<td>Base stem
</td>
<td>No
</td>
<td>The stem (aka: folder) whose content is to be visible to this connector. The default is ":" indicating the whole tree.
</td>
</tr>
<tr>
<td>Stem Attribute Names to Include
</td>
<td>No
</td>
<td>Custom attribute names to be included with the “Stem” object class. By default all attributes of a stem are included in an attribute named “attributesJSON”. By populating this configuration item you can break out each individual attribute as needed to avoid parsing the JSON format.
</td>
</tr>
<tr>
<td>Stems to Include
</td>
<td>No
</td>
<td>A set of regular expressions that the connector uses to determine whether a stem will be included in a query result.
</td>
</tr>
<tr>
<td>Stems to Exclude
</td>
<td>No
</td>
<td>A set of regular expressions that the connector uses to determine whether a stem will be excluded from a query result
</td>
</tr>
<tr>
<td>Group Attribute Names to Include
</td>
<td>No
</td>
<td>Custom attribute names to be included with the “Group” object class. By default all attributes of a group are included in an attribute named “attributesJSON”. You can avoid parsing the JSON format by populating this configuration item to break out each individual attribute as needed.
</td>
</tr>
<tr>
<td>Groups to Include
</td>
<td>No
</td>
<td>A set of regular expressions that the connector uses to determine whether a group will be included in a query result.
</td>
</tr>
<tr>
<td>Groups to Exclude
</td>
<td>No
</td>
<td>A set of regular expressions that the connector uses to determine whether a group will be excluded from a query result
</td>
</tr>
<tr>
<td>Subject Source
</td>
<td>No
</td>
<td>The sourceId of subjects in Grouper which will be visible by this connector.
</td>
</tr>
<tr>
<td>Test Stem
</td>
<td>No
</td>
<td>If left blank the Base Stem will be used for testing the connector
</td>
</tr>
<tr>
<td>Test Group
</td>
<td>No
</td>
<td>The name of an existing Grouper group that will be accessed to test the connector. For example: “etc:sysadmingroup” If left blank a test for groups will not be performed. Such an omission is not critical
</td>
</tr>
</table>


When adding or removing a custom attribute it may be necessary to refresh the connector schema such that the access management system can obtain the new information.


# 5 Connector Query Capabilities

As of version 1.01 the grouper connector provides read only access to a grouper repository. It is possible to create multiple resource connector instances for a Midpoint installation. In this case the Base Stem configuration provides a top level filter that allows you to establish the root branch in the grouper repository tree. So a query all on the connector will return all stems or all groups that are children of the base stem.

With this in mind the connector can perform the following queries:



* Fetching all groups that are children of the base stem.
* Fetching a group by name.
* Fetching a group by UUID.
* Fetch all stems that are children of the base stem.
* Fetch a stem by Grouper name.
* Fetch a stem by Grouper UUID.

When fetching a Group by name or UUID the system may choose to include the list of members. In all cases the attribute assignments of groups objects and stem objects will be included in the result.


# 6 Connector Schema

As mentioned in an earlier section, the grouper connector supports 2 object classes. These are Group Objects and Stem Objects.


## Stem Objects


<table>
<tr>
<td><strong>Attribute </strong>
</td>
<td><strong>Type</strong>
</td>
<td><strong>Comment</strong>
</td>
</tr>
<tr>
<td>name
</td>
<td>String
</td>
<td>The Grouper assigned path of the stem/folder
</td>
</tr>
<tr>
<td>uuid
</td>
<td>String
</td>
<td>The Grouper assigned uuid of the stem/folder
</td>
</tr>
<tr>
<td>extension
</td>
<td>String
</td>
<td>The last part of the Grouper path. Also known as the folder name.
</td>
</tr>
<tr>
<td>description
</td>
<td>String
</td>
<td>The description of the Grouper folder
</td>
</tr>
<tr>
<td>attributesJSON
</td>
<td>JSON
</td>
<td>A JSON formatted map of name value pairs containing the attribute assignments for the stem
</td>
</tr>
</table>


As discussed in the section on connector configuration you can extend the stem schema by adding attribute assignments from grouper.


## Group Objects


<table>
<tr>
<td><strong>Attribute </strong>
</td>
<td><strong>Type</strong>
</td>
<td><strong>Comment</strong>
</td>
</tr>
<tr>
<td>name
</td>
<td>String
</td>
<td>The Grouper assigned path of the group
</td>
</tr>
<tr>
<td>uuid
</td>
<td>String
</td>
<td>The Grouper assigned uuid of the group
</td>
</tr>
<tr>
<td>extension
</td>
<td>String
</td>
<td>The last part of the Grouper path. Also known as the group name.
</td>
</tr>
<tr>
<td>description
</td>
<td>String
</td>
<td>The description of the group
</td>
</tr>
<tr>
<td>attributesJSON
</td>
<td>JSON
</td>
<td>A JSON formatted map of name value pairs of the attribute assignments for the group
</td>
</tr>
<tr>
<td>member
</td>
<td>Array
</td>
<td>A string array of subjects whose Subject Source is specified in the connector configuration
</td>
</tr>
</table>


As discussed in the section on connector configuration you can extend the group schema by adding attribute assignment names. When the group has the assigned attribute name contained in the attributesJSON field it will be broken out into its own attribute.


# 7 Grouper Messages

The following are Grouper Messages that may be processed by the Asynchronouse Update Connector

* ATTRIBUTE_ASSIGN_ADD
* ATTRIBUTE_ASSIGN_DELETE
* ATTRIBUTE_ASSIGN_UPDATE
* STEM_ADD
* STEM_DELETE
* STEM_UPDATE
* GROUP_ADD
* GROUP_UPDATE
* GROUP_DELETE
* MEMBERSHIP_ADD
* MEMBERSHIP_UPDATE
* MEMBERSHIP_DELETE
2 changes: 1 addition & 1 deletion src/main/java/com/evolveum/polygon/connector/grouper/rest/GroupProcessor.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -804,7 +804,7 @@ ObjectClassInfoBuilder buildStemSchema()

/**
* Test whether members are to be returned with a Group request
* @param options The options to be evaluated to determine whether members are to be included
* @param options The options to be evaluated to determine whether members are to be included
* @return true when members are required to be included in a group Object
*/
private boolean isGetMembers(OperationOptions options)
Expand Down

0 comments on commit 44fa66e

Please sign in to comment.