Skip to content

group.md

Latest commit

 

History

History
200 lines (142 loc) · 6.15 KB

group.md

File metadata and controls

200 lines (142 loc) · 6.15 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

Create a new group of EDI user profiles.

POST: /auth/v1/group

createGroup(
  edi_token
  title: The title of the group
  description: The description of the group
)

Returns:
  200 OK
  401 Unauthorized
  403 Forbidden

Body:
  Group's EDI-ID if 200 OK, error message otherwise

Permissions:
  The caller must be in the Vetted system group

Read Group

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

GET: /auth/v1/group/<group_edi_id>

readGroup(
  edi_token
  group_edi_id: the group EDI-ID
)

Returns:
  200 OK
  401 Unauthorized
  403 Forbidden
  404 Not Found - The group does not exist

Permissions:
  The caller must have READ permission on the group

Update Group Details

Modify the title and/or description of a group.

PUT: /auth/v1/group/<group_edi_id>

updateGroup(
  edi_token
  title: The title of the group (optional)
  description: The description of the group (optional)
)

Returns:
  200 OK if successful
  401 Unauthorized if the client does not provide a valid authentication token
  403 Forbidden if client is not authorized to execute method or access resource
  404 If the group does not exist

  
  body:
      Empty if 200 OK, error message otherwise

Permissions:
  The caller must have WRITE permission on the group

Delete Group

Delete an EDI group.

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

deleteGroup(edi_token, group_name)
  edi_token: the token of the requesting client
  group_edi_id: the group EDI-ID
  return:
      200 OK if successful
      401 Unauthorized if the client does not provide a valid authentication token
      403 Forbidden if client is not authorized to execute method or access resource
      404 If the group does not exist
  body:
      Empty if 200 OK, error message otherwise

Permissions:
  The caller must have WRITE permission on the group

Add User Profile to Group

Add an EDI user profile to a group.

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

addGroupMember(
  edi_token
  group_edi_id: The EDI-ID of the group to which the user profiles will be added
  profile_edi_id: The EDI-ID of the user profile to add to the group
)

Returns:
  200 OK
  401 Unauthorized
  403 Forbidden
  404 Not Found - If the group or the user profile does not exist. The response body will contain a message indicating which EDI-ID was not found.

Permissions:
  The caller must have WRITE permission on the group
  • If the profile EDI-ID is already a member of the group, no changes will be made, and the method will return 200 OK, with a message indicating that the profile was already a member of the group.

Examples

Adding user profile EDI-1234 to group EDI-99cd:

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 a User Profile from a Group

Remove an EDI user profile from a group.

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

removeGroupMember(edi_token, group_edi_id, profile_edi_id)
  edi_token: the token of the requesting client
  group_edi_id: the group EDI-ID
  profile_edi_id: the profile EDI-ID to remove from the group
  return:
    200 OK if successful
    401 Unauthorized if the client does not provide a valid authentication token
    403 Forbidden if client is not authorized to execute method or access resource
    404 If the group does not exist or if the user does not exist
  body:
    Empty if 200 OK, error message otherwise

Permissions:
  The caller must have WRITE permission on the group