Grouper web services (grouper-ws) is a J2EE web application which exposes common Grouper business logic through SOAP and REST. See Web Services FAQ. and architectural diagram.
To deploy the services, download the warfile and configure the property files (e.g. subject sources, databases, logging, etc). Configure authentication.
Note: there is a command line and java API web service client called Grouper Client
To implement a web service client:
Grouper client version |
v1.4, v1.5, v1.6, v2.0 (server version) Endpoint |
WSDL from server |
WSDL from SVN |
---|---|---|---|
1.4 |
https://server.address/grouperWs/services/GrouperService?wsdl |
||
1.5 |
https://server.address/grouperWs/services/GrouperService?wsdl |
||
1.6 |
https://server.address/grouperWs/services/GrouperService?wsdl |
||
2.0 |
https://server.address/grouperWs/services/GrouperService_v2_0 |
https://server.address/grouperWs/services/GrouperService_v2_0?wsdl |
/grouper-ws/servicesRest/xml/v2_1_000/groups/aStem%3AaGroup/members/10021368 /grouper-ws/servicesRest/json/v2_1_000/groups/aStem%3AaGroup/members/10021368 /grouper-ws/servicesRest/xhtml/v2_1_000/groups/aStem%3AaGroup/members/10021368 |
https://spaces.at.internet2.edu/confluence/download/attachments/3014660/webServicePresentation.pptPresentation about Grouper web services
Note the WS is included in the Grouper Installer. Checkout the appropriate projects under grouper-ws, read the README.txt in the grouper-ws/grouper-ws cvs directory
Note the WS is included in the Grouper Installer. (it will build and configure it). The build script for grouper-ws is pretty basic. Generally just do the default (dist). There is also an "ant grouper" target to build a new grouper jar, and "ant quick" to do everything but generate the Axis files (takes 3 minutes).
C:\mchyzer\isc\dev\grouper\grouper-ws>ant Buildfile: build.xml dist: clean: [delete] Deleting directory C:\mchyzer\isc\dev\grouper\grouper-ws\build [mkdir] Created dir: C:\mchyzer\isc\dev\grouper\grouper-ws\build\grouper-ws [mkdir] Created dir: C:\mchyzer\isc\dev\grouper\grouper-ws\build\dist [mkdir] Created dir: C:\mchyzer\isc\dev\grouper\grouper-ws\build\dist\grouper-ws compile: [javac] Compiling 10 source files to C:\mchyzer\isc\dev\grouper\grouper-ws\build\grouper-ws [javac] C:\mchyzer\isc\dev\grouper\grouper-ws\src\grouper-ws\edu\internet2\middleware\grouper\webservices\GrouperSer viceServlet.java:33: warning: [deprecation] getEPRForService(java.lang.String,java.lang.String) in org.apache.axis2.tran sport.TransportListener has been deprecated [javac] public class GrouperServiceServlet extends AxisServlet { [javac] ^ [javac] 1 warning generate-aar: [mkdir] Created dir: C:\mchyzer\isc\dev\grouper\grouper-ws\build\dist\webservices\classes [delete] Deleting directory C:\mchyzer\isc\dev\grouper\grouper-ws\build\dist\webservices\classes [mkdir] Created dir: C:\mchyzer\isc\dev\grouper\grouper-ws\build\dist\webservices\classes [copy] Copying 13 files to C:\mchyzer\isc\dev\grouper\grouper-ws\build\dist\webservices\classes [jar] Building jar: C:\mchyzer\isc\dev\grouper\grouper-ws\webapp\WEB-INF\services\GrouperService.aar [jar] Building jar: C:\mchyzer\isc\dev\grouper\grouper-ws\build\dist\grouper-ws.jar [mkdir] Created dir: C:\mchyzer\isc\dev\grouper\grouper-ws\build\dist\grouper-ws\WEB-INF\classes [mkdir] Created dir: C:\mchyzer\isc\dev\grouper\grouper-ws\build\dist\grouper-ws\WEB-INF\lib [copy] Copying 12 files to C:\mchyzer\isc\dev\grouper\grouper-ws\build\dist\grouper-ws\WEB-INF\classes [copy] Copying 30 files to C:\mchyzer\isc\dev\grouper\grouper-ws\build\dist\grouper-ws\WEB-INF\lib [copy] Copying 11 files to C:\mchyzer\isc\dev\grouper\grouper-ws\build\dist\grouper-ws [jar] Building jar: C:\mchyzer\isc\dev\grouper\grouper-ws\build\dist\grouper-ws.war BUILD SUCCESSFUL Total time: 22 seconds The system cannot find the batch label specified - end C:\mchyzer\isc\dev\grouper\grouper-ws> |
Notice the generate-aar target. This is what makes the axis archive, which is all the classes needed for axis to determine the wsdl, along with the services.xml config file.
Axis is ~40 jars, though most of them are pretty axis specific. There is an ant target which will compress most of these into one jar (axisBundle.jar). Here is the ant help:
C:\mchyzer\isc\dev\grouper\grouper-ws>ant help Buildfile: build.xml help: [echo] Please ensure you have read the documentation - [echo] and created a build.properties file based on the template provided [echo] [echo] The following targets are available - type the appropriate name: [echo] [echo] 1) default (dist) [echo] Simply builds, without cleaning, to the webapp.folder [echo] 2) clean [echo] Clean the webapp folder, and classfiles, and build [echo] 3) generate-aar [echo] Make the axis archive, which is the classfiles and services.xml that axis needs. You need to do this i f you ever change anything that changes the wsdl. You can do this automatically in dist by setting a property in the bu ild.properties [echo] 4) generate-axis-bundle-jar [echo] Take all the bundlable axis jars (in lib/axis-bundle), unjar, and jar back up into one jar [echo] BUILD SUCCESSFUL Total time: 0 seconds The system cannot find the batch label specified - end C:\mchyzer\isc\dev\grouper\grouper-ws> |
1. The default attribute names (comma separated) sent back for each request are specified in grouper-ws.properties under the key:
ws.subject.result.attribute.names
2. If the caller sets T to retrieve subject detail, then the attributes will be appended to that list in grouper-ws.properties key:
ws.subject.result.detail.attribute.names
3. If the caller specifies subjectAttributeNames in the request (comma separated), then those will be appended to the list (independent of the detail attributes).
So there are central settings, and caller settings that you need to design for and specify...
Note if subjectId and subjectIdentifier are filled in with the same value, it will find by subject id or identifier.
You can do this via the client or a proxy. If you must do this via the server, there is an experimental way to do this in v2.1.1+. You should not do this in prod, only in a testing environment.
Add a new servlet filter mapping in the web.xml
<filter-mapping> <filter-name>Grouper logging filter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping> |
Set the filter logger to log at debug level
log4j.logger.edu.internet2.middleware.grouper.ws.j2ee.ServletFilterLogger = DEBUG |
You will see log entries like this
2012-05-03 09:13:18,575: [http-8088-1] DEBUG ServletFilterLogger.logStuff(98) - - IP: 127.0.0.1, url: /grouperWs/servicesRest/v2_1_001/groups/aStem%3AaGroup/members, queryString: null, method: PUT, content-type: text/x-json; charset=UTF-8 request params: request body: {"WsRestAddMemberRequest":{"actAsSubjectLookup":{"subjectId":"GrouperSystem"},"replaceAllExisting":"F","subjectLookups":[{"subjectId":"10021368"},{"subjectId":"10039438"}]}} respone headers: (note, not all headers captured, and not in this order) X-Grouper-resultCode: SUCCESS X-Grouper-success: T X-Grouper-resultCode2: NONE HTTP/1.1 201 Content-Type: text/x-json; charset=UTF-8 response: {"WsAddMemberResults":{"responseMetadata":{"millis":"237","serverVersion":"2.1.1"},"resultMetadata":{"resultCode":"SUCCESS","resultMessage":"Success for: clientVersion: 2.1.1, wsGroupLookup: WsGroupLookup[pitGroups=[],groupName=aStem:aGroup], subjectLookups: Array size: 2: [0]: WsSubjectLookup[subjectId=10021368]\n[1]: WsSubjectLookup[subjectId=10039438]\n\n, replaceAllExisting: false, actAsSubject: WsSubjectLookup[subjectId=GrouperSystem], fieldName: null, txType: NONE, includeGroupDetail: false, includeSubjectDetail: false, subjectAttributeNames: null\n, params: null\n, disabledDate: null, enabledDate: null","success":"T"},"results":[{"resultMetadata":{"resultCode":"SUCCESS_ALREADY_EXISTED","success":"T"},"wsSubject":{"id":"10021368","name":"10021368","resultCode":"SUCCESS","sourceId":"jdbc","success":"T"}},{"resultMetadata":{"resultCode":"SUCCESS_ALREADY_EXISTED","success":"T"},"wsSubject":{"id":"10039438","name":"10039438","resultCode":"SUCCESS","sourceId":"jdbc","success":"T"}}],"wsGroupAssigned":{"description":"a group description","displayExtension":"a group","displayName":"a stem:a group","extension":"aGroup","name":"aStem:aGroup","typeOfGroup":"group","uuid":"d9094e4a7c6e4f399d7e1489c875b9f0"}}} |
At some point we can make it more granular which requests get logged and give an option to format the request/response (indent, etc)
If you want to check to see if a subject as a group permission, or to get a list of people with a certain permissions on a group, use hasMember or getMembers, and pass the name of the field (note this list depends on your configuration):
select name from grouper_fields where type != 'naming';
admins
description
displayExtension
displayName
extension
members
name
optins
optouts
readers
requireActiveEmployee
requireAlsoInGroups
updaters
viewers
See the always available client for more info on this slide