Working with MCommunity Groups Using the IAM Groups (iamGroups) Web Service API

This document provides information about the iamGroups Application Programming Interface (API)/Web Service. The iamGroups API is a web service that IT professionals can use to create and edit MCommunity groups. This document assumes a basic understanding of the U-M API Directory. See the API Directory Help page for information.

Contents

About iamGroups

The IAM Groups (iamGroups) API is a web service that IT professionals can use to create and edit MCommunity groups. It can do all the same things that a group owner can do in the MCommunity Directory via the web. You must be an owner of an MCommunity group to edit it.

The API is restricted to 200 calls per minute. The iamGroups API supports JSON (JavaScript Object Notation).

Check the ITS Service Status page to stay informed about potential outages of this web service.

First, Get Set Up in the API Directory

To call this web service, you will first need to join an organization, set up an application, and subscribe to iamGroups in the API Directory.

  1. Join a developer organization. See API Directory: Getting Started for details.
  2. Log in to the API Directory with your uniqname and UMICH (Level-1) password.
  3. Register your application with the API Directory by adding it as a new application.
  4. Note the Client ID and Client Secret when you are creating the application. You will need them later.
    • You'll need the Client ID to connect your application to your MCommunity groups.
    • You'll need to include the Client Secret in the header payload when you call the iamGroups API.
  5. Find iamGroups. In the API Directory, use the search box to search for iamGroups.
  6. Subscribe to iamGroups by selecting your application in the list.

After you subscribe to iamGroups and are approved, you will need the following four things from the API:

Then Connect it to Your MCommunity Groups

Create an MCommunity group to serve as the owner of all the groups you want to work with using iamGroups. You will add your Client ID to that group to connect them.

  1. Create an MCommunity group to own the groups. Set the owning group so that anyone can view the members. This gives the API the access it needs.
  2. Edit the owning group. In the Also Known As section of that group's profile, add the Client ID you got when you registered your application with the API Directory.
  3. Update your existing groups. Add the new group as an owner of each of the groups you want to work with using the API.

Optional: Active Directory Synchronization

To synchronize groups from MCommunity to Active DIrectory, you'll need to request an MCommunity control group from the ITS Service Center and add the groups you want to synchronize to it.

  1. Request a control group in the MCommunity Directory for Active Directory group synchronization by contacting the ITS Service Center. This is a special kind of group that will add the needed umichServiceEntitlement attribute to any subgroup you add to it as a member. This attribute synchronizes the subgroup to Active Directory (UMROOT).
  2. To add the subgroup to the control group programmatically, use the iamGroups API/web service, and call the /api/update/groupMember endpoint.

See Example 5 in the Group Management Examples section below for an illustration of how this is done.

Group Management Examples

The following examples show you how to create and edit MCommunity groups with the iamGroups API/web service.

  1. Create a Group
    Request method: POST
    url_endpoint: api/create
    Data: {"name":"your group name"}
  2. Add Members to a Group
    Request method: POST
    url_endpoint: api/update/member
    Data: {"dn":"cn=<your group name>,ou=user groups,ou=groups,dc=umich,dc=edu", "memberDn":["uid=uniqname,ou=people,dc=umich,dc=edu","uid=uniqname,ou=people,dc=umich,dc=edu"]}
  3. Add Moderators to a Group
    Request method: POST
    url_endpoint: api/update/moderator
    Data: {“dn”:”cn=<your group name>,ou=user groups,ou=groups,dc=umich,dc=edu", “moderator”: [{”email”:”username@domain.extension”},{“email”:”username@domain.extension”,“name”:”username”} ]}
    Do not add the name element without the email element; this will not create a valid moderator value.
  4. Add Owners to a Group
    Request method: POST
    url_endpoint: api/update/owner
    Data: {"dn":"cn=<your group name>,ou=user groups,ou=groups,dc=umich,dc=edu", "ownerDn":["cn=<your group name>,ou=user groups,ou=groups,dc=umich,dc=edu","uid=uniqname,ou=people,dc=umich,dc=edu"]}
  5. Add Subgroups to a Control Group
    Request method: POST
    url_endpoint: api/update/groupMember
    Data: {"dn":"cn=<your control group name>,ou=user groups,ou=groups,dc=umich,dc=edu", "memberGroupDn":["cn=<your subgroup name>,ou=user groups,ou=groups,dc=umich,dc=edu"]}

Scripting Examples

Scripting examples are available for you to use, along with the group management examples above, to help you use iamGroups to work with your groups.

Programming Notes

  • Data in POST request operations are always in JSON format.
  • The Client ID and Client Secret always need to be in the header when calling the web service.
  • If you are trying to automate group operations, you will need to append uniqnames and group names with the ou=People,dc=umich,dc=edu and ou=User Groups,ou=Groups,dc=umich,dc=edu organizational units.
  • The Lightweight Directory Access Protocol (LDAP) is not case sensitive. User and group fully-qualified distinguished names can appear in any combination of mixed case.
  • The underlying database for the MCommunity Directory is an LDAP v3 compliant directory. For more about LDAP and MCommunity, see LDAP Access to the MCommunity Directory.
  • People profiles in the MCommunity Directory are stored in ou=People,dc=umich,dc=edu with a naming attribute of uid. The LDAP fully-qualified distinguished name of the person with the uniqname bjensen, for example, is uid=bjensen,ou=People,dc=umich,dc=edu.
  • Groups in the MCommunity Directory are stored in ou=User Groups,ou=Groups,dc=umich,dc=edu with a naming attribute of cn (common name). The LDAP fully-qualified distinguished name of a group with the name iamGroupsWSTest1, for example, would be cn=iamGroupsWSTest1,ou=User Groups,dc=umich,dc=edu.

Doing More with the iamGroups API/Web Service

The API Directory has plenty of examples on how to call additional endpoints of the iamGroups web service. Click an endpoint in the API Directory to see how to call it. To save yourself time, remember to take note of whether the endpoint uses GET or PUT.

Screen shot of viewing endpoint information in the API Directory

Last Updated: 
Friday, February 1, 2019