Grouper Connector

1 Overview

Open source connector for Grouper that uses the ConnId Framework from Tirasa for integration with Identity and Access Management (IAM) systems such as 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 connector 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 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:

Item	Req’d	Description
Base URL	Yes	The base URL of the Grouper Web Service
Username	Yes	Username assigned to access the Grouper Web Service
Password	Yes	Password assigned to access the Grouper Web Service
Ignore SSL validation	No	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
Base stem	No	The stem (aka: folder) whose content is to be visible to this connector. The default is ":" indicating the whole tree.
Stem Attribute Names to Include	No	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.
Stems to Include	No	A set of regular expressions that the connector uses to determine whether a stem will be included in a query result.
Stems to Exclude	No	A set of regular expressions that the connector uses to determine whether a stem will be excluded from a query result
Group Attribute Names to Include	No	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.
Groups to Include	No	A set of regular expressions that the connector uses to determine whether a group will be included in a query result.
Groups to Exclude	No	A set of regular expressions that the connector uses to determine whether a group will be excluded from a query result
Subject Source	No	The sourceId of subjects in Grouper which will be visible by this connector.
Test Stem	No	If left blank the Base Stem will be used for testing the connector
Test Group	No	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

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 Operations

The grouper connector implements the following connId spi operations:

• SchemaOp - Allows the Connector to describe which types of objects the Connector manages on the target resource. This includes the options supported for each type of object.
• TestOp - Allows testing of the resource configuration to verify that the target environment is available. (ie. to validate the connection to the Grouper Web Service)
• SearchOp - Allows the connector to search the Grouper Web Service for resource objects.

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

Get All Groups

The get all groups query request recognizes the following parameters

Filter	Operation Options	Outcome
Null	Null	Returns all Groups in Base Stem. Includes group attributes, excludes members
Null	AttributesToGet = “member”	Returns all Groups in Base Stem including members and attributes

Get Group By Name

The get group by name recognizes the following parameters

EqualsFilter	Operation Options	Outcome
name=<Value>	Null	Returns a group. Includes group attributes, excludes members
name=<Value>	AttributesToGet = “member”	Returns a group including members and attributes

Get Group by UUID

The get group by UUID query recognizes the following parameters

EqualsFilter	Operation Options	Outcome
uuid=<Value>	Null	Returns a group identified by its grouper uuid. Includes group attributes, excludes members
uuid=<Value>	AttributesToGet = “member”	Returns a group identified by its grouper uuid including members and attributes

Get All Stems

The get all stems query returns all stems that are children of the configured base stem. It requires no filter or operation options. The outcome includes all the attributes of each stem returned.

Get Stem by Name

The get stem by name query typically returns a single grouper stem object with all of its attributes included.

EqualsFilter	Operation Options	Outcome
name=<Value>	Null	Returns a stem identified by its grouper name. Includes stem attributes

Get Stem By UUID

The get stem by uuid query typically returns a single grouper stem object with all of its attributes included.

EqualsFilter	Operation Options	Outcome
uuid=<Value>	Null	Returns a stem identified by its grouper uuid. Includes stem attributes

7 Connector Schema

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

Stem Objects

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

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

Group Objects

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

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.

8 Grouper Messages For Async Updates

The grouper system is capabile of sending messages that can notify the IAM system of changes to an object's state. With Midpoint you can implement the Asynchronous Update Connector as an additional connector in your Grouper Connector Resource Configuration. We have included a fragment in the artifacts folder that you can include in Grouper Connector Resource configuration to implement asynchronous updates.

The fragment calls a Function Library to process messages. The artifacts folder in this repository contains a function library you can use to process Grouper STEM messages

The Grouper System can provide the following event messages:

• ATTRIBUTE_ASSIGN_ADD
• ATTRIBUTE_ASSIGN_DELETE
• ATTRIBUTE_ASSIGN_VALUE_ADD
• ATTRIBUTE_ASSIGN_VALUE_DELETE
• STEM_ADD
• STEM_DELETE
• STEM_UPDATE
• GROUP_ADD
• GROUP_UPDATE
• GROUP_DELETE
• MEMBERSHIP_ADD
• MEMBERSHIP_UPDATE
• MEMBERSHIP_DELETE