Documentation

Table of Content

 

Introduction

Thanks for choosing DNN Dynamic Roles by weweave! DNN Dynamic Roles allows you to define criteria that defines whether or not a user should be member of a role or not and DNN Dynamic Roles automatically takes care of dynamically adding or removing the user to/from the role. Because those “dynamic” roles plug 100% into DNN’s default role system, they can be used just as any other (static) rule in DNN.

If nothing else is stated, this documentation refers to the latest available version of DNN Dynamic Roles.

 

Requirements

In order to use DNN Dynamic Roles, make sure your environments meets the following requirements:

 

Installation

Please follow these steps to set up DNN Dynamic Roles:

  1. Download DNN Dynamic Roles from the download page.
  2. Log in to your DNN installation as host admin and select “Settings > Extensions” (DNN 9) or navigate to “Host > Extensions” (DNN 7 or 8).
  3. Select “Install Extension” (DNN 9) or “Install Extension Wizard” (DNN 7 or 8) and follow the process.
  4. After a successful installation you should see one new menu items: “Dynamic Roles” under “Admin” where the portal-specific configuration can be performed.
  5. Navigate to “Admin > Dynamic Roles”, select Host Settings and enter your license key in the popup.

 

Upgrading

Please follow these steps to upgrade your existing DNN Dynamic Roles module installation:

  1. Download the latest version of DNN Dynamic Roles for your DNN version from the download page.
  2. Make sure that your license key is still valid before performing the upgrade.
  3. Log in to your DNN installation and select “Settings > Extensions” (DNN 9) or go to “Host > Extensions” (DNN 7 or 8).
  4. Select “Install Extension” (DNN 9) or “Install Extension Wizard” (DNN 7 or 8) and follow the process.

 

Role Configuration

The actual role configuration of DNN Dynamic Role is performed portal-specific under “Admin > Dynamic Roles”. When editing or adding a role, you can set the following properties:

  • Role name: A unique name for your role
  • Role group: DNN role group to assign the role to
  • Rule: A logical rule that defines whether or not a user should assigned to the role described by a XML syntax (see XML Rule Definition Syntax)
  • Enabled: Check if this role is enabled, i.e. user should automatically added or removed from the role
  • Track anonymous: Check if the role’s rule should be evaluated before the user has logged in and add resp. remove the user after he has logged in
  • Eval trigger: Select “Request” to evaluate the role’s rule on every request or “Login” to evaluate the role’s rule after a successful login
  • Update method: Defined whether to only add, remove or sync (add and remove) user to/from the role
  • Cache time: Defines the time in minutes for which the rule’s result is cache, i.e. the rule is not evaluated again (0 disables caching)

XML Rule Definition Syntax

The criteria whether or not a user should be assigned to a dynamic role are expressed as XML. This section lists the available XML tags and gives some samples.

Logical Operators

Multiple rules can be combined by the logical operators AND and OR, and single rules can be negated by using the logical NOT operator.

The AND operator combines multiple rules by a logical AND. Thus, all rules enclosed in the AND tag must evaluate to true.

<and>
    <rule1 />
    <rule2 />
</and>

The OR operator combines multiple rules by a logical OR. Thus, at least one rule enclosed in the OR tag must evaluate to true.

<or>
    <rule1 />
    <rule2 />
</or>

The NOT operator negates a single rule enclosed in the OR tag. This, if the rule returns true, it is negated to false and vice versa.

<not>
    <rule1 />
</not>

Please note that every ruleset must be enclosed in a logical outer tag. Thus, every ruleset must start with and AND, OR, or NOT operator – even if there is only one rule in your ruleset.

The logical operators can be combined with each other by nesting the corresponding tags.

<and>
    <rule1 />
    <rule2 />
    <or>
        <rule3 />
        <rule4 />
        <not>
            <rule5 />
        </not>
    </or>
</and>

The pseudo-rules <true /> and <false /> can be used for testing purposes. They always evaluate to true or false.

Role Membership

Dynamic roles can be built on top of other roles. These roles can be static (so administered manually by a site operator) or they can be dynamic themselves. Please note that this rule always evaluates to false for anonymous requests.

<and>
    <member role="goodCustomer" />
    <member role="originGermany" />
</and>

In this example, the user must be in both roles “goodCustomer” and “originGermany” in order for the ruleset to evaluate to true.

  • role (required): The role to be checked for.

Cookies

You can check if a certain cookie is present, and (optionally) if it has a certain value.

<cookie name="first-visit" pattern="^2014-.*$" />

In this example, the user must have a cookie with the name “first-visit” present and the cookies content has to start with the string “2014-“.

  • name (required): The name of the cookie.
  • pattern (optional): The value of the cookie to match. This is a regular expression. If this parameter is not specified, the existence of the cookie is sufficient for the rule to evaluate to true.
  • patternIgnoreCase (optional): Set to “false” to ignore case. Default is “true”.

Referer

Check the referer/referrer. This is the url of the page the user visited before coming to your site. Please note that you cannot rely on the referer: In many cases, browsers do not set this http request header.

<referer pattern="^http(s)?://(www.)?weweave.net/.*$" />

In this example, the user must come from weweave.net – either via http or via https, and either with or without “www.”.

  • pattern (required): A regular expression to check the referer against (case insensitive).

Browser

Check the browser (interpreted user agent) a user uses. Please note that user agents can be faked, so you should not rely on the correctness.

<or>
    <browser type="internetexplorer" minVersion="6" maxVersion="9" />
    <browser type="firefox" maxVersion="20.1" />
</or>

In this example, the user must use Internet Explorer 6-9, or Firefox <= 20.1.

  • type (required): One of the following values: internetexplorer, firefox, chrome, opera, safari.
  • minVersion (optional): The minimum version (major and minor, inclusive).
  • maxVersion (optional): The maximum version (major and minor, inclusive).

