Groups

This guide will walk you though the process of assigning, getting and updating groups and also give you a better understanding about group definition.

Group is an aggregation of persons to which policies can be assigned. It can be a group of friends, a community, an organisation, a department within an organisation, etc. The example should give you more understanding of the topic:

Company Acme (group) hires 10 employees (persons) which are allowed to enter the office (policy).

What you need

To successfully complete this topic guide you need to ensure following prerequisites:

have the DUM Engine application up and running
have access to DUM Engine APIs and know the Basic Authorization credentials

For the sake of this guide we assume that the DUM Engine is available at http://localhost:8080.

Add a group

To add a group you need to execute an API call POST api/v1/groups to DUM Engine endpoint.

curl -i --user username:password 
-H "Content-Type: application/json" 
-H "Accept: application/json" 
-X POST -d 

'{
   "parent_group_id": "160d8767-b7ea-4706-9738-4dc221658868",
   "name": "Innosure Back Office"
 }' 

http://localhost:8080/api/v1/groups

The service responds with HTTP/1.1 201 Created status code and a Group representation for operation completed successfully.

Example response:

HTTP/1.1 201
Content-Type: application/json;charset=UTF-8

{
  "id": "160d8767-b7ea-4706-9738-4dc221658868",
  "policy_ids": [
    "145fabf0-8b05-4a4d-be15-95c7b568da63",
    "fe987430-8f0f-4fe6-948c-3d77cf05279a",
    "7b10aea0-6ca5-40f6-8fd5-acd060dfad95"
  ],
  "child_group_ids": [
    "f530f30d-8322-47d1-93ff-19f4fea37c79",
    "7b10aea0-6ca5-40f6-8fd5-acd060dfad95"
  ],
  "parent_group_ids": [
    "f530f30d-8322-47d1-93ff-19f4fea37c79",
    "7b10aea0-6ca5-40f6-8fd5-acd060dfad95"
  ],
  "name": "Innosure Back Office"
}

To get more information about the endpoint signature please look into the API documentation.

Get group details

To get a group you need to execute an API call GET api/v1/groups/{groupId} to DUM Engine endpoint.

curl -i --user username:password
-H "Content-Type: application/json" 
-H "Accept: application/json" 
-X GET http://localhost:8080/api/v1/groups/160d8767-b7ea-4706-9738-4dc221658868

The service responds with HTTP/1.1 200 Ok status code and a Group representation for operation completed successfully.

Example response:

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
  "id": "160d8767-b7ea-4706-9738-4dc221658868",
  "policies": [
    "145fabf0-8b05-4a4d-be15-95c7b568da63",
    "fe987430-8f0f-4fe6-948c-3d77cf05279a",
    "7b10aea0-6ca5-40f6-8fd5-acd060dfad95"
  ],
  "child_groups": [
    "f530f30d-8322-47d1-93ff-19f4fea37c79",
    "7b10aea0-6ca5-40f6-8fd5-acd060dfad95"
  ],
  "parent_groups": [
    "f530f30d-8322-47d1-93ff-19f4fea37c79",
    "7b10aea0-6ca5-40f6-8fd5-acd060dfad95"
  ],
  "owners": [
    "160d8767-b7ea-4706-9738-4dc221658868",
    "146a47f0-31be-145d-aaef-900abc3753e1"
  ],
  "name": "Innosure Back Office"
}

To get more information about the endpoint signature please look into the API documentation.

Update a group

To update a group you need to execute an API call PUT api/v1/groups/{groupId} to DUM Engine endpoint.

curl -i --user username:password 
-H "Content-Type: application/json" 
-H "Accept: application/json" -X POST -d 

'{
   "name": "Innosure Back Office"
 }' 

http://localhost:8080/api/v1/groups/160d8767-b7ea-4706-9738-4dc221658868

The service responds with HTTP/1.1 200 Ok status code and a Group representation for operation completed successfully.

Example response:

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
  "id": "160d8767-b7ea-4706-9738-4dc221658868",
  "policies": [
    "145fabf0-8b05-4a4d-be15-95c7b568da63",
    "fe987430-8f0f-4fe6-948c-3d77cf05279a",
    "7b10aea0-6ca5-40f6-8fd5-acd060dfad95"
  ],
  "child_groups": [
    "f530f30d-8322-47d1-93ff-19f4fea37c79",
    "7b10aea0-6ca5-40f6-8fd5-acd060dfad95"
  ],
  "parent_groups": [
    "f530f30d-8322-47d1-93ff-19f4fea37c79",
    "7b10aea0-6ca5-40f6-8fd5-acd060dfad95"
  ],
  "owners": [
    "160d8767-b7ea-4706-9738-4dc221658868",
    "146a47f0-31be-145d-aaef-900abc3753e1"
  ],
  "name": "Innosure Back Office"
}

To get more information about the endpoint signature please look into the API documentation.

Search groups

You can list and filter groups which specified person has permissions to.

List all groups

In order to fetch all person's groups you need to execute an API call GET api/v1/groups/search to DUM Engine's endpoint specifying person identifier in the query.

curl -i --user username:password
-H "Accept: application/json" -X GET http://localhost:8080/api/v1/groups/search?person_id=person-1

The DUM Engine will respond with all groups which person-1 has permissions to.

