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
}
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. More info can be found in the API documentation.
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
}
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 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.