Breadcrumbs

Suspend rules

You can configure a local connection to suspend users' access automatically under specified rules. User accounts that match the conditions of a suspend rule no longer have access to resources and are shown in the account list as suspended.

Suspend rules are custom. You can base them on any attribute or combination of attributes passed by the local source. For example, if you manage users through SirsiDynix, you could base a rule on the SirsiDynix attribute patronStatusInfo.statusType. You do not need to map local attributes to OpenAthens attributes when using them in a suspend rule.

Suspend rules apply only to local user accounts.

Structure of a suspend rule

A suspend rule consists of one or more conditions. Each condition has three parts:

  • The local attribute on which the condition is based. For example, ‘role’ or ‘status’

  • The value against which to test the attribute. For example, ‘staff' or ‘inactive’

  • The test to perform. For example, ‘matches’, ‘contains' or ‘does not match’

If a rule has more than one condition, you can require any or all of the conditions to be true. If you specify any, users who meet at least one condition in the rule will be suspended. If you specify all, only users who meet all of the conditions will be suspended.

Example rules

Example 1

Suspend account when any of these conditions are met:

memberOf contains visitor

memberOf contains walk-in

Suspends user accounts whose memberOf attribute contains either of the values ‘visitor’ or ‘walk-in’.

Example 2

Suspend account when all of these conditions are met:

memberOf contains staff

memberOf contains temporary

Suspends user accounts whose memberOf attribute contains both of the values ‘staff’ and ‘temporary’.

Example 3

Suspend account when all of these conditions are met:

department does not match physics

department does not match chemistry

Suspends accounts for all users who belong to neither the physics nor chemistry departments.

