As part of a recent support case customer was developing a restman process to add users, but found restman does not have functionality to add users as members of the groups. As part of the soln we developed a rest method to be able to manipulate group membership - this article is the result of that.
Currently there is no way to manipulate Group Membership for Internal Groups via the restman interface. Clearly it would be best if restman supported listing and editing group membership - as per the enhancement request :
Enhance Restman to support add/delete/change usergroup membership
Failing that option, what's described here is service that provides /restman like interface to enable adding/deleting/changing group membership.
Hopefully, if you have this type of requirement you can take this sample code and modify it to suit your circumstances as a workaround until the product is modified and an official restman interface is provided.
1. Current Restman Interface.
The documentation for restman as per - REST Management API - CA API Gateway - 9.4 - CA Technologies Documentation
is available from your gateway server : https://<GatewayHostName>:<port>/restman/1.0/doc/home.html
The documentation provides :
We have for Users :
Create User : POST 1.0/users
List Users: GET 1.0/users
Get User: GET 1.0/users/{userID}
Delete User: DELETE 1.0/users/{userID}
Update User: PUT 1.0/users/{userID}
For Group we have :
List Group: GET 1.0/groups
Get group: GET 1.0/groups/{groupID}
That enabled us to get the userid and groupid, needed to edit group membership.
2. What we would like for Group Membership
What we would like for Group Membership is :
Create UserGroup : POST 1.0/usergroup
List UserGroup: GET 1.0/usergroup?user_goid=<id>&group_goid=<id>
Get UserGroup: GET 1.0/usergroup/{usergroupID}
Delete UserGroup: DELETE 1.0/usergroup/{usergroupID}
Update UserGroup: PUT 1.0/usergroup/{usergroupID}
That would allow us to add a user as member of a group, list group membership, either in total, or for a specific user or for a specific group. Then also to delete and update the group membership record.
And that essentially is the interface we have implemented here - outside the /restman framework, but with a similar interface.
3. Internal Implementation for Group Membership
The group membership resides in a table internal_user_group, and is associated with the group and user information in tables : internal_group, internal_user, :
The internal_user_group contains mostly goid entries linking the group to the user. So by accessing the internal ssg database we can manipulate the status of group membership.
4. Simple Data Representation
For the user_group data formatting we are using simple xml layout (no dtd even), a little like the formal one used in restman.
These are our elements :
<?xml version="1.0" encoding="UTF-8"?>
<List>
<UserGroup>
<Goid>20b28e068d1cae807d2fd5aef7388139</Goid>
<Version>0</Version>
<GroupGoid>20b28e068d1cae807d2fd5aef7388128</GroupGoid>
<ProviderGoid>0000000000000000fffffffffffffffe</ProviderGoid>
<UserGoid>20b28e068d1cae807d2fd5aef7388125</UserGoid>
<SubgroupId>null</SubgroupId>
</UserGroup>
</List>
5. Gateway Policy Implementation
5.1 We need a database connection to the ssg database :
5.2 We need a policy to restrict access as per the restman
As per the original restman policy, where we copied this from.
So we require SSL, an authenticated user against the internal identity provider (you may want to suplment that to allow only admin user or a group member for example).
5.3 Determine which command we are to run
Not showing them all, but combination of http.method and url path tell us which operation : LIST, ADD, ADD_OR_UPDATE, DELETE, we are trying to perform. We default to LIST - but usually should be determined by context.
5.4 Get the relevant data and execute SQL Statement.
For each command we parse the query parameters, the {id} field from the url, and the fields out of the xml input as needed. Then we need to execute an SQL stmt to either get or update the data field.
Here is the ADD command :
So for ADD: if the <Guid> field is not present - then it will generate one, the version will default to 0 if it is not present. And the subgroup_id will default to null if it is not present (the text 'null' will be interpreted as an SQL null).
There are similar blocks of code for each operation - for details see the attached policy.
Note1 : The use of : mysql unhex(replace(${new_group_member_goid},"-","")), means the input goid field can handle both the string form and straight hex string form.
Note2: In our returning of uuid data we didn't add the "-" mainly because it would be less efficient - but some function could easily be added to do that.
Note3: The interface we have is just using the goid values, but it would be fairly easy to supplement the interface to allow using the username or groupname, and then do a lookup to get their goid values.
Note4: In the sql we are using nullif(${subgroup_id},'null')); to translate the subgroup text 'null' to the sql null entry - just to keep that part simple.
6. Test Cases for the Service
For my testing I've used RestClient in Firefox, things to remembers are to make sure you set the content-Type : application/xml and to set the basic Authentication header.
6.1 LIST Operations
These are the basic list operations - and sample returned data :
GET https://odoma04-gw.example.com:8443/usergroup
GET https://odoma04-gw.example.com:8443/usergroup?user_goid=20b28e068d1cae807d2fd5aef7388121
GET https://odoma04-gw.example.com:8443/usergroup?group_goid=20b28e068d1cae807d2fd5aef7388128
GET https://odoma04-gw.example.com:8443/usergroup/20b28e068d1cae807d2fd5aef7388139
6.2 ADD Operation
The POST does an add - here is POST with the minimal data fields - the uuid will be generated and returned :
POST https://odoma04-gw.example.com:8443/usergroup
<?xml version="1.0" encoding="UTF-8"?>
<UserGroup>
<GroupGoid>20b28e068d1cae807d2fd5aef7388128</GroupGoid>
<ProviderGoid>0000000000000000fffffffffffffffe</ProviderGoid>
<UserGoid>20b28e068d1cae807d2fd5aef7388125</UserGoid>
</UserGroup>
If you add the Goid, Version or subgroup_id those will be added otherwise defaults are used.
6.3 UPDATE Operation
Update is pretty similar to ADD, if the entry via Goid is found it will be updated, otherwise it will be inserted. It will use the Goid from the URL, rather than the one in the xml.
PUT https://odoma04-gw.example.com:8443/usergroup/20b28e068d1cae807d2fd5aef7388139
<?xml version="1.0" encoding="UTF-8"?>
<UserGroup>
<Goid>20b28e068d1cae807d2fd5aef7388139</Goid>
<Version>0</Version>
<GroupGoid>20b28e068d1cae807d2fd5aef7388128</GroupGoid>
<ProviderGoid>0000000000000000fffffffffffffffe</ProviderGoid>
<UserGoid>20b28e068d1cae807d2fd5aef7388125</UserGoid>
<SubgroupId>null</SubgroupId>
</UserGroup>
6.4 DELETE Operation
Delete is fairly simple - again if the record is found it will be deleted.
DELETE https://odoma04-gw.example.com:8443/usergroup/20b28e068d1cae807d2fd5aef7388139
Cheers - Mark