Skip to content

group.md

Latest commit

 

History

History
216 lines (142 loc) · 8.91 KB

group.md

File metadata and controls

216 lines (142 loc) · 8.91 KB

Group and Group Membership Management API

This document describes the API for managing groups and group members.

Groups in EDI IAM

Groups provide a way to manage permissions for collections of users, simplifying access control by allowing you to grant permissions to multiple users at once rather than managing individual ACRs for each user.

A group is a named collection of user profiles, each identified by their EDI-ID. Groups themselves are also identified by EDI-IDs, allowing them to be treated as principals in the authorization system. When you create a group, you give it a title and description, then add user profiles as members.

Groups can be used as principals in Access Control Rules. Instead of creating separate ACRs for each user who needs access to a resource, you:

  1. Create a group (e.g., "LTER Scientists")
  2. Add user profiles to the group
  3. Create a single ACR granting the group access to the resource

Now all members of the group automatically have that permission.

How Groups Work with ACRs

When evaluating authorization, the IAM system checks not only the user's direct ACRs but also ACRs granted to any groups the user belongs to. If a group has read permission on a resource, every member of that group can read that resource.

Users can belong to multiple groups, and the system checks all of them during authorization. If any group the user belongs to has the required permission, access is granted.

Group Management

Creating Groups: Any user can create new groups.

Managing Group Details: Groups have a title and description that can be updated by anyone with write permission on the group. Like resources, groups themselves can have ACRs that control who can modify the group or manage its membership.

Managing Membership: Adding or removing members requires write permission on the group.

Group Permissions Model: Groups themselves are treated like resources in the permission system:

  • read permission: View group details and member list
  • write permission: Modify group title/description and manage membership
  • changePermission permission: Manage ACRs on the group itself

Create Group

POST /auth/v1/group

Create a new group of EDI user profiles.

Required permission: Caller must be in the Vetted system group.

Parameters

Parameter In Required Description
edi-token Cookie Yes See Parameters
title JSON body Yes Title of the group
description JSON body Yes Description of the group

Response

Status Description
200 OK Group created successfully; response body includes the group's EDI-ID
401 Unauthorized See Parameters
403 Forbidden Caller is not in the Vetted group

Read Group

GET /auth/v1/group/<group_edi_id>

Retrieve the title, description, and member list of a group.

Required permission: Caller must have read permission on the group.

Parameters

Parameter In Required Description
edi-token Cookie Yes See Parameters
group_edi_id URL path Yes EDI-ID of the group

Response

Status Description
200 OK Group details retrieved successfully
401 Unauthorized See Parameters
403 Forbidden Caller does not have read permission
404 Not Found Group not found

Update Group

PUT /auth/v1/group/<group_edi_id>

Modify the title and/or description of a group.

Required permission: Caller must have write permission on the group.

Parameters

Parameter In Required Description
edi-token Cookie Yes See Parameters
group_edi_id URL path Yes EDI-ID of the group
title JSON body No New title for the group
description JSON body No New description for the group

Response

Status Description
200 OK Group updated successfully
401 Unauthorized See Parameters
403 Forbidden Caller does not have write permission
404 Not Found Group not found

Delete Group

DELETE /auth/v1/group/<group_edi_id>

Delete an EDI group.

Required permission: Caller must have write permission on the group.

Parameters

Parameter In Required Description
edi-token Cookie Yes See Parameters
group_edi_id URL path Yes EDI-ID of the group

Response

Status Description
200 OK Group deleted successfully
401 Unauthorized See Parameters
403 Forbidden Caller does not have write permission
404 Not Found Group not found

Add Group Member

POST /auth/v1/group/<group_edi_id>/<profile_edi_id>

Add an EDI user profile to a group. If the profile is already a member, returns 200 OK with a message indicating it was already a member.

Required permission: Caller must have write permission on the group.

Parameters

Parameter In Required Description
edi-token Cookie Yes See Parameters
group_edi_id URL path Yes EDI-ID of the group
profile_edi_id URL path Yes EDI-ID of the profile to add

Response

Status Description
200 OK Profile added to group, or was already a member
401 Unauthorized See Parameters
403 Forbidden Caller does not have write permission
404 Not Found Group or profile not found; response body indicates which EDI-ID was not found

Example

Request:

curl -X POST https://auth.edirepository.org/auth/v1/group/EDI-99cda3eb50ab4699971c99c55c11a15f/EDI-1234567890abcdef1234567890abcdef \
  -H "Cookie: edi-token=$(<~/Downloads/token-EDI-<my-token>.jwt)"

Remove Group Member

DELETE /auth/v1/group/<group_edi_id>/<profile_edi_id>

Remove an EDI user profile from a group.

Required permission: Caller must have write permission on the group.

Parameters

Parameter In Required Description
edi-token Cookie Yes See Parameters
group_edi_id URL path Yes EDI-ID of the group
profile_edi_id URL path Yes EDI-ID of the profile to remove

Response

Status Description
200 OK Profile removed from group successfully
401 Unauthorized See Parameters
403 Forbidden Caller does not have write permission
404 Not Found Group or profile not found