Setting up the Grouper and Signet Databases

1. Setting up the Grouper and Signet Databases Joy Veronneau Cornell University Identity Management November 7, 2006

4. Introduction • Grouper and Signet rely on Hibernate technology to integrate with a variety of RDBMS systems. • Also see the Signet and Grouper Wikis for Hibernate configuration information.

5. Let’s talk about first…

6. grouper.hibernate.properties • See sample grouper/conf/grouper.hibernate.properties in Appendix 2 of handout. • Comes pre-populated for HSQLDB, PostgreSQL, and Oracle - just comment and uncomment the appropriate sections. • Hibernate uses JDBC - fill in: • hibernate.connection.driver_class (JDBC driver classname) • hibernate.connection.url (JDBC URL for the database) • hibernate.connection.username (database user) • hibernate.connection.password (database user’s password)

7. Grouper/Oracle Example • At Cornell, we are using an Oracle database for the groups registry.

8. Grouper/Oracle cont’d • Remember to uncomment this line if you are using Oracle: (You can also fix any spelling mistakes you might find.)

9. Ready, Set … • If your configuration is ready, the next thing you need to do is initialize your database. • Don’t forget to put your classes.jar file in the grouper/lib directory (e.g. oracle-classes12.jar) • You may want to edit your log4j.properties file if you haven’t already.

10. Go! • Switch into the grouper directory and type “ant schemaexport” - this command generates the DDL (Data Definition Language) appropriate for your configured RDBMS and installs the tables. • Then type “ant db-init”. This command populates various tables with required logical schema information and creates the root naming stem of the Groups Registry. • These ant commands will produce errors if you haven’t configured your log files correctly in log4j.properties. But the commands will still work after Grouper complains a little.

11. Grouper FAQ Number 2: Q: "ant schemaexport" creates 14 tables, 2 of which are "subject" and "subjectattribute". Do I need these? A: No. They are there only to support the quickstart demo and testing the API. They can safely be removed or ignored *if* your subjects are coming from another source, e.g. an LDAP directory.

12. Grouper FAQ Number 6: Q: I am using Oracle for my Grouper database, and when I try to add more groups or members, I am getting this error: "hibernate commit error: Could not execute JDBC batch update." What causes that? A: One cause may be that you have run out of tablespace - try extending your tablespace for the Grouper database. Cornell currently has the tablespace set to 1Gb, just a rough guess based on preliminary data loads.

13. Grouper/Oracle cont’d • The Oracle database schema has been modified between version 1.0 and 1.1 of Grouper. If you are upgrading from 1.0, you should export the GROUPER_MEMBERSHIPS table, reorder the columns and import the GROUPER_MEMBERSHIPS table for much better performance.

14. Audience Participation • Any experience using Grouper with PostgreSQL or HSQLDB?

15. Special Grouper Subjects:GrouperAll • The GrouperAll subject is hard-wired. • GrouperAll means *any* subject. • When you select “Assign the following default privileges for everyone” in the UI, you are actually assigning them to the “GrouperAll” subject. • You will see GrouperAll appear in the UI when you look at who has group privileges such as VIEW and READ.

17. Special Grouper Subjects:GrouperSystem • The super-user… • If you are using an SSO system and/or outside subject sources, you probably won’t be able to sign on as GrouperSystem but… • You can create a Grouper “wheel” group whose members are the security equivalent to “GrouperSystem”. • If you are a member of the “wheel” group, the UI gives you a choice whether to act as yourself with normal privileges, or as “admin” which means “GrouperSystem”.

18. Setting up the Grouper Wheel Group • See instructions in the Wiki Documentation section: “Initializing Administration of Grouper Privileges.” • Use gsh to create the group, and edit the grouper.properties file. • Sample grouper.properties file in Appendix 4 of handout. • Joy sez: “Make a script, you will have to do this more than once when you are starting out!”

19. The gsh Utility (Grouper Shell) • My favorite utility - a tool for interacting with the Grouper API. • Script (batch) and interactive modes. • The Grouper Wiki has instructions for how to build and use it. • Use special gsh commands or *any* API command.

20. Useful gsh Variables

21. Create “wheel” Group - Sample gsh Script

22. Grouper XML Export • Exported XML may be used for: * provisioning other systems * reporting * backups * switching database backends - including to upgraded schemas (required by new Grouper API versions) in the same database

23. Grouper XML Import • Useful for: * loading - adding to or updating existing Stems, Groups and Group Types. Whole or partial Grouper registries can be exported, and subsequently imported at a specified Stem (or the Root Stem if not specified) in the new instance. * initializing a new, empty registry to a known state - useful for demos, testing and system recovery

24. Sample Grouper XML export command • Remember to create an export.properties file. • From grouper directory, this will export the cu:ga stem which has the wheel group in it: ant xml-export -Dcmd="GrouperSystem -name cu:ga x.xml"

25. What the Export xml Looks Like

26. Setting up the Database

27. Set Up the Signet Database • Instructions on the Signet Wiki • The DDL for each supported database is found in the signet/sql directory. • Signet currently provides DDL for: * HSQL * Oracle * Postgres * Sybase • Execute with your favorite tool (Aqua for Mac, dbArtisan for Windows)

28. Copy Your Driver • For Oracle this is oracle-classes12.jar • An appropriate driver must be installed in two places, as there are two parts to Signet that operate independently - the Web application and the utilities. * signet/lib * signet/webapp/signet/WEB-INF/lib

29. Two Different Versions of Hibernate? • It’s just an accident that Signet uses XML for the Hibernate configuration and Grouper doesn’t. • Currently Grouper (& Subject) use v2.1.8 of Hibernate. Signet uses some earlier v2. • Normalization of third party libraries common to Signet and Grouper is being addressed.

30. Edit signet/config/hibernate.cfg.xml • See sample hibernate.cfg.xml in Appendix 3 of handout. • Configures your JDBC connection. • Edit two copies of the hibernate.cfg.xml file: • signet/config/hibernate.cfg.xml • signet/webapp/signet/WEB-INF/classes/hibernate.cfg.xml

31. Sample signet/config/hibernate.cfg.xml for Oracle

32. The Special “Signet” Subject • Built into Signet • The Signet subject is the source of granted privileges over internal Signet system actions as described below. • The Signet subject is the actor on any system-initiated action, e.g., it will be identified as the "revoker" when a lifecycle event (expiration or affiliation change) causes the automatic revocation of services.

33. “Signet” Subject - more • The Signet subject has hard-wired granting powers over all functions in all subsystems. Note that Signet can extend capabilities to others (can grant), but cannot itself act on those privileges.

34. Giving the Signet System Administrator Initial Power • Use the Signet proxy tool to grant System Administrator privileges (described in the Wiki) • ./run.sh grant jv11@cornell.edu • Possible commands: grant, revoke, list