PennGroups

From Provider Wiki

Jump to: navigation, search

Contents


[1]Download the client

Email the support listserv: penngroups-help@lists.upenn.edu

To request access to PennGroups, submit an access form: [2]http://www.upenn.edu/computing/penngroups/pennGroupsAccess.pdf

[3]Course list description

Training:

Penngroups user training [4] ppt, movie part [5] 1, [6] 2, [7] 3, [8] 4, [9] 5, [10] 6, [11] 7, [12] 8, [13] 9, [14] 10

Penngroups admin training [15] ppt, movie part [16] 1, [17] 2, [18] 3, [19] 4

FAQ:

How can I see the name and description from the grouperClient (or WS)? 

 [mchyzer@flash pennGroupsClient-1.4.2]$ java -jar grouperClient.jar --operation=getMembersWs --groupNames=test:testGroup --subjectAttributeNames=PENNNAME,EMAIL,name,description --outputTemplate='${wsSubject.attributeValues[0]} ${wsSubject.attributeValues[1]} ${wsSubject.attributeValues[2]}: ${wsSubject.attributeValues[3]}$newline$'
 bwh bwh@isc.upenn.edu Bryan W Hopkins: Bryan W Hopkins (bwh, 10064187) Pennpay, Staf (active)
 mchyzer mchyzer@isc.upenn.edu Michael Christopher Hyzer: Michael Christopher Hyzer (mchyzer, 10021368) Pennpay, Staf (active)

How can I edit group memberships in the UI?

See this page: PennGroupsUi

How can I test connectivity to the PennGroups?

You can try to list a public group we have setup with the PennGroups client: 

 C:\temp>java -jar grouperClient.jar --operation=getMembersWs --groupNames=test:testGroup
 GroupIndex 0: success: T: code: SUCCESS: group: test:testGroup: subjectIndex: 0: 10064187
 GroupIndex 0: success: T: code: SUCCESS: group: test:testGroup: subjectIndex: 1: 10021368

You can list the same group with ldap: 

 C:\temp>java -jar grouperClient.jar --operation=getMembersLdap --groupName=test:testGroup

How can I return pennkeys from the web service?

You can specify to return pennnames, and you can use them in your output template: 

 C:\temp>java -jar grouperClient.jar --operation=getMembersWs --groupNames=test:testGroup --subjectAttributeNames=PENNNAME --outputTemplate=${wsSubject.attributeValues[0]}$newline$
 bwh
 mchyzer

How can I query based on pennkey from the web service?

You can use the built in pennkey support in Penn's grouper client (needs custom configuration over the generic Grouper download): 

 C:\temp>java -jar grouperClient.jar --operation=hasMemberWs --groupName=test:testGroup --pennKeys=mchyzer,bwh
 Index 0: success: T: code: IS_MEMBER: 10021368: true
 Index 1: success: T: code: IS_MEMBER: 10064187: true

How can I get pennnames and emails from a WS call? 

 java -jar grouperClient.jar --operation=getMembersWs --groupNames=test:testGroup --subjectAttributeNames=PENNNAME,EMAIL --outputTemplate='${wsSubject.attributeValues[0]} ${wsSubject.attributeValues[1]}$newline$'
 abc abc@isc.upenn.edu
 def def@isc.upenn.edu

How can I make a group which has a manual membership list and requires users to be faculty student or staff?

First off, you need permission to view the facultyStudentStaff group, email the support listserv penngroups-help@lists.upenn.edu. Then you can make this client request (note, the composite arguments shouldnt be necessary, but until it is fixed, use them and it will work). This makes a group, a system of record group (where the manual entries go), and the overall group is a composite intersection of the manual group and the facultyStudentStaff group. 

 C:\temp>java -jar grouperClient.jar --operation=groupSaveWs --name=test:isc:astt:chris:myGroup --includeGroupDetail=true --description="test group with requiring active facultyStudentStaff" --displayExtension="My test group" --attributeName0=requireAlsoInGroups --attributeValue0=penn:community:facultyStudentStaff --typeNames=requireInGroups --compositeType=INTERSECTION --leftGroupName=test:isc:astt:chris:myGroup_systemOfRecord --rightGroupName=penn:community:facultyStudentStaff
 Success: T: code: SUCCESS_INSERTED: test:isc:astt:chris:myGroup