Create a suspend rule

  1. Log in to the Compass admin area (https://admin.openathens.net) as an administrator.

  2. Go to Management > Connections.

    Main Connections page. In the left sidebar, under the subheading 'Local authentication', are a 'Create' button and a list of existing local connections.

  3. Under Local authentication in the left sidebar, select your local connection to edit it.

  4. Go to the Permissions tab.

    Permissions tab of a local connection called 'ADFS connection'. There is a drop-down selector called 'Add rule', followed by rules called 'Default permissions' and 'Permission sets attribute'. At the top right of the page is a 'Save changes' button.

  5. From the Add rule drop-down menu, select Suspend account.

    Permissions tab of 'ADFS connection'. The 'Add rule' drop-down menu is open to show two options, 'Permission set mapping' and 'Suspend account'. 'Suspend account' is highlighted.

    A template for creating a new suspend rule appears further down the page.

    Permissions tab of the 'ADFS connection'. Following the rules 'Default permissions' and 'Permission sets attribute' is a form for creating a suspend rule. The form has two elements, 'Rule name', which is a simple text field, and 'Suspend account when', which includes several conditions. At the bottom of the form are 'Done' and 'Cancel' buttons.

  6. In the Rule name field, enter a descriptive name for this rule.

    Text input field called 'Rule name'. It is marked as mandatory.

  7. Under Suspend account when, define the conditions of the rule. For each condition, you need to choose a local attribute to evaluate, the test to perform on the attribute, and the value to compare it against.
    First, from the drop-down menu, choose whether to match any or all of the specified conditions.

    Drop-down menu showing the options 'all' or 'any', preceded by the text 'Suspend account when...' and followed by the text 'of these conditions are met'.

    If you’re creating a simple rule with only one condition, you can choose either setting since they are effectively the same. If you’re creating a rule with more than one condition, select all to enforce the rule only if all of the specified conditions are met. Selecting any will enforce the rule if at least one of the conditions is met.

  8. In the first input field, enter the name of the local attribute on which to base the rule. Use the name by which the attribute is called in the local source. Attribute names are case sensitive.
    (In this example, the field is called ADFS claim. Its label will vary depending on the type of connection.)

    Text field labeled 'ADFS claim', followed by a drop-down selector that reads 'matches' and then another, unlabeled text field.

  9. From the drop-down list, select the test to perform on the attribute.

    Drop-down selector with the default value of 'matches', expanded to show the full list of options.


    The options are:

    • matches

    • does not match

    • starts with

    • ends with

    • contains

    • does not contain

    • has a value

  10. In the last field, enter the required value for the condition. For example, if you wanted to suspend the account of anyone named ‘Smith’, you would enter ‘Smith’ in this field; the complete rule would be something like ‘name | contains | Smith’.

    A completed rule. The field 'ADSF claim' contains the value 'name'. The drop-down selector is set to 'contains'. The final field contains the value 'Smith'. Following these controls is a button marked with a plus sign. At the bottom are 'Done' and 'Cancel' buttons.

  11. This creates a simple rule with a single condition. To add more conditions for a more complex rule, press the plus button to generate another set of input fields. Repeat as necessary. (If you add fields and then decide not to use them, press the minus button to remove them before you submit.)

    Create rule interface showing a second, blank set of fields beneath the 'name contains Smith' condition. Following these fields is a button marked with a minus sign. Finally, there are 'Done' and 'Cancel' buttons.

  12. When you’ve finished, press Done. Your new rule appears in the list of rules. Check that the rule is correctly configured.

    Permissions tab for the connection called 'ADFS connection'. Following the existing rules, there is a new rule called 'Test'. This rule is described as 'Suspend account when all of the following match - name contains Smith'. Following this is a label that reads 'Suspend account'.

  13. Repeat to add any other rules that are required.

  14. Press Save changes to put your changes live.

Edit a suspend rule

  1. Go to Management > Connections.

    Main Connections page. In the left sidebar, under the subheading 'Local authentication', are a 'Create' button and a list of existing local connections.

  2. Under Local authentication in the left sidebar, select the required local connection.

  3. Go to the Permissions tab.

  4. In the list of rules, hover over the rule you want to edit. Edit and Remove buttons appear.

    Permissions tab of a connection called 'ADFS connection', showing a list of existing rules. Next to a rule called 'Test' are buttons labeled 'Edit' and 'Remove'.

  5. Press Edit. The details of the rule appear on screen.

    Details of a rule called 'Test'. The 'Rule name' field and the criteria under 'Suspend account when' are editable. Following these settings are 'Done' and 'Cancel' buttons.

  6. Edit the name or conditions of the rule as required.

  7. Press Done. The amended rule is shown in the list.

  8. Repeat for any other rules you want to edit.

  9. Press Save changes to put your changes live.

Delete a suspend rule

  1. Go to Management > Connections.

    Main Connections page. In the left sidebar, under the subheading 'Local authentication', are a 'Create' button and a list of existing local connections.

  2. Under Local authentication in the left sidebar, select the required local connection.

  3. Go to the Permissions tab.

  4. In the list of rules, hover over the rule you want to edit. Edit and Remove buttons appear.

    Permissions tab of a connection called 'ADFS connection', showing a list of existing rules. Next to a rule called 'Test' are buttons labeled 'Edit' and 'Remove'.

  5. Press Remove. You are asked to confirm this action before the rule is deleted.

    Dialog pop-up titled 'Delete permission set rule'. A message reads, 'Please confirm you wish to delete permission set rule 'Test'.' There are buttons marked 'Delete' and 'Cancel'.

  6. Press Delete to confirm.

  7. Press Save changes to put your changes live.

Multi-valued attributes and negative conditions

If your local source has a multi-valued attribute, such as the memberOf attribute from Microsoft Entra ID (aka Azure or Active Directory), be aware of how suspend rules treat this attribute. A multi-valued attribute contains multiple discrete value elements. Suspend rules check each of these values separately, so if even one of them matches the specified condition, then the rule will pass. This can happen even when you might not obviously expect it.

Let’s look back at one of our earlier examples. Assuming memberOf contains multiple discrete values, then we can write a rule that checks for one or more of those values:

Suspend account when any of these conditions are met:

memberOf contains visitor

memberOf contains walk-in

Regardless of what other data the attribute contains, or what order the values are listed, as long as memberOf includes either ‘visitor’ or ‘walk-in’ then the rule will pass.

So far, that is probably what you would expect. However, the rule is doing something subtly different from what its wording might suggest. The rule doesn’t look at memberOf as a whole, to determine if ‘visitor’ or ‘walk-in’ appear somewhere in the list of values. Instead, it tests each value individually, checking if ‘visitor’ contains the required value, if ‘walk-in’ contains the required value, and so on. Each does contain a required value, so the rule passes.

In an example like the former, which tests a positive condition, the outcome is the same as checking the values of the attribute as a whole. Things become more complicated, though, if you want to create a negative condition such as does not contain. This condition will be true if any of the individual values meet it, even if other values indicate a contrary outcome.

For example, say we want to suspend users whose memberOf attribute does not include the value ‘student’. We create the following rule:

Suspend account when all of these conditions are met:

memberOf does not contain student

Let’s assume that there are two users, A and B. A has a memberOf attribute with the values ‘student, alumnus’. B has the memberOf attribute ‘visitor'.

Which users are suspended by the rule? We might expect that B is suspended while A gets to keep her account. Actually, both are suspended. Why? The rule checks against each of the discrete values in memberOf individually. User A meets the specified condition since, although she has the value ‘student’, she also has ‘alumnus’, which matches the criterion of does not contain student. Because a match for any value triggers the rule, A is culled along with B.

As you see, this behaviour can be counter-intuitive, although it does have potential uses. Take care when creating negative conditions with multi-valued attributes and check that your rule will not produce undesirable results.

Multi-valued attributes are different from multi-line attributes, in which a single value element is split into several parts.