User Agent

Check the raw user agent reported by the client. Please note that user agents can be faked, so you should not rely on the correctness.

<userAgent pattern=".*lynx.*" />

In this example, the user must use a version of Lynx.

  • pattern (required): A regular expression matched against the HTTP request header “User-Agent” (case insensitive).

Request Parameter

Check if a certain request parameter (GET or POST) is present and, if desired, it has a certain value.

<requestParam name="query" pattern="^error.*$" method="get" />

In this example, the HTTP GET parameter “query” must be present and its value must start with the string “error”.

  • name (required): The name of the request parameter.
  • pattern (optional): A regular expression of the required parameter value.
  • patternIgnoreCase (optional): Set to “false” to ignore case. Default is “true”.
  • method (optional): The request method employed. One of the following values: get, post. If this parameter is not supplied, the parameter is searched in both GET and POST section.

Date

Check if the current date is within a certain range. The server-side timestamp is used for this check.

<date min="2014-12-01" max="2014-12-24" />

In this example, the current date must be between 12/01/2014 and 12/24/2014.

  • min (required): The minimum date (inclusive). Format: yyyy-MM-dd
  • max (required): The maximum date (inclusive). Format: yyyy-MM-dd

Time

Check if the current time is within a certain range. The server-side timestamp is used for this check.

<time min="09:00:00" max="15:30:00" />

In this example, the current date must be between 9:00 AM and 3:30 PM.

  • min (required): The minimum time (inclusive) in 24h format. Format: HH:mm:ss
  • max (required): The maximum time (inclusive) in 24h format. Format: HH:mm:ss

Date and Time

Check if the current timestamp is within a certain range. The server-side timestamp is used for this check.

<dateTime min="2014-12-01 15:00:00" max="2014-12-31 09:00:00" />

In this example, the current date must be between 12/01/2014 3:30 PM and 12/31/2014 9:00 AM.

  • min (required): The minimum timestamp (inclusive) in 24h format. Format: yyyy-MM-dd HH:mm:ss
  • max (required): The maximum timestamp (inclusive) in 24h format. Format: yyyy-MM-dd HH:mm:ss

SQL Query

Run an SQL Query and evaluate the result. The rule evaluates to true if the value of the first column in the first row is “1”, and to false otherwise.

<sql query="SELECT COUNT(*) FROM sales WHERE customer_id = @[email protected] LIMIT 1" />

In this example, there must be a row in the “sales” table where the customer’s ID matches the current user’s ID.

  • query (required): The query to execute. You can use the placeholder @[email protected] which will be replaced with the current user’s ID, and @[email protected] which will be replaced with the current portal’s ID. Please note @[email protected] is always null for anonymous requests. Both parameters are passed as int.

Geo Location

Check the user’s IP address against MaxMind‘s geo ip database. You need an account at MaxMind in order to use this rule.

<geoMaxMindCountry userId="1" licenseKey="abc" service="city" country="US" />

In this example, the user’s IP address must be located in the US.

  • userId (required): MaxMind User ID.
  • licenseKey (required): MaxMind License Key.
  • service (required): MaxMind’s endpoint to be used. One of the following values: city, country, insights
  • country (required): Two-letter ISO Country Code (i.e. “US” or “DE”).

Random >= 01.03.00

Evaluates randomly to true or false (i.e. useful for A/B testing).

<random ratio="0.5" />

In this example, the rule returns true in 50% of all requests, and false in the other 50%.

  • ratio (required): The ratio between 0.0 and 1.0 at which the rule evaluates to true.

Administrator User >= 01.04.00

Checks is the current user is an administrator.

<administratorUser />

Super User >= 01.04.00

Checks is the current user is a super user.

<superUser />

Unauthenticated User >= 01.04.00

Checks is the current user is an unauthenticated user.

<unauthenticatedUser />

Registered User >= 01.04.00

Checks is the current user is a registered user.

<registeredUser />

User’s email address >= 01.04.00

Checks if the user’s email address matches a specific pattern.

<email pattern=".*@gmail\.com" />
  • pattern (required): A regular expression of the required email address pattern.

User’s first name >= 01.04.00

Checks if the user’s first name matches a specific pattern.

<firstName pattern="A.*" />
  • pattern (required): A regular expression of the required first name.

User’s last name >= 01.04.00

Checks if the user’s last name matches a specific pattern.

<lastName pattern="A.*" />
  • pattern (required): A regular expression of the required last name.

User’s preferred locale >= 01.04.00

Checks if the user’s preferred locale matches a specific pattern.

<preferredLocale pattern="de_DE" />
  • pattern (required): A regular expression of the required locale.

User’s profile property >= 02.02.00

Checks if a user’s profile property matches a specific pattern.

<profileProperty pattern="A.*" property="profileProperty" />
  • property (required): Profile property (case sensitive) the regular expression should match against.
  • pattern (required): A regular expression of the required profile property.
  • patternIgnoreCase (optional): Set to “false” to ignore case. Default is “true”.

User’s title >= 02.02.00

Checks if the user’s title matches a specific pattern.

<title pattern="A.*" />
  • pattern (required): A regular expression of the required title.
  • patternIgnoreCase (optional): Set to “false” to ignore case. Default is “true”.

Troubleshooting

Enabling debug logging

Add the following lines right before the closing “</log4net>” to the file DotNetNuke.log4net.config which you’ll find in your website’s root directory.

<logger name="weweave.DnnDynamicRoles">
    <level value="Debug" />
</logger>

Debug output will be written into the log files in this directory: Portals\_default\Logs

Uninstalling

You can easily remove DNN Dynamic Roles from your DNN installation by uninstalling the extension.