...
Note |
---|
This document is a work in progress. Improvements to wiki formatting are welcome. |
Table of Contents |
---|
Usage
...
The psp may be run using GrouperShell (gsh).
...
One of -bulkCalc
, -bulkDiff
, -bulkSync
, -calc <id>
, -diff <id>
, or -sync <id>
must be specified. All other arguments are optional.
Introduction
...
Grouper groups, memberships, and stems may be provisioned using the provisioning service provider (psp, formerly known as ldappcng).
...
Currently, the psp supports SPMLv2 requests represented as java objects via the Oasis SPMLv2 implementation. The requestor is Grouper's cli, gsh.
calc
Calculate how an object should be provisioned.
Upon receipt of a calc
request, the psp will calculate how an object (or objects) should be provisioned, and will return a calc
response representing the correct provisioning.
diff
Determine the changes necessary to transform a provisioned object from how it is currently provisioned to how it should be provisioned.
Upon receipt of a diff
request, the psp first performs a calc
request to calculate how objects should be provisioned. Then, the psp queries each target to determine how objects are provisioned. The psp returns a diff
response representing the changes necessary to synchronize the provisioned objects from how it is currently provisioned to how it should be. The changes consist of add, delete, and or modify requests.
sync
Synchronize a provisioned object.
Upon receipt of a sync
request, the psp first performs a diff
request to determine provisioning changes. Then, the psp requests targets to perform the changes, and returns the results as a sync
response.
bulkCalc|bulkDiff|bulkSync
Bulk requests operate on all configured source identifiers, and includes the remove of orphan objects (provisioned objects for which no source identifier is known).
Getting Started with Real-Time Provisioning
...
Real-time provisioning is the incremental provisioning of groups, stems, and memberships triggered from the Grouper change log. Incremental provisioning is distinguished from full provisioning in that only a single or subset of an attribute's values are provisioned.
...
These instructions were written on a Mac, other platforms should be similar.
Requirements
...
- Grouper API (requires Java 6 and a database, details are here)
- provisioning service provider (psp)
- ldap directory
Install : Grouper Installer
...
To install Grouper including the API, UI, WS, grouperClient, psp, etc., download and run the Grouper Installer.
...
curl
http://www.internet2.edu/grouper/release/2.1.0/grouperInstaller.jar
-O
java -jar grouperInstaller.jar
Install : Manual
...
Install the provisioning service provider by copying jar files and example configuration files from the psp distribution to your Grouper API installation.
...
To install manually, download and unpack the psp, then copy jars and configuration files to your Grouper API installation.
Install : Manual - Download and Unpack the PSP
Download the PSP here and unpack.
...
curl
http://www.internet2.edu/grouper/release/2.1.0/grouper.psp-2.1.0.tar.gz
-O
tar xzf grouper.psp-2.1.0.tar.gz
Install : Manual - Copy Jars
Copy jars located in lib/custom
from the psp distribution to the Grouper API installation.
cp -vR grouper.psp-2.1.0/lib/custom/ grouper.apiBinary-2.1.0/lib/custom/
Install : Copy Example Configuration Files
...
Copy example configuration files located in conf
from the psp distribution to the Grouper API installation.
...
cp -vR grouper.psp-2.1.0/conf/ grouper.apiBinary-2.1.0/conf/
Configuration Example : Grouper to LDAP
...
This configuration example should apply to any ldap directory server.
examples | |
DN structure | bushy |
| member DNs |
Configuration Example : Grouper to Tivoli
...
This configuration example targets an IBM Tivoli Directory Server with requirements from Penn State.
examples | |
DN structure | flat |
| member subject ids |
| group DNs |
| member names |
| group names |
Configuration Example : Grouper to OpenLDAP
...
This configuration example applies to OpenLDAP, and includes provisioning the mailLocalAddress
attribute sourced from the Grouper attribute framework.
...
examples | |
DN structure | bushy |
| member DNs |
| member names |
| group names |
Configuration Example : Grouper to Active Directory
TODO
Configuration Example : LDAP to Grouper
TODO
Configure LDAP Provisioning Target
...
The LDAP provisioning target connection is configured in ldap.properties
.
...
No Format | ||
---|---|---|
| ||
# The base DN for groups. edu.internet2.middleware.psp.groupsBaseDn = ou=groups,dc=example,dc=edu # The base DN for people. edu.internet2.middleware.psp.peopleBaseDn = ou=people,dc=example,dc=edu |
Configure LDAP Provisioning Structure : Flat
...
In a flat
structure all groups are provisioned under a single base DN (container ID). A flat
group's ldap RDN is its Grouper name or displayName.
...
No Format | ||
---|---|---|
| ||
edu.internet2.middleware.psp.structure=flat edu.internet2.middleware.psp.cnSourceAttributeID=name |
Configure LDAP Provisioning Structure : Bushy
...
In a bushy
structure groups are provisioned hierarchically, with stems as branches (ldap organizationalUnits) in the tree. A bushy
group's RDN is its Grouper extension or displayExtension.
...
No Format | ||
---|---|---|
| ||
edu.internet2.middleware.psp.structure=bushy edu.internet2.middleware.psp.cnSourceAttributeID=extension |
Configure LDAP Subject Source
...
Configure Grouper to look for subjects in your LDAP directory by using the ldap source adapter.
...
No Format | ||
---|---|---|
| ||
<param-name>base</param-name> <param-value>ou=people,dc=example,dc=edu</param-value> ... |
Configure LDAP Subject Source : ID Other Than "ldap"
...
The id of the Grouper LDAP subject source adapter, <id>ldap</id>
, appears in several psp configuration files. If your Grouper LDAP subject source adapter id is not "ldap", you should read the following and make changes to your psp configuration files. In the following examples, the Grouper LDAP subject source id has been changed from "ldap" to "ad".
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<!-- The value of the "changeLogMembershipLdapSubjectId" attribute is the subject identifier of the "ldap" source member of a membership change log entry. --> <resolver:AttributeDefinition id="changeLogMembershipLdapSubjectId" xsi:type="ad:Script"> <resolver:Dependency ref="AddMembershipChangeLogDataConnector" /> <resolver:Dependency ref="DeleteMembershipChangeLogDataConnector" /> <ad:Script><![CDATA[ // Import Shibboleth attribute provider. importPackage(Packages.edu.internet2.middleware.shibboleth.common.attribute.provider); // Create the attribute to be returned. changeLogMembershipLdapSubjectId = new BasicAttribute("changeLogMembershipLdapSubjectId"); // Return 'subjectId' attribute values if the 'sourceId' attribute is 'ad'. if (typeof sourceId != "undefined" && sourceId != null ){ if (sourceId.getValues().contains("ad")) { if (typeof subjectId != "undefined" && subjectId != null ){ changeLogMembershipLdapSubjectId.getValues().add(subjectId.getValues().get(0)); } } } ]]></ad:Script> </resolver:AttributeDefinition> |
Configure LDAP Subject Source in Grouper UI
...
Copy sources.xml
and ldap.properties
from the Grouper API to the Grouper UI.
...
No Format | ||
---|---|---|
| ||
# edu.vt.middleware.ldap.searchResultHandlers=edu.internet2.middleware.psp.ldap.QuotedDnResultHandler,... |
Configure LDAP Subject Source in Grouper WS
TODO
Configure Grouper Stem to be Provisioned
...
Configure the name of the Grouper stem to be provisioned, by default this is the root stem, which is the empty string.
...
No Format | ||
---|---|---|
| ||
# The base Grouper stem to be provisioned. edu.internet2.middleware.psp.baseStem= |
Configure Grouper Change Log
...
The Grouper change log is configured in grouper-loader.properties
.
...
The Quartz cron string documentation is here.
Configure Grouper Logging
...
You may want to change the Grouper log file appenders in grouper.apiBinary-2.1.0/conf/log4j.properties
.
No Format | ||
---|---|---|
| ||
log4j.appender.grouper_error = org.apache.log4j.DailyRollingFileAppender log4j.appender.grouper_error.File = ${grouper.home}logs/grouper_error.log log4j.appender.grouper_error.DatePattern = '.'yyyy-MM-dd log4j.appender.grouper_event = org.apache.log4j.DailyRollingFileAppender log4j.appender.grouper_event.File = ${grouper.home}logs/grouper_event.log log4j.appender.grouper_event.DatePattern = '.'yyyy-MM-dd |
Configure Grouper Versions Prior to 2.1.0
...
Note |
---|
The following changes are necessary to support provisioning Grouper API versions prior to 2.1.0 with the psp. |
...
3. For Grouper API versions prior to 2.1.0, the ldap source adapter in subject.jar
does not provide the method which allows the psp to re-use the same ldap connection as the subject source. You will need to copy lib/grouper/subject.jar
from the Grouper 2.1.0 API distribution to your pre-2.1.0 Grouper API installation.
Configure Subject API Cache
...
The Subject API cache is configured in grouper.ehcache.xml
.
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<!-- Subject resolving caching --> <!-- @see CachingResolver#find(...) --> <cache name="edu.internet2.middleware.grouper.subj.CachingResolver.Find" maxElementsInMemory="5000" eternal="false" timeToIdleSeconds="30" timeToLiveSeconds="120" overflowToDisk="false" statistics="true" /> <!-- @see CachingResolver#findAll(...) --> <cache name="edu.internet2.middleware.grouper.subj.CachingResolver.FindAll" maxElementsInMemory="5000" eternal="false" timeToIdleSeconds="30" timeToLiveSeconds="120" overflowToDisk="false" statistics="true" /> <!-- @see CachingResolver#findByIdentifier(...) --> <cache name="edu.internet2.middleware.grouper.subj.CachingResolver.FindByIdentifier" maxElementsInMemory="5000" eternal="false" timeToIdleSeconds="30" timeToLiveSeconds="120" overflowToDisk="false" statistics="true" /> <!-- @see CachingResolver#findByIdOrIdentifier(...) --> <cache name="edu.internet2.middleware.grouper.subj.CachingResolver.FindByIdOrIdentifier" maxElementsInMemory="5000" eternal="false" timeToIdleSeconds="30" timeToLiveSeconds="120" overflowToDisk="false" statistics="true" /> |
Configure PSP : Provisioning Service Provider
...
The psp configuration files are :
| Configuration for the objects, identifiers, attributes, and references to be provisioned to a target. |
| Configuration for the Shibboleth attribute resolver. |
| Configuration for Shibboleth services such as the attribute resolver, psp, and provisioning targets. |
| Bootstraps Shibboleth. |
Configure PSP : SPMLv2 Provisioned Objects, Identifiers, Attributes and References
...
The objects, identifiers, attributes, and references to be provisioned are defined in psp.xml
.
Configure PSP : Provisioned Objects
...
Provisioned objects, or in SPMLv2 terms Provisioning Service Objects, consist of identifiers, attributes (probably), and references (maybe) to the identifiers of other objects, which are most likely located on the same provisioning target.
...
property | default | value |
---|---|---|
|
| the unique id of the provisioned object |
| | If |
|
| The id of an attribute resolver definition whose values are all source identifiers applicable to this provisioned object. |
Configure PSP : Identifiers
...
Identifiers consist of a string ID, a target ID, and possibly a container ID. We consider a container ID to be similar to an ldap base dn. A container ID is itself an identifier, recursing potentially indefinitely.
...
Code Block | ||
---|---|---|
| ||
dn: cn=group,ou=groups,dc=example,dc=edu |
Configure PSP : Identifying Attribute
...
The optional <identifyingAttribute/>
of a provisioned object has two purposes : (1) to determine the schema entity of target objects returned from a lookup or search request and (2) to be converted to a query when searching a target for all identifiers. If <identifyingAttribute/>
is not present, the provisioned object will be ignored during bulk requests.
...
For example, in the configuration example above, the psp will perform an ldap search with filter "(objectClass=organizationalUnit)" to retrieve the identifiers of all provisioned stems as well as an ldap search with filter "(objectclass=groupOfNames)" to retrieve the identifiers of all provisioned groups. The base of each search will be the containerId of the <identifier/>
element.
Configure PSP : Alternate Identifier
...
The optional <alternateIdentifier/>
element configures the psp to rename provisioned objects. It refers to an attribute resolver definition whose value is the previous (old) identifier of an object after it has been renamed. If <alternateIdentifier/>
is not present, provisioned objects will not be renamed, instead the old object will be deleted and a new object created.
...
property | value |
---|---|
| The id of the Shibboleth attribute definition whose value is the previous SPMLv2 PSO Identifier. |
Configure PSP : Attributes
...
Name value pairs. Probably multi-valued. Case sensitive names and values. We return values in the same order as they were given to us.
...
Code Block | ||
---|---|---|
| ||
dn: cn=group,ou=groups,dc=example,dc=edu cn: group |
Configure PSP : References
...
A reference refers to the identifier of another object. It consists of two identifiers, the "from object" and the "to object". A node in a directed graph. Directional.
...
Code Block | ||
---|---|---|
| ||
dn: cn=group,ou=groups,dc=example,dc=edu cn: group member: uid=person,ou=people,dc=example,dc=edu dn: uid=person,ou=people,dc=example,dc=edu ... |
Configure PSP : Attribute Resolver
...
The values of the identifiers, attributes, and references to be provisioned are defined by a Shibboleth attribute resolver configuration psp-resolver.xml
.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<!-- The attribute resolver. --> <Service id="psp.AttributeResolver" xsi:type="attribute-resolver:ShibbolethAttributeResolver"> <ConfigurationResource file="/psp-resolver.xml" xsi:type="resource:ClasspathResource"> <ResourceFilter xsi:type="grouper:ClasspathPropertyReplacement" xmlns="urn:mace:shibboleth:2.0:resource" propertyFile="/ldap.properties" /> </ConfigurationResource> </Service> |
Configure PSP : Attribute Resolver and Grouper Integration
TODO
Configure PSP : Attribute Resolver and Grouper ChangeLog Integration
TODO
Configure PSP : Attribute Resolver and Grouper Attribute Framework Integration
...
To provision an attribute sourced from the Grouper Attribute Framework, the attribute must be defined in a <grouper:Attribute id="etc:attribute:name"/>
element of a Grouper data connector.
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<resolver:DataConnector id="GroupDataConnector" xsi:type="grouper:GroupDataConnector"> <!-- The "etc:attribute:mailLocalAddress" attribute framework definition. --> <grouper:Attribute id="etc:attribute:mailLocalAddress" /> </resolver:DataConnector> |
Configure PSP : Logging and Output
...
The psp is a Shibboleth service which is configured in psp-services.xml
.
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<!-- The provisioning service provider. --> <Service id="psp" xsi:type="psp:ProvisioningServiceProvider" depends-on="psp.AttributeAuthority" authority="psp.AttributeAuthority" logSpml="true" writeRequests="false" writeResponses="false" pathToOutputFile=""> <ConfigurationResource file="/psp.xml" xsi:type="resource:ClasspathResource"> <ResourceFilter xsi:type="grouper:ClasspathPropertyReplacement" xmlns="urn:mace:shibboleth:2.0:resource" propertyFile="/ldap.properties" /> </ConfigurationResource> </Service> |
Configure PSP : LDAP Target
...
The LDAP target to be provisioned is a Shibboleth service configured in psp-services.xml
.
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<!-- The ldap target. The ldapPoolIdSource is either "grouper" or "spring". --> <!-- If ldapPoolIdSource is "spring", the ldapPoolId must be the id of the ldap pool bean in the vt-ldap xml spring configuration. --> <!-- If ldapPoolIdSource is "grouper", the ldapPoolId must be the id of the LdapSourceAdapter in sources.xml --> <Service id="ldap" xsi:type="psp-ldap-target:LdapTarget" logSpml="true" ldapPoolId="ldap" ldapPoolIdSource="grouper"> <!-- A <ConfigurationResource/> is required to instantiate the <Service/>, so supply a do-nothing resource. --> <ConfigurationResource file="/edu/internet2/middleware/psp/util/empty-bean.xml" xsi:type="resource:ClasspathResource" /> </Service> |
Provision Grouper
...
Before you can provision anything from Grouper to ldap or anywhere else, you will need to create the corresponding objects in Grouper using the UI, API, GSH, WS, loader, import, etc.
Provision Grouper : GSH
...
To calculate how a group should be provisioned :
...
bin/gsh.sh -psp -sync edu:group
Provision Grouper : Grouper Change Log
...
To provision in real-time triggered by the Grouper change log, enable the psp consumer in grouper-loader.properties
and run the loader via
bin/gsh.sh -loader
Real-Time Provisioning Beta-Testing : Grouper Subject Sources
...
Institution | Subject Source | Number of Subjects | Subject ID |
---|---|---|---|
LIGO | LDAP | 1,000 | dn: employeeNumber=882,ou=people,dc=ligo,dc=org |
Penn State | LDAP | 165,000 | dn:uid=xyx123,dc=psu,dc=edu |
UCLA | LDAP | 40,000 |
|
UMontreal | LDAP | 120,000 | sAMAccountName (value same as cn) |
UVienna | Undecided | 155,000 | cn, uid |
UWMadison |
|
|
|
Real-Time Provisioning Beta-Testing : Provisioning Targets
Institution | Target | Implementation |
---|---|---|
LIGO | LDAP | OpenLDAP 2.4.x |
Penn State | LDAP | IBM Tivoli Directory Server |
UCLA | LDAP | Sun Java System Directory Server Enterprise Edition 6.3.1 |
UMontreal | LDAP | Active Directory |
UVienna | LDAP | Active Directory, OpenLDAP |
UWMadison |
|
|
Real-Time Provisioning Beta-Testing : Provisioning memberOf
The groups that a member is a member of may be provisioned to the memberOf attribute. Some LDAP implementations, such as Active Directory, automatically maintain the memberOf attribute. OpenLDAP maintains the memberOf attribute automatically via the memberOf overlay. The value of the memberOf attribute is typically a group DN.
Institution | memberOf for members (people) | memberOf for groups |
---|---|---|
LIGO | + |
|
Penn State | + |
|
UCLA | - |
|
UMontreal | automatic (Active Directory) | automatic (Active Directory) |
UVienna | automatic (Active Directory), OpenLDAP+memberOf | automatic (Active Directory), OpenLDAP+memberOf |
UWMadison | + |
|
Real-Time Provisioning Beta-Testing : Provisioning eduMember
The eduMember objectClass defines the isMemberOf and hasMember attributes, whose values are identifiers which are not DNs.
Institution | isMemberOf | hasMember |
---|---|---|
LIGO | + | + |
Penn State | + | + |
UCLA | uclaIsMemberOf | uclaHasMember |
UMontreal | - | - |
UVienna | - | - |
UWMadison | + | + |
Real-Time Provisioning Beta-Testing : Provisioning eduCourse
The eduCourse objectClass defines course related attributes.
Institution | eduCourse |
---|---|
LIGO | - |
Penn State | - |
UCLA | - |
UMontreal | - |
UVienna | - |
UWMadison | + |
Real-Time Provisioning Beta-Testing : Provisioning Structure
The group provisioning structure may be either flat
or bushy
. A flat
structure provisions all groups into a single container. A bushy
structure provisions groups hierarchically.
...
Institution | Structure (flat or bushy) |
---|---|
LIGO | bushy |
Penn State | flat |
UCLA | flat |
UMontreal | bushy |
UVienna | ? |
UWMadison | flat |
Real-Time Provisioning Beta-Testing : Membership Structure
Given groupA with memberA and groupB with memberB :
...