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.
Real-time provisioning is available from the provisioning service provider (psp, formerly known as ldappcng) as of version 2.1.0. It should be possible to install and configure the psp for Grouper versions 1.6 and up.
These instructions assume that Grouper subjects are already provisioned to your ldap directory, and makes use of the vt-ldap based ldap source adapter.
These instructions target Mac OS X, other platforms should be similar.
Once you have a working Grouper API installation, you will need to install and configure the psp.
You do not need to install Grouper again if you already have a working Grouper API deployment.
To install Grouper, download and run the Grouper Installer, available as of version 2.0, and follow the prompts.
curl http://www.internet2.edu/grouper/release/2.1.0/grouperInstaller.jar -O java -jar grouperInstaller.jar |
You may want to unlimit the number and size of the Grouper log files by commenting out or removing those limits in grouper.apiBinary-2.1.0/conf/log4j.properties
.
# log4j.appender.grouper_event.MaxFileSize = 1000KB # log4j.appender.grouper_event.MaxBackupIndex = 1 # log4j.appender.grouper_error.MaxFileSize = 1000KB # log4j.appender.grouper_error.MaxBackupIndex = 1 |
Download and unpack the psp.
The distribution name is of the form
grouper.psp-2.1.0-SNAPSHOT.tar.gz
or
grouper.psp-2.1.0-SNAPSHOT.zip
.
curl http://www.internet2.edu/grouper/release/2.1.0/grouper.psp-2.1.0-SNAPSHOT.tar.gz -O tar xzf grouper.psp-2.1.0-SNAPSHOT.tar.gz |
Copy jars located in lib/custom
from the psp distribution to the Grouper API installation. Many jars are dependencies of the Shibboleth attribute resolver and may not be necessary in your deployment.
cp -vR grouper.psp-2.1.0-SNAPSHOT/lib/custom/ grouper.apiBinary-2.1.0/lib/custom/ |
Copy example configuration files located in conf
from the psp distribution to the Grouper API installation.
If you have already configured |
cp -vR grouper.psp-2.1.0-SNAPSHOT/conf/psp-example-grouper-to-tivoli/ grouper.apiBinary-2.1.0/conf/ |
You will need to configure Grouper to look for subjects in your ldap directory and you will need to configure how groups, stems, and memberships are provisioned to your ldap directory by the psp.
The psp configuration files are :
|
Maps source attributes returned by a Shibboleth attribute resolver to target objects. |
|
The Shibboleth attribute resolver configuration file. |
|
Configures Shibboleth attribute resolver services, including provisioning targets. |
|
Bootstraps the Shibboleth attribute resolver. |
The configuration files for Grouper ldap subjects are :
|
Configures Grouper subjects. |
|
The vt-ldap configuration. Also used for macro replacement in the psp configuration files. |
ldap.properties
Change the default base DN for ldap searches to match your ldap directory :
edu.vt.middleware.ldap.baseDn = dc=example,dc=edu |
Configure authentication and encryption :
edu.vt.middleware.ldap.serviceUser=cn=Manager,dc=example,dc=edu edu.vt.middleware.ldap.serviceCredential=secret |
Change the default base DN (container) for provisioning people and groups :
# 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 |
sources.xml
Change the base DN in the multiple search configuration elements :
<param-name>base</param-name> <param-value>ou=people,dc=example,dc=edu</param-value> |
For versions previous to 2.1.0, there is a bug which will throw a NullPointerException if the following is not present in sources.xml
:
<search> <searchType>searchSubjectByIdentifierAttributes</searchType> <param> <param-name>filter</param-name> <param-value> (&(uid=%TERM%)(objectclass=person)) </param-value> </param> <param> <param-name>scope</param-name> <param-value>SUBTREE_SCOPE</param-value> </param> <param> <param-name>base</param-name> <param-value>ou=people,dc=example,dc=edu</param-value> </param> </search> |
For versions previous to 2.1.0, the location of ldap.properties
specified in sources.xml
must be an absolute path. For versions 2.1.0 or later, the location of ldap.properties
may be an absolute path or in your Java classpath. For example, for version 2.0.3 in sources.xml
:
<init-param> <param-name>ldapProperties_file</param-name> <param-value>/opt/grouper/2.0.3/grouper.apiBinary-2.0.3/conf/ldap.properties</param-value> </init-param> |
You may need to copy sources.xml and ldap.properties to your Grouper UI installation.
If you installed the Grouper UI via the Grouper Installer, copy ldap.properties
and sources.xml
from the Grouper API installation to the Grouper UI installation :
cp grouper.psp-2.1.0-SNAPSHOT/conf/psp-example-grouper-to-tivoli/ldap.properties grouper.ui-2.1.0/dist/grouper/WEB-INF/classes/ cp grouper.psp-2.1.0-SNAPSHOT/conf/psp-example-grouper-to-tivoli/sources.xml grouper.ui-2.1.0/dist/grouper/WEB-INF/classes/ |
You will also need to copy the vt-ldap jar from the Grouper API installation to the Grouper UI installation :
cp grouper.apiBinary-2.1.0/lib/custom/vt-ldap-3.3.4.jar grouper.ui-2.1.0/dist/grouper/WEB-INF/lib |
The Grouper UI will not load unless you edit |
Comment out or remove the psp specific search result handlers in ldap.properties
in your Grouper UI installation :
# edu.vt.middleware.ldap.searchResultHandlers=edu.internet2.middleware.psp.ldap.QuotedDnResultHandler,... |
Before you can provision a group, stem, or membership from Grouper to ldap, you will need to create the corresponding objects in Grouper using the UI, API, GSH, WS, loader, import, etc.
To calculate how a group should be provisioned :
bin/gsh.sh -psp -calc edu:group |
To diff the current and correct provisioning of a group :
bin/gsh.sh -psp -diff edu:group |
To provision or synchronize a group :
bin/gsh.sh -psp -sync edu:group |
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 |
|
|
|
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 |
|
|
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 |
+ |
|
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 |
+ |
+ |
The eduCourse objectClass defines course related attributes.
Institution |
eduCourse |
---|---|
LIGO |
- |
Penn State |
- |
UCLA |
- |
UMontreal |
- |
UVienna |
- |
UWMadison |
+ |
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.
For example, the DN of a group with name 'edu:stem:group' in a flat
structure looks like :
dn: cn=edu:stem:group,ou=groups,dc=example,dc=edu
while the DN of a group with name 'edu:stem:group' in a bushy
structure looks like :
dn: cn=group,ou=stem,ou=edu,ou=groups,dc=example,dc=edu
Institution |
Structure (flat or bushy) |
---|---|
LIGO |
bushy |
Penn State |
flat |
UCLA |
flat |
UMontreal |
bushy |
UVienna |
? |
UWMadison |
flat |
Given groupA with memberA and groupB with memberB :
dn : cn=groupA,ou=groups member: cn=memberA,ou=people dn: cn=groupB,ou=groups member: cn=memberB,ou=people |
If groupB is added as a member to groupA, how do you want groupA to be provisioned :
everything :
dn : cn=groupA,ou=groups member: cn=memberA,ou=people member: cn=memberB,ou=people member: cn=groupB,ou=people |
immediate :
dn : cn=groupA,ou=groups member: cn=memberA,ou=people member: cn=groupB,ou=people |
The everything membership structure handles applications which may not support nested groups and represents the nested structure of the group memberships.
The same membership structure applies to memberOf :
everything :
dn: cn=memberB,ou=people memberOf: cn=groupB,ou=groups memberOf: cn=groupA,ou=groups |
immediate :
dn: cn=memberB,ou=people memberOf: cn=groupB,ou=groups |
Institution |
member |
memberOf |
---|---|---|
LIGO |
everything |
everything |
Penn State |
|
|
UCLA |
|
|
UMontreal |
immediate |
immediate |
UVienna |
everything |
everything |
UWMadison |
|
|