Step-by-Step Guide to Creating Groups with the iamGroups Web Service

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.

MCommunity Directory Basics

The MCommunity Web Directory application allows for the management of user and group information. It is an application written in-house and supported by the Identity and Access Management team.

The purpose of the iamGroups web service is to allow you to do anything you can do with the Web Directory user interface.

The underlying database for the MCommunity Web Directory is an LDAP v3 compliant directory.

Users in the MCommunity directory (specifically, the MCommunity vault) are stored in ou=People,dc=umich,dc=edu, with a naming attribute of uid. The LDAP fully-qualified distinguished name of the user with the uniqname bjensen 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 is cn=iamGroupsWSTest1,ou=User Groups,ou=Groups,dc=umich,dc=edu.

Directory of APIs Setup

To call this web service, you will first need to join an organization, set up an application, and subscribe to the iamGroups web service in the Directory of APIs. More information about that setup is located in the API Overview.

Setup within MCommunity

After you subscribe to the iamGroups web service, you will receive a Client ID. You will then add the Client ID to the “Also Known As” field of the group which you want to own your other groups.

AKA field in Mcommunity

For example, if the group you want to own your other groups is called FakeDepartment-Owners, you would add the Client ID to the “Also Known As” field of this group.

Active Directory Synchronization

If you are interested in synchronizing groups from MCommunity to Active Directory, please see Synchronizing Groups from MCommunity (Google doc) to AD for additional setup and configuration steps.

Scripting Examples

The following Git repository contains scripting examples configured with the parameters necessary to pass to the Directory of APIs:

You can use the scripting examples along with the group modification example functionality (below) to modify groups.

Programming Notes

  • Data in POST request operations are always in JSON format.
  • 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 LDAP protocol is not case sensitive, so user and group fully-qualified distinguished names can appear in any combination of mixed case.

Example Functionality

Any time you want to add or remove a member, owner, etc., you must first read the memberDn attribute with the 'members' endpoint, add or remove the user(s) from it, then call the desired endpoint with the updated list of users.

For example, the member, moderator, and owner endpoints have this requirement.

  1. Find information for a group:
    Request method: GET
    url_endpoint: 'find/group/Your Group Name'

    This endpoint provides some, but not all, of the information for a group. For example, it does not provide the group's gid number. If you want to find the group's gid number, use the 'profile/dn' endpoint, described below.

     

  2. Find information for a group:
    Request method: GET
    url_endpoint: profile/dn/cn=Your Group Name,ou=User Groups,ou=Groups,dc=umich,dc=edu'

    Please note: This endpoint provides complete information for a group, including the group's gid number, which is located in the gidNumber attribute of the response.

     

  3. Get the members of a group:
    Request method: GET
    url_endpoint: 'members/cn=Your Group Name,ou=User Groups,ou=Groups,dc=umich,dc=edu'

    Please note: Call this endpoint to get the members of the group from the memberDn attribute of the response.

     

  4. Create a group:
    Request method: POST
    url_endpoint: 'api/create'
    data: '{"name":"iamGroupsWSTest1"}'

    Please note: Your group will be created with an expiration date one year into the future.

     

  5. Add members to a group:
    Request method: POST
    url_endpoint: ‘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"]}'

    Please note: This endpoint performs a replacement operation of the member attribute values.

     

  6. Add moderators to a group:
    Request method: POST
    url_endpoint: ‘update/moderator’
    data: ‘{“dn”:”cn=<your group name>,ou=user groups,ou=groups,dc=umich,dc=edu", “moderator”: [{”email”:”someone@google.com”},{“email”:”someone@yahoo.com”, “name”:”someone”} ]}’

    Please note: Do not try to add the name element without the email element, as this will not create a valid moderator value.

     

  7. Add owners to a group:
    Request method: POST
    url_endpoint: ‘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"]}’

     

Doing More with the Swagger Document

You can use the Swagger document to do a lot more with the iamGroups web service.

Swagger is a tool which allows our IAM developers to document the capabilities of the iamGroups web service with you without having to maintain separate sets of code and documentation. The Swagger document for the iamGroups web service is here.

For example, if you wanted to find group members in a particular group, you would search the Swagger document for the word “member”. Then, you would expand the selection “/api/members/{dn}” in the document. The document tells you that this endpoint requires a GET request method, and it further tells you the type of data which it expects to be passed to it.

For example, to find a group:

Request method: GET
url_endpoint: 'members/cn=Your Group Name,ou=User Groups,ou=Groups,dc=umich,dc=edu'

If you’re using the scripts included in this document, remember to use the GET script. Additionally, in the case of GET endpoints, data is appended to the URL, so the value of the data must be URL-encoded.

If you were attempting to call the iamGroups web service from a web browser, the URL would look like this:
https://iam-groups-test.dsc.umich.edu/iamGroups/api/members/cn%3D%3Cyour%20group%20name%3E%2Cou%3Duser%20groups%2Cou%3Dgroups%2Cdc%3Dumich%2Cdc%3Dedu

Last Updated: 
Monday, October 11, 2021