Example response:

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8
{
    "content": [
        {
            "parent_groups_ids": [
                "be51f7a1-4b0d-4f80-bf03-3cabf270fd3a"
            ],
            "id": "71828ce1-6365-47e4-a760-d7b7cd751e5a",
            "name": "Acme"
        },
        {
            "child_groups_ids": [
                "71828ce1-6365-47e4-a760-d7b7cd751e5a",
                "f8c4defc-0a0b-4a61-87e0-083cdb3c5778"
            ],
            "id": "be51f7a1-4b0d-4f80-bf03-3cabf270fd3a",
            "name": "ROOT_GROUP"
        },
        {
            "parent_groups_ids": [
                "be51f7a1-4b0d-4f80-bf03-3cabf270fd3a"
            ],
            "id": "f8c4defc-0a0b-4a61-87e0-083cdb3c5778",
            "name": "Onegini"
        }
    ],
    "total_results": 3,
    "offset": 0,
    "page_size": 20
}

Please note that the actual response is wrapped by paging object. You can control the pagination by specifying additional query params which are following org.springframework.data.domain.PageRequest object definition, ex. offset, sort, page and size.

To get more information about the endpoint signature please look into the Delete group documentation.

Search groups by group name

The DUM Engine allows you to specify whether the group name should start with groupName%, end with %groupName, contain %groupName% or exact match groupName certain string. The group name parameter should be provided in the name query parameter as follows:

curl -i --user username:password
-H "Accept: application/json" -X GET http://localhost:8080/api/v1/groups/search?person_id=person-1&name=Ac%25

Please note that in case you want use LIKE search the % symbol must be urlencoded %25.

Example response:

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8
{
    "content": [
        {
            "parent_groups_ids": [
                "be51f7a1-4b0d-4f80-bf03-3cabf270fd3a"
            ],
            "id": "71828ce1-6365-47e4-a760-d7b7cd751e5a",
            "name": "Acme"
        }
    ],
    "total_results": 1,
    "offset": 0,
    "page_size": 20
}

To get more information about the endpoint signature please look into the Delete group documentation.

Remove a group

To remove a group you need to execute an API call to DELETE api/v1/groups/{groupId} DUM Engine endpoint. Please note that when you delete a group, also all policies which consider it as a subject will be removed as well. The DUM Engine by default creates a parent / root group, which lies on the top level and serves the inheritance purpose. The root group cannot be removed.

curl -i --user username:password
-H "Content-Type: application/json" 
-H "Accept: application/json" 
-X DELETE http://localhost:8080/api/v1/groups/0d31a0fa-ac44-45e9-affd-92edf4b1b5b4

The service responds with HTTP/1.1 204 No Content for operation completed successfully.

To get more information about the endpoint signature please look into the Delete group documentation.

Add a person to a group

Users can be connected with groups not only by assigning policies, but also by becoming it's members. To add a person to a group you need to execute an API call to POST api/v1/groups/{groupId}/persons/{personId} DUM Engine's endpoint. This method allows you also to specify about the user

curl -i --user username:password
-H "Content-Type: application/json"
-H "Accept: application/json"
-X POST -d

'{
   "first_name": "John",
   "last_name": "Smith"
 }'

http://localhost:8080/api/v1/groups/145fabf0-8b05-4a4d-be15-95c7b568da63/persons/fe987430-8f0f-4fe6-948c-3d77cf05279a

To get more information about the endpoint signature please look into the API documentation.

Search group members

You can list and filter group members.

List all group members

To list all group members you need to execute an API call to GET api/v1/group/{groupId}/persons DUM Engine endpoint.

curl -i --user username:password
-H "Content-Type: application/json"
-H "Accept: application/json"
-X GET http://localhost:8080/api/v1/group/7b10aea0-6ca5-40f6-8fd5-acd060dfad95/persons

The service responds with HTTP/1.1 200 Ok status code and a list of persons which are members of the given group.

Example response:

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8
{
    "content": [
        {
             "person_id": "a2c0bde9-2325-437b-8f8a-77196a9084a2",
             "first_name": "John",
             "last_name": "Smith"
        }
    ],
    "total_results": 1,
    "offset": 0,
    "page_size": 20
}

To get more information about the endpoint signature please look into the API documentation.

Search group members by member name

The DUM Engine allows you specify whether group member first or last name should start with name%, end with %name, contain %name% or exact match name certain string. The group name parameter should be provided in the name query parameter as follows:

curl -i --user username:password
-H "Content-Type: application/json"
-H "Accept: application/json"
-X GET http://localhost:8080/api/v1/group/7b10aea0-6ca5-40f6-8fd5-acd060dfad95/persons/search?name=Joh%25

Please note that in case you want use LIKE search the % symbol must be urlencoded %25.

The service responds with HTTP/1.1 200 Ok status code and a list of group members who match specified criteria.

Example response:

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8
{
    "content": [
        {
             "person_id": "a2c0bde9-2325-437b-8f8a-77196a9084a2",
             "first_name": "John",
             "last_name": "Smith"
        }
    ],
    "total_results": 1,
    "offset": 0,
    "page_size": 20
}

To get more information about the endpoint signature please look into the API documentation.

Remove a group member

To remove a person from a group you need to execute an API call to DELETE api/v1/groups/{groupId}/persons/{personId} DUM Engine's endpoint.

curl -i --user client:password
-H "Content-Type: application/json"
-H "Accept: application/json"
-X DELETE http://localhost:8080/api/v1/groups/0d31a0fa-ac44-45e9-affd-92edf4b1b5b4/persons/a2c0bde9-2325-437b-8f8a-77196a9084a2

The service responds with HTTP/1.1 204 No Content for operation completed successfully.

To get more information about the endpoint signature please look into the API documentation documentation.