Stream Access Control (Optional Feature)

Use the optional Stream Access Control section of the Streaming menu  to apply permanent (“default”) or scheduled access rules to your streams. Typically this is used for establishing a default geoblock (e.g., only listeners in a specific region or country can receive the stream) or for scheduling geoblocking (or "geofencing”) of a specified location to prevent listeners in that area from receiving the stream for a specific period of time, such as during a sports event where there is a broadcast blackout in effect for the area around the live event. It can also block the stream based on user agent, IP address, and other factors.

You can set rules to DENY or ALLOW access to the stream. Generally, they work together to create “deny” and “allow” zones. For example:

• If a U.S. national publisher wants to restrict the broadcast of an election debate to listeners in New York State, it would create a scheduled deny rule that denies everyone from receiving the stream, then add an allow rule that specifies “New York State.” By explicitly naming that location, the allow rule supersedes the deny rule.
• If a broadcast blackout for a football game in Boston requires that listeners in Boston be denied access to the broadcast but everyone else can hear it, the publisher needs to explicitly state a “deny” rule for Boston.

Basic Principles Of Stream Access Control (SAC)

When a listener hits “Play” on their device, the device’s app/browser/operating system requests the stream from the Triton platform through a link to Triton player services. Player Service can determine if a user can access the stream or not, based on different rules as configured in the Triton Stream Access Control (SAC) interface.

When a device requests a stream, it does so by declaring several parameters along with its request. Among them are the requesting IP, device information (“user agent”), and in the case of players embedded in web pages, the referring web page URL from which the player is making the request. It may also have GPS coordinate if the user allowed location sharing in the mobile application.  

SAC rules use one or more of these pieces of information to allow or deny access to the stream.

Rules and Rule Sets

A rule set is simply a collection of rules that are saved together. Technically, a rule set that contains only one rule is still a "rule set." For simplicity, the descriptions below usually refer to "rules" but unless otherwise indicated they refer to the full saved rule set (regardless of how many rules are in the rule set).

Where Are Rules Applied?

Rules can be applied at any level in the Triton Console's Navigator pane:

• Top Broadcaster level
  • Sub-broadcaster level
    • Market level
      • Station level
        • Mount level

Rules applied to a particular level are also in effect for all sub-levels (“chlidren”) that do not have rules of their own. Rules applied at any level will override rules from higher levels.

Each level can have multiple rules active at the same time. In the example below, Rule Set #1 applies to every level except for Station 2 (which has its own rule set). Mount 3 follows Rule Set #2 (it doesn’t have a rule set active at its level, so it inherits the rule from its station) but Mount 4 follows its own rule (Rule Set #3).

A broadcaster has the following structure:

• Top Broadcaster (Rule Set #1)
  • Market 1
    • Station 1
      • Mount 1
      • Mount 2
    • Station 2 (Rule Set #2)
      • Mount 3
      • Mount 4 (Rule  Set #3)
  • Market 2
    • Station 3
      • Mount 5
      • Mount 6
    • Station 4
      • Mount 7
      • Mount 8

Rule #1 is present from the Top Broadcaster level on down.

Rule #2 is applied on Station 2. 

Rule #3 is applied to Mount 4.

What Happens When A Stream Is Blocked?

Restricting access to streams will inevitably mean that certain listeners will be refused access to the content they wanted to hear. By default, when a rule set determines that the listener is to be denied access, the system returns an error code to the device. Some players using the Triton SDK (such as Triton’s own player and apps) will display a message letting the user know the content is unavailable at this time. Players unable to consume this error code will simply fail to connect and will default to how they were programmed to handle such events.

To help improve the listener experience, Alternate Content can be configured to either redirect the listener to another station, or deliver an audio file for the device to play instead of the live stream. See the sections below on Alternate Content for details.

A Note Regarding IP Geolocation

IP addresses are used in determining the listener’s geolocation. Triton uses a database to map IPs with physical locations around the world. This database is updated often, and in general the location matching works fairly well. However, there can be cases where the geolocation of the IP is different from the actual physical location.

IP geolocation errors tend to be more common with mobile listening, as telecommunication companies regularly lease IPs from other providers when they run out of their own IPs. In such cases the system will think that a listener is in a different location than they really are, since the IP is now attached to that other location. For example, if a listener is at a NASCAR event in Austin Texas, and their cellular provider is overwhelmed by the large number of subscribers at the event, the listener might be assigned an IP that is leased from another telecommunication provider. As a result, the listener is flagged as being elsewhere, such as New York, because the leased IP is mapped to New York by the second provider.

Default (Permanent) Rules vs. Scheduled Rules

SAC rules can be applied to any of the elements found in the Navigator on the left. Each element can be assigned Default rules (which we refer to as "permanent" in the rest of this section) as well as Scheduled rules.

• Default rules are permanent rules that are always active. In some cases, an active scheduled rule can override a permanent rule. Typically, you set up your permanent rules once and let them run.
• Scheduled rules are configured to run on a timed schedule and will sometimes override permanent rules while they are active. Typically, you create and edit scheduled rules on an on-going basis.  Scheduled rules overridepermanent rules when:
  • The scheduled rule is of the same rule type as the permanent rule. E.g., a scheduled rule that denies a user agent(rule type) will override a permanent rule that denies or allows a user agent. See examples, below:
    • Example 1: If you have a permanent rule that denies "bots" (* bot * User Agent rule type), and you create a scheduled rule that includes either allowing or denying any device type (User Agent rule type), the scheduled rule overrides the permanent rule while the scheduled rule is active. This means that while the scheduled rule is active, "bots" will not be denied unless that is specified in the scheduled rule that overrides the permanent rule.
    • Example 2: If you have a permanent rule that allows access from USA (Geographic Region rule type), and allows access from desktop devices (User Agent rule type), then you create a scheduled rule set that allows users from New York DMA (Geographic Region rule type), the scheduled geographic rule will override the permanent geographic rule while the scheduled rule is active, but will have no effect on the user agent rule. This means that while the scheduled rule is active, ONLY listeners from New York DMA will be allowed access because the permanent Geographic Region rule has been overridden by the scheduled Geographic Region rule. The scheduled rule does not override the user agent rule. So the only listeners that will have access during the scheduled rule are desktop device users in New York DMA.
    • Example 3: If you have a permanent rule that allows access from USA (Geographic Region rule type), and you create a scheduled rule set that denies mobile users (User Agent rule type) but with no Geographic Region rule type specified, the scheduled rule will not override the permanent rule while the scheduled rule is active. This means that while the scheduled rule is active, non-mobile listeners from USA will be allowed access as usual, and mobile users everywhere will be denied access.

Common Rule Components

All stream access rules have a Default Action, a Type, a Description, an Action, and a Rank. These components work the same way for both Default and Scheduled rules.

Default Action

The Default Action setting is the start of the SAC logic. By default this setting is always set to ALLOW, which allows all traffic. If the setting is set to DENY, all traffic is blocked, unless other rules state differently.

Remember that Enable This Ruleset must be selected in order for the rule set to be in effect.

Rule Types

The type of rule determines a criteria against which the system applies logic to determine if a listener is allowed or denied access to the content. As stated earlier, rules can be applied against various bits of information given to Triton when the listener’s device requests the content from the Triton Network.

Geographic Region

Using the device’s IP, Triton maps the listener to a physical geographic location. A rule can be set to a particular Country, Region, and City, or to the mobile app GPS coordinate (if provided).

DMA

In the United States it is typical to group listeners according to their Designated Market Area (DMA). Rules can be applied using these geographic area groups, which affect listeners in the United States only. DMAs are set by selecting the DMA number from the drop down list.

Coordinate (Radius)

A rule can be set to an area around a geographical element (Country, Region, City). The rule can be set in Kilometres or Miles around the selected point.

Host

The host rule type can be used to block or allow individual IP addresses. We recommend you consult your company's IT professionals to get details on what to enter in this interface.

Referrer

The referrer rule type can be used when there is a need to restrict access from browser-based players. The rule uses the referring web page URL from which the browser player is making the request.

You must include the URL prefix (https:// or http://). E.g.: https://mywebsiteURL.com

User Agent

The user agent rule type can be used to restrict access for specific players and/or devices.  The field is an open text field. The system will search the entire user agent string sent by the device for the text entered in the field. Wildcards (specifically “ * ”) can be used to broaden the matching of the text string. The search is not case-sensitive.

For example, if a device (in this case a Samsung Galaxy S8 mobile phone) sends the following code as a user agent string:
 
Mozilla/5.0 (Linux; Android 7.0; SM-G892A Build/NRD90M; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/60.0.3112.107 Mobile Safari/537.36
 
...and the rule has “ *android* ” entered in the text field, the rule will be correctly applied to this user agent because there is a match. Be careful of typographical errors!

User agent lists are always evolving as new devices are brought to market. Current lists can easily be found with via Internet searches.

Action

This is the action the server will take if the rule is found to be TRUE. Actions can be set to either ALLOW or DENY access to the stream. By default, if no rules are set, the servers will ALLOW all traffic.

Creating Default (Permanent) Rules

Permanent rules are configured in the top panel of the SAC window. These are the "permanent" rules that are always in effect unless they are overridden by a scheduled rule. (See Default (Permanent) Rules vs. Scheduled Rules.)

To create a permanent rule:

1. In the top panel of the SAC window, click Create Default Rules.
2. Set the Default Action (Allow or Deny) for the permanent rule.
3. Set the Required Rule Groups, if applicable. (Most of the time you will leave these unselected. For more information, see Rank and Rule Groups.)
4. Select the desired rule type using the radio buttons.
5. Enter the desired parameters for the selected rule type.
6. Click Add.
   At this point you can add any additional rule types and parameters that you want to use as part of this rule set.
7. Once all rules are added, click Save and Enable.*

* Alternatively, click Save to save the rule but not enable it. You can come back later and select Enable This Ruleset when you want the rule to take effect. (You will need to click Save to save the change.)

Alternate Content (Permanent Rules)

You have the option of configuring alternate content for when a connection is refused because the rules result in a DENY action. When alternate content is configured, the system can redirect the listener to one of two sources: another stream or an audio file.

To configure alternate content:

1. While creating or editing a Default rule, click Configure Alternate Content.
2. In the Configure Alternate Content window, click Enabled.
3. Select the Type (either MEDIAL_URL for a file or MOUNT if you want to redirect to another stream).
4. In the Value (Mount name or URL, field, enter the exact URL where the audio file is located, or the exact name of the mount (e.g., MYSTATIONAAC) as listed in the Navigation panel. If entering a URL, be sure to include the transfer protocol (e.g., HTTPS://) and enter the full URL to the file, e.g.:
   https://thisiswherethefilelives.com/subfolder/myalternateaudiofile.mp3.
5. Click OK in the Configure Alternate Content window.
6. Save the rule.

The alternate content configuration is saved, and is displayed in the Default Rules panel. Note that there is no validation check to ensure the entered URL is valid. If you enter an invalid mount name, an error message appears.

Creating Scheduled Rules

Scheduled rules are configured in the bottom panel of the SAC window. These are the rules that operate on a timed schedule, either as a one-time event or as a recurring event. Scheduled rules can sometimes override permanent rules that would normally apply to the station or mount. (See Default (Permanent) Rules vs. Scheduled Rules.)

Scheduled rules can only be created at the station or mount levels. As with permanent rules, adding a scheduled rule to a station affects all the mounts under that station.

Only one scheduled rule set can be active at any time for any given station or mount. This means you cannot schedule overlapping rulesets. The system will not allow you to save a scheduled rule set if it overlaps with another scheduled rule for the same station or mount. For example, It is not possible to schedule a rule that blocks mobile listening during the first week of January and also a rule that blocks all traffic on January 2nd for the same station. To achieve this, the first rule would have to be split in two so as to not overlap with the January 2nd rule.

The process for creating a scheduled rule is very similar to creating a permanent rule.

To create a scheduled rule:

1. In the bottom panel of the SAC window, click Add Scheduled Rule.
2. In the Create New Schedule window's Rulestab:
   1. Start by giving the rule a name.
      Tip: Use a short but easily-understood name. Remember that you and possibly other people need to be able to identify the rule by name when there are several or even many rules in place.
   2. Set the Default Action (Allow or Deny) for the scheduled rule.
   3. Enter a description for the rule.
      Tip: Be brief but clear in your description, as things can get confusing when many rules are present, and consider that other people might need to understand your rule's intention.
   4. Edit the Required Rule Groups, if applicable. For scheduled rules, Referrer, User Agent, and Location/DMA/Coordinate are selected by default; this is a useful setting for many rules but might need to be adjusted for others. (For more information, see Rank and Rule Groups.)
   5. Select the desired rule type using the radio buttons. (Geographic, DMA, etc.)
   6. Enter the desired parameters for the selected rule type.
   7. Click Add.
   8. At this point you can add any additional rule types and parameters that you want to use as part of this rule set.
   9. Once all rules are added, click Next.
3. On the Scheduletab:
   1. Enter the start date and start time for when the rule is in effect.
   2. Enter the end date and end time for when the rule is in effect.
      Enter an end date even if you also intend to enter an end point in a recurring rule.
      Times are in reference to the station's timezone.
   3. Choose whether the rule is a one time event or a recurring event.
      If you select Recurring, you can then select the interval (daily/weekly/monthly, etc.) and when the recurrence will end.
   4. Click Next.
4. On the Mountstab:
   1. If you want the rule to apply to any new mounts that are added before the rule expires, select that option. De-select it if you do not want any new mounts to be subject to the rule.
   2. De-select any existing station mount that you do NOT want the scheduled rule to be applied to.
   3. Click Next.
5. On the Submit tab:
   1. Click Save to save the rule but not yet enable it. Or click Save and Enable to save it and enable it immediately.

Alternate Content (Scheduled Rules)

Alternate content for scheduled rules works the same way as for permanent rules,

To enable alternate content on a scheduled rule:

1. Click the arrow to the right of the saved rule to open the available options.
2. In the list of available options, click Alternate Content.
3. In the Configure Alternate Content window, click Enabled.
4. Select the Type (either MEDIAL_URL for a file or MOUNT if you want to redirect to another stream).
5. In the Value (Mount name or URL, field, enter the exact URL where the audio file is located, or the exact name of the mount (e.g., MYSTATIONAAC) as listed in the Navigation panel. If entering a URL, be sure to include the transfer protocol (e.g., HTTP:// or HTTPS://) and enter the full URL to the file, e.g.,  https://thisiswherethefilelives.com/subfolder/myalternateaudiofile.mp3.
6. Click OK in the Configure Alternate Content window.
7. Save the rule.

Copying a Scheduled Rule Set

To save time, scheduled rule sets can be copied to either the same station where they were created, or to another station.

To copy an existing scheduled ruleset:

1. Click the arrow to the right of the saved rule to open the available options.
2. In the list of available options, click Copy...
3. In the Copy Scheduled Ruleset window, enter the Start Date, Start Time, End Date and End Time you wish to use for the copied rule.
4. Use the Station drop down menu to select the station or mount you wish to have the copied ruleset applied to. Note that you can also type in the drop down to search for stations and mounts.
5. Click Copy.

Rank and Rule Groups

SAC rules use a priority system which gives each rule a rank. The lower the rank number, the higher its priority.  (Rank 1 being the first to be evaluated or highest priority).

Rules have a priority system that gives each rule a rank. The rank number range is 1-9999, with lower numbers having higher priority. The automatic rank assignment is usually in the range of 1000 to 3000.

Rank is automatically assigned to each rule, but you can edIt a rule's rank to give it a higher or lower priority. Simply click the existing rank to convert it to an editable field, then type in the new rank. Hit the Return key to set the new rank number, then save the rule.

A red triangle next to the rank score indicates the rank has changed but the change has not yet been saved.

How the System Uses Rank

The system evaluates lower-ranked rules first. However, you should be aware that this operates differently depending on whether or not Rule Groups are used.

Without Required Rule Groups  (Simpler option)

The rules are evaluated one after the other until there is a match. Upon the first match, it will trigger the action configured by the rule (ALLOW or DENY) and will not look at any further rule. If there is no match, it will trigger the default action. It’s better to have different ranks for all rules, to avoid uncertainties in cases of rules with equal rank.

In the example below, any listeners from Canada would be allowed, no matter the platform, and any listeners on Windows would be allowed, no matter the country.

By default, for a scheduled rule set, the system will have checked Referrer, User Agent and Location/DMA/Coordinates. For many use cases, however, these should be unchecked to keep things simple, unless your rule logic requires them.

With Required Rule Groups

When Required Rule Groups are selected, each selected rule group must return ALLOW to grant access. For example:

Upon a sports game scheduled rule coming into effect, Desktop users within a specific Geography shall be allowed access to the stream, while any other users shall be denied access.  

If we return to the above example, but with the user agent and location required groups checked, we get a different result. Now, if a listener is in Canada, but not on Windows, they do not get the stream. Only Canadian listeners on Windows get the stream.

Note that within a group, rank is still respected, so the overall result still depend on the ranking logic. In the next example, a Canadian listener using Chrome on Windows would be denied, since the Chrome rule has a higher priority than the Windows rule:

Vice-versa, if the Windows ALLOW rule has a higher priority than the Chrome DENY rule, the stream will be granted to the Canadian listener on Windows.