EZproxy/Blackboard Building Block Authorization Mapping

Lookup user

In the EZproxy/Blackboard Building Block properties, you can use "Lookup user" to verify the names and roles associated with particular users, which will help you build the authorization rules to allow and disallow access. In addition, "Lookup user" will verify whether or not the current rules allow specific users to gain access, and if you use group mappings, will allow you to test into which groups specific users will be mapped.

Working with a copy of your configuration

When you are developing a new authorization mapping, to minimize user disruption, you should use the Building Block copy feature to copy the existing EZproxy configuration to an alternate name, work on the alternative version to develop the mapping, use Lookup user on the alternative version to verify access, and then copy and paste the authorization mapping from the alternate version into the active version.

Contents of an authorization mapping

An authorization mapping is composed of a series of conditions that the Build Block should evaluate and a series of actions that the Building Block should take based on those conditions. In the absence of an authorization mapping, any user who can log into Blackboard is given access to EZproxy. Through an authorization mapping, you can fine-tune which users are able to access EZproxy, and you can also map users into groups to determine which users have access to which EZproxy resources.

Conditions

Course [-Literal] [-Role= SomeRole[,SomeRole]] CourseName

Tests to see if the user is a member of CourseName. Unless you include the optional -Literal qualifier, CourseName may include the wildcard * to match 0 or more characters and ? to match one or more characters. You can also use -Role to further specify that the user must have one or more specific roles in the course. Standard course roles include Student, Instructor, Grader, Teaching_Assistant, and Course_Builder.

If the user is in the Student role, then the Course must be available to the user for this test to be true.

DataSource [-Literal] DataSourceName

Tests to see if the user was loaded from the specified DataSourceName. Unless you include the optional -Literal qualifier, DataSourceName may include the wildcard * to match 0 or more characters and ? to match one or more characters.

NoGroups

NoGroups is true if the user has not been assigned to any groups.

Not

Not may appear in front of any condition to reverse the condition tested. For example, "Not User jdoe" would be true if the user did not have the username jdoe.

Portal -Role= SomeRole[,SomeRole]]

Tests to see if the user's is assigned one of the portal roles specified. Standard portal roles include Student, Faculty, Staff, and Alumni, along with a series of site-specific portal roles that can be found with the "Lookup user" feature.

User [-Literal] [-Role= SomeRole[,SomeRole]] UserName

Tests to see if the user's username matches Username. Unless you include the optional -Literal qualifier, UserName may include the wildcard * to match 0 or more characters and ? to match one or more characters. You can also use -Role to further specify that the user must have one or more specific system roles. Use the "Lookup user" feature to verify the system roles available on your system.

Actions

Deny denial message

Deny the user access and send the denial message to provide feedback on why access was denied. The denial message may not contain any semi-colons. This form is best for very short messages or testing. For longer messages, see Deny -Inline.

Deny -Inline

One or more lines of

denial text; may contain semi-colons.

/Deny

Deny the user access and send the message that appears after Deny -Inline up until the line that starts /Deny to provide feedback on why access was denied.

Deny -URL= http://www.yourlib.org/denied.html

Deny the user access and redirect the user to the specified URL to provide feedback on why access was denied.

Group [+|-]GroupName[[+|-]GroupName]

Add or remove the user from groups. Individual groups are separated by + and -. If the first group name does not start with + or -, all existing groups are removed from the user and the first specified group is added to the user. When a group name is preceded by +, the group is added to the user's authorized groups. When a group name is preceded by -, the group name is removed from the user's authorized groups. You can specify the special GroupName NULL to remove the user from all groups.

Stop

Stop indicates that authorization mapping should stop without consideration for anything else that follows.

Examples

In this example, any username that starts with abc is allowed to EZproxy, but all others are denied access.

User abc*; Stop

Deny -Inline

Only users whose usernames start with abc are allowed to

access EZproxy.

/Deny



In this example, all users are granted access to the EZproxy Default group. Users who are are enrolled in courses starting with Law. are included in the EZproxy Law group. Users who are enrolled in courses starting with Medical.* are included in the EZproxy Medical group. Users who are enrolled both a course that starts Law. and a course that starts with Medical. are included in the EZproxy MedicalLaw group. who are faculty in any course at all are included in the Faculty group.

Group Default

Course Law.*; Group +Law

Course Medical.*; Group +Medical

Course Law.*; Course Medical.*; Group +MedicalLaw

Course -Role=Faculty *; Group +Faculty



Creating/updating an authorization mapping

In older releases of Blackboard, the term System Extension appeared in places where Building Block now appears. If you are installing on an older release of Blackboard, the option to use at a given step may be named slightly differently from what is shown (e.g. for Manage Building Blocks, you might have Manage System Extensions instead).

1. Log in to Blackboard as a system administrator.
2. Go into the Blackboard System Admin area.
3. In Blackboard Building Blocks Management, click Manage Building Blocks.
4. Next to the EZproxy Building Block, click Properties.
5. If you need to create a new EZproxy Server Configuration, Add EZproxy server configuration and fill in the fields in Add EZproxy Server Configuration as follows:
   • Auth: pick an arbitrary text string to identify the EZproxy server.
   • EZproxy server URL: enter the URL to your EZproxy server, including the port number if your server requires a port (e.g. http://ezproxy.yourlib.org:2048 ).
   • SHA1 shared secret: this is an arbitrary string used to digitally sign the information sent to the EZproxy server. The SHA1 secret should be kept secure. If compromised, you can change it on this page and in the user.txt/ezproxy.usr configuration file to a new value.
   • Authorization Mapping: leave this blank or enter the initial authorization mapping.
   • Click Submit. If necessary, correct errors, then submit again until the configuration is accepted. Click OK.
6. For an existing EZproxy configuration, click Modify to access and update the authorization mapping.
7. If you change group assignments, make certain to click the Suggested user.txt/ezproxy.usr configuration to check if the AcceptGroup directive changes.
8. As you make changes to the authorization mapping, use the Lookup user feature to enter various usernames and receive feedback regarding the type of access that will be granted to the user.