What does that look like in a soap request? 

 <?xml version='1.0' encoding='UTF-8'?>
 <soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
   <soapenv:Body>
     <ns1:groupSave xmlns:ns1="http://soap.ws.grouper.middleware.internet2.edu/xsd">
       <ns1:clientVersion>v1_4_002</ns1:clientVersion>
       <ns1:wsGroupToSaves>
         <ns1:wsGroup>
           <ns1:description>
             test group with requiring active facultyStudentStaff
           </ns1:description>
           <ns1:detail>
             <ns1:attributeNames>requireAlsoInGroups</ns1:attributeNames>
             <ns1:attributeValues>penn:community:facultyStudentStaff</ns1:attributeValues>
             <ns1:compositeType>intersection</ns1:compositeType>
             <ns1:hasComposite>T</ns1:hasComposite>
             <ns1:leftGroup>
               <ns1:description></ns1:description>
               <ns1:displayExtension></ns1:displayExtension>
               <ns1:displayName></ns1:displayName>
               <ns1:extension></ns1:extension>
               <ns1:name>penn:community:facultyStudentStaff</ns1:name>
               <ns1:uuid></ns1:uuid>
             </ns1:leftGroup>
             <ns1:rightGroup>
               <ns1:description></ns1:description>
               <ns1:displayExtension></ns1:displayExtension>
               <ns1:displayName></ns1:displayName>
               <ns1:extension></ns1:extension>
               <ns1:name>test:isc:astt:chris:myGroup_systemOfRecord</ns1:name>
               <ns1:uuid></ns1:uuid>
             </ns1:rightGroup>
             <ns1:typeNames>requireInGroups</ns1:typeNames>
           </ns1:detail>
           <ns1:displayExtension>My test group</ns1:displayExtension>
           <ns1:extension>myGroup</ns1:extension>
           <ns1:name>test:isc:astt:chris:myGroup</ns1:name>
         </ns1:wsGroup>
         <ns1:wsGroupLookup>
           <ns1:groupName>test:isc:astt:chris:myGroup</ns1:groupName>
         </ns1:wsGroupLookup>
       </ns1:wsGroupToSaves>
       <ns1:actAsSubjectLookup>
         <ns1:subjectId></ns1:subjectId>
       </ns1:actAsSubjectLookup>
       <ns1:txType></ns1:txType>
       <ns1:includeGroupDetail>T</ns1:includeGroupDetail>
     </ns1:groupSave>
   </soapenv:Body>
 </soapenv:Envelope>

Grouper Client setup:

To use PennGroups, or the Pennkey to PennID translation service, you need a kerberos service principal. You can use the Grouper Client, or web services, you need have a known password. To just use LDAP directly, you can use a known password or another method. Here are the commands that your kadmin (kerberos administrator) can issue to create a kerberos service principal with a known password (ON UNIX), assuming the kadmin principal is lila/kadmin-isc-seo.upenn.edu, and the principal to create is: penngroups/medley-test.isc-seo.upenn.edu 

 [lila@bastion ~]$ kadmin -p lila/kadmin-isc-seo.upenn.edu
 Authenticating as principal lila/kadmin-isc-seo.upenn.edu with password.
 Password for lila/kadmin-isc-seo.upenn.edu@UPENN.EDU: 

 kadmin:  addprinc -randkey +requires_preauth penngroups/medley-test.isc-seo.upenn.edu
 NOTICE: no policy specified for penngroups/medley-test.isc-seo.upenn.edu@UPENN.EDU; assigning "default"
 Principal "penngroups/medley-test.isc-seo.upenn.edu@UPENN.EDU" created.

 kadmin:  cpw penngroups/medley-test.isc-seo.upenn.edu
 Enter password for principal "penngroups/medley-test.isc-seo.upenn.edu": 
 Re-enter password for principal "penngroups/medley-test.isc-seo.upenn.edu": 
 Password for "penngroups/medley-test.isc-seo.upenn.edu@UPENN.EDU" changed.

For windows, you dont need the -p. http://www.upenn.edu/computing/pennkey/sysadmin/e_install_win/kadmin.html

If you issued those commands, then the principal to login with in grouperClient or web services would be: penngroups/medley-test.isc-seo.upenn.edu. NOTE: the kerberos principal is case-sensitive.

You can test the creation by getting a Kerberos ticket with that login/pass (e.g. leash)

Windows users will need to install the kadmin tool as noted at http://www.upenn.edu/computing/pennkey/sysadmin/e_install_win/kadmin.html. More information on creating and managing non-user Kerberos principals is available at http://www.upenn.edu/computing/pennkey/sysadmin/c_install_gen/kadmin-howto.html.

