Delegated Access and Shopping Period Tools
The delegated access tool controls both delegating access to users outside of the site membership realm as well as setting up and controlling site shopping period information. To make it easier to describe, I will break the description into two tools: “Delegated Access Tool” and “Shopping Period Tool”.
Delegated Access Tool:
The delegated access tool has five primary functionalities:
- Provide a friendly interface for administrators to delegated user access to specific sites or department levels.
- Provide a friendly interface for administrators to delegated shopping period admin privileges for users at the site or departments level.
- Provide a friendly interface for delegated users to view, search and access their delegated sites.
- Provide a friendly interface for delegated shopping period admins to adjust shopping period data within their scope of privileges.
- Allow a user, who have been granted access to sites, to use the direct URL for the site to access it.
The delegated access tool allows administrators to search for users and delegate site, role, and shopping period admin access. It also allows you to select specific tools the user should not have access to.
The easiest way to think of how the tool works is liking it to the Role Swap feature in Sakai. Instead of just swapping the role, you can specify the realm and role the user will receive for that particular site or node in the hierarchy. All child nodes will inherit the parent settings unless overridden.
Shopping Period Tool:
The shopping period tool is just a special use case of the Delegated Access Tool from the perspective of shopping consumer. In another words, we treat the .anon or .auth role as a delegated user which we can determine what role they will inherit when they enter a site. There are three user cases that the shopping period section handles:
User Case: Administrator:
When a user who has been granted shopping period administrative privileges goes into the delegated access tool, they will see a link for “Shopping Period Admin”. Here they can modify what role a .anon or .auth (public/logged in) user will inherit when they enter. They can also choose which tools are open as well as the open and close date for the shopping period for that site or department.
Use Case: Instructor:
If you enable the instructor to override shopping settings, then the instructor will have an interface in the "Site Info" tool under the link "Manage Access" where he/she can modify their course's shopping settings. This allows an instructor to opt in or out of the shopping period.
User Case: Shopper:
When a user who wants to shop for a particular site goes to the Shopping Period tool, they will see a node structure and a search box to look for a particular site they want to test out. This tool, for example, can be added to Sakai’s !Gateway site so unauthorized users can view it. When the user finds the site they want, they just click the link and go to the site.
Authorship and Licensing
The Delegated Access Tool was developed by the Longsight Group under contract with Columbia University. It is licensed under the Educational Community License, Version 2.0.
- log into http://nightly2.sakaiproject.org:8085/portal
- username: admin
- pw: admin
- Add "Delegated Access" to your My Workspace.
- Note: you have to do by going to "Worksite Setup" in your My Workspace site then find your My Workspace site in the list and click the checkbox next to it. Then you click "Edit" on the top. This will bring you to the "Site Info" page where you can click "Edit Tools". In this page, you check "Delegated Access" and click save to add this tool to your My Workspace site.
- Go to tool.
- To start you can see how it looks to have access delegated to you by clicking "Search Users" and searching for yourself ("admin"). This is where you can grant access to specific nodes in the hierarchy. Checking the boxes will enable the permissions. Doing this enables additional options in the tool which will show up when refreshed.
Delegated Access Landing Page
This page will show which sites you’ve been granted access to. You can search your sites or click the title in the node tree.
Site Search Page
This page allows you to search through the sites by site id, site title, site term, or instructors
User Search Page
This page allows Sakai Administrators to search for user’s to grant privileges to.
Edit User Privileges Page
This page is where you set a user’s access and shopping admin privileges.
Shopping Period Settings Page
This is the page where a shopping period administrator can edit the shopping period information for their sites or departments.
Shopping List Page
This page is where you can search for reports on the current status of active shopping sites as well as all shopping settings
Shopping Period Page
This is the page where a use would access to shop for sites that are open to shopping.
Instructor Shopping Period Edit Page
This page allows an instructor to set their own shopping period status for their site. This is controlled by a sakai.property. An instructor can access it by going to "Site Info -> Manage Access" in their site.
Source Location and Patches
Delegated access can run in Sakai 2.8.2+ and 2.9.0+
Delegated Access Tool:
https://source.sakaiproject.org/contrib/caret/hierarchy/ (*1.2.6+ recommended)
- Sakai 2.7.x Backport Patch (only if you want to run this in 2.7.x)
- apply commits in SAK-22079 and KNL-919
- Running in an large institution:
- Run trunk Hierarchy Tool (or a version that includes contrib r78264) (DAC-2)
- You will also need to set the following Columns to "Clob" for Oracle or "mediumblob" for MySQL
Using the Tool
Adding the Tool
There are two tools for delegated access:
The “sakai.delegatedaccess” tool is set so anyone can add it to their MyWorkspace. This isn’t a security issue since only Sakai Administrators have the ability to delegate site access and shopping period administration privileges. If a user doesn’t have any privileges, it will just say they have no access. You will want to add this to the Administration Workspace site.
The “sakai.delegatedaccess.shopping” tool is just a read only view of the Shopping period sites that are actively ready to be accessed. This should be added somewhere where .anon user’s can access it. One suggestion would be the !Gateway page.
Create a Site Hierarchy
The default hierarchy is based on a site's property values (in order):
You can overwrite the hierarchy structure in sakai.properties with:
Once you have set up your hierarchy properties, you will need to add these properties to your sites. This should be done during your site integration job.
Site Hierarchy Quartz Job
The name of the quartz job is: Delegated Access Site Hierarchy Job
This is the default quartz job to populate/update(add/remove) the Delegated Access site hierarchy. It searches through all sites in Sakai and looks for structure properties tied to the site. You can run it as many times as you want. The best bet would be to set up a quartz trigger to go off after every time your site integration runs. This job will add/move/remove site’s within the hierarchy.
Shopping Period Quartz Job
The name of this quartz job is: Delegated Access Shopping period Job
This is the job that will populate the shopping period access tree. It should be ran every morning (sometime after midnight). This is used to open and close the shopping period for sites based on their open and close dates.
Sakai Administrator User Use Case
Go to the tool and click "Search Users" and find a user you want to delegate access for. Click their name.
The edit user page allows you to assign delegated access as well as shopping period admin permissions for this user.
For the "Shopping Admin" column, you can select the checkbox next to the level/site you want this user to have control over setting shopping period settings for. The nodes and children of the nodes you select for "Shopping Admin" will show up for the user in the "Shopping Period" link.
For the "Site Access" column, you can select which level/site you want the user to have access to. When you choose "Site Access", you must fill out what role the user will become when they visit that site or a site that under that level. You also have the ability to choose which tools are restricted for this user by clicking the "Restrict Tools" link. All child nodes will inherit their parents settings unless you have specifically overridden them. The nodes and children of the nodes you select for "Site Access" will show up for the user in the "Delegated Access" link. When you are done, click save or click cancel to undo all changes.
Delegated Access User Use Case
By default the tool can be added to a user's My Workspace. Since only administrators can delegate access, a regular user won't be able to modify anything. If the user doesn't have any access delegated to them, they will see a message saying so. Otherwise, you will see a node structure in which you can navigate and click on the sites you've been granted access to. Since this tool populates the delegated access information during login, a user could also use direct links to a delegated site.
Delegated Shopping Admin User Use Case
For a user who has been granted shopping admin privileges, they will be able to click the “Shopping Period” link on the top.
This page allows you to set the shopping period settings for the sites you've been granted permission to update. To set the shopping period settings, you can select the checkbox next to the level/site that you want to set. Note, you will only see a checkbox next to a node you have permission to modify. First, when you select a node, you must set the "Authorization" setting. The two options are ".anon" and ".auth". ".anon" is for anonymous users who do not need to log in to shop in this site. ".auth" is for users who must log in first in order to shop in this site. Next, you need to choose the role the user will become when they are shopping. Finally, you need to set the dates during which the shopping period will be open. You also have the ability to choose which tools are restricted for shoppers by clicking the "Restrict Tools" link and selecting the tools you want to restrict. All child nodes will inherit their parents settings unless you have specifically overridden them. When you are done, click save or click cancel to undo all changes.
Shopping Instructor Use Case
If the properties are set to allow instructors to modify shopping period settings, then the instructor just needs to go to "Site Info->Manage Access" and override the shopping period settings. The instructor can modify any setting for their site: Visibility, Start Date, End Date, Role, and Show Tools.
Shopping User Use Case
The shopping user is a person who is interested in trying a site that has been set up for shopping. This user will go to shopping period tool (more than likely in the !Gateway page). Here they will be able to see all their options in a node architecture and they will be able to search for sites by ID or Title. When they have found the site they want to shop for, they will click the link for that site and inherit the privileges for that shopping period.
- GET /direct/delegated_access/SITE_ID
- returns the node's shopping period information
- POST /direct/delegated_access/SITE_ID
- updates the node's shopping period information. Parameters include:
- shoppingAuth (string)
- shoppingStartDate (string)
- shoppingEndDate (string)
- shoppingRealm (string)
- shoppingRole (string)
- shoppingShowTools (string or string)
- directAccess (boolean)
- updates the node's shopping period information. Parameters include:
- GET /direct/delegated_access/shoppingOptions/authorization
- returns a list of available shopping period authorization options (i.e. .anon, .auth)
- GET /direct/delegated_access/shoppingOptions/roles
- returns a list of available shopping period roles
- GET /direct/delegated_access/shoppingOptions/tools
- returns a list of available shopping period tools to display
- GET /direct/delegated_access/access/site/SITE_ID
- returns a list of users who have access to the site
Basic Tree Structure
This is the tree structure for both the Shopping Period Tree and Delegated Access Tree.
Delegated Access Tree Node
This is the basic tree node structure for every node in the Delegated Access tree. The shopping period tree node is just 3 properties: Node Id, Site Id, Site Reference.
Site Hierarchy and Shopping Period Jobs
Delete a site from the shopping period hierarchy:
If you can't wait until the next time the site hierarchy job runs, run this script to get instant results. Make sure you update the shopping period tool as well so the next time the job runs it won't re-add this site.
This will remove the site from the shopping period hierarchy as well as clean up the site's realm roles and remove the site properties associated to the shopping period.
Changed hierarchy structure and need to reprocess sites
If you changed the hierarchy structure, you will need to re-process all sites with the Site Hierarchy Quartz Job. For performance reasons, there is a "job last successfully ran" time stamp that will only process sites that have been added/removed/modified since that date. In order to reprocess all sites, you will need to remove this flag like so:
WARNING: Switching the hierarchy can remove settings. For instance, if you have a 3 tier hierarchy and you add a new tier between 2 and 3 (e.g. 1->2->New->3->Site), all settings assigned to tier 3 and below will be deleted.