Subject/Entity API:

Subject attributes

The following are attributes you can get from WS or grouperClient:

name: person's name. This is private and should not be published

description: description you see in the UI (don't parse this, it is subject to change), this is useful in list results

EMAIL: person's private email address. Do not publish this, it is for university purposes only!

id: pennid

PENNNAME: pennkey

EMAIL_PUBLIC: public email address that you can publish

NAME_PUBLIC: public name that you can publish

FIRST_NAME: private first name

LAST_NAME: private last name

PERSON_ACTIVE: T or F as to whether this person is active

NAME_FIRST_PUBLIC: public first name

NAME_LAST_PUBLIC: public last name

Grouper Client USAGE:

This program runs queries against grouper ldap and web services The system exit code will be 0 for success, and not 0 for failure Output data is printed to stdout, error messages are printed to stderr or logs (configured in grouper.client.properties) Grouper client webpage: https://wiki.internet2.edu/confluence/display/GrouperWG/Grouper+Client

Arguments are in the format: --argName=argValue

Example argument: --operation=encryptPassword

Example argument(OS dependent): --operation="value with whitespace"

Optional arguments below are in [brackets]

Misc Operations

Encrypt passwords for storing passwords in external encrypted files: 

 java -jar grouperClient.jar --operation=encryptPassword
 [--dontMask=true|false]

Usage (this message): 

 java -jar grouperClient.jar

Send file to web service: 

 java -jar grouperClient.jar --operation=sendFile --urlSuffix=groups/aStem:aGroup/members 
 [fileName=theFileName]
 [fileContents=theFileContents]
 [--contentType=text/xml]
 [--labelForLog=addMember]
 [--indentOutput=false]
 [--saveResultsToFile=fileName]
 [--debug=true]
 [--clientVersion=someVersion]
 e.g. java -jar grouperClient.jar --operation=sendFile --fileName="C:/addMember.xml" --urlSuffix=groups/aStem:aGroup/members

LDAP Structure

 Host: penngroups.upenn.edu
 Base dn: dc=upenn,dc=edu
 
 People ou: ou=pennnames
 objectClass for people: pennidTranslation
 attribute for pennkey: pennname
 attribute for pennid: pennid   (numeric)
 
 Groups ou: ou=groups
 Group name: Common name
 List of members by pennkey: hasmember   (multivalued attribute)
 Object classes: pennGrouperGroup, eduMember


LDAP Operations

pennname to pennid usage: 

 java -jar grouperClient.jar --operation=pennnameToPennid --pennnameToDecode=pennname
 [--saveResultsToFile=fileName]
 [--outputTemplate=somePattern]
 [--debug=true]
 e.g.: java -jar grouperClient --operation=pennnameToPennid --pennnameToDecode=jsmith
 output: pennid: 12341234

pennid to pennname usage: 

 java -jar grouperClient.jar --operation=pennidToPennkey --pennidToDecode=pennid
 [--saveResultsToFile=fileName]
 [--outputTemplate=somePattern]
 [--debug=true]
 e.g.: java -jar grouperClient --operation=pennidToPennkey --pennidToDecode=12341234
 output: pennname: jsmith

hasMember ldap usage: 

 java -jar grouperClient.jar --operation=hasMemberLdap --groupName=a:b:c --pennnameToCheck=pennkey
 [--saveResultsToFile=fileName]
 [--outputTemplate=somePattern]
 [--debug=true]
 e.g.: java -jar grouperClient --operation=hasMemberLdap --groupName=penn:myfolder:mygroup --pennnameToCheck=jsmith
 output: hasMemberLdap: true

getMembers ldap usage: 

 java -jar grouperClient.jar --operation=getMembersLdap --groupName=a:b:c
 [--saveResultsToFile=fileName]
 [--outputTemplate=somePattern]
 [--debug=true]
 e.g.: java -jar grouperClient --operation=getMembersLdap --groupName=penn:myfolder:mygroup
 output: groupList: jsmith, tsmith, msmith
 note: extremely large group lists might not display fully (e.g. over 1000 members)

Web Service Operations

See v1.6: https://spaces.internet2.edu/display/GrouperWG/Grouper+Web+Services


Samples and Examples:

Retrieved from "http://prowiki.isc.upenn.edu/wiki/PennGroups"
Personal tools