YouTube API v3 Rule Set Documentation
Table Of Contents YouTube API v3 ...... 1 Scope ...... 1 Disclaimer ...... 2 Overview ...... 2 Prerequisites ...... 2 Installation ...... 2 Import Error Templates ...... 2 Import the Rule Set ...... 2 Configuration ...... 3 Extract Meta Data ...... 3 Get Title/Description ...... 3 Get Uploader/Channel ...... 4 Get Thumbnails ...... 4 Filters Based on Meta Data ...... 4 Filter By Category ...... 4 Filter By Keywords...... 4 Filter By Uploader/Channel ...... 4 Filter By Video ID ...... 5 Filter By DLP Acceptable Use ...... 5 Fail-Open Error Handler ...... 5 Troubleshooting ...... 5
Scope This document is a short whitepaper which comes along with a rule set for McAfee Web Gateway. The document describes how to import the associated rule set into a default McAfee Web Gateway policy.
Disclaimer This rule set along with all of its associated files and documents is provided on an as-is basis. McAfee will not take any responsibilities for problems, outages or any other issues resulting from using this rule set, or any of the files associated.
Please be careful when importing the rule set into your existing policy. Make sure you understood what the rule set is supposed to do and verified it does not interfere with any other rules that currently exist within your configuration.
Many values used within the rules are example values and will most likely not fit your environment. Always make sure that you have changed examples to real-life values.
Overview YouTube offers a publically accessible API which allows access to a YouTube videos Meta information such as uploader, category or similar. Recently Version 3 of the API has been released which might supersede previous implementations using the older API.
This rule set utilizes Version 3 to lookup Categories and Uploader/Channel names in order to provide some additional filter capabilities to MWG. It uses external list calls to poll the API servers and writes the results into custom HTTP headers which are usable from within the rule engine.
Prerequisites Compared to the previous API the API v3 requires a user to obtain an API key which is used to identify who is querying the API. Every API has a specific quota which defined how many requests against the API can be done.
More details can be found at https://developers.google.com/youtube/v3/getting-started.
Please note that McAfee and/or the product McAfee Web Gateway don’t have any control about the API itself (in regards to availability) and/or the quota. In case you exceed the quota for your API key it may be required to talk to YouTube/Google to increase the available quota for your key.
Additionally the API now heavily utilizes JSON, so a version of McAfee Web that has JSON Support Gateway is required.
Installation
Import Error Templates Before you import the rule set itself it is required to import the error templates.
1.) Find the “Template Editor”, for example by editing any of the existing Block Actions 2.) Click the “Import” button 3.) Point to the ZIP file which came with the rule set and contains the templates 4.) Resolve any conflict 5.) Close the template editor
Import the Rule Set 1.) Access the McAfee Web Gateway Web Interface (UI)
2
2.) Open the “Policy” tab 3.) Find an appropriate location for the rule set, for example between URL Filter and AV rule sets 4.) Select “Add -> Top Level Rule Set -> Import Rule Set from Library” 5.) Click the “Import from file” button in the lower left corner of the new window 6.) Select the rule set from the file you have download 7.) Solve all conflicts by “refer to existing” objects 8.) Done!
Configuration Because the YouTube API requires a personalized API key now the rule set will not work but immediately exit unless you provide MWG with your API key:
In the parent rule set “Youtube API v3” you will have to put your API key into a user-defined property. If the key is not provided, the server will deny all API requests. This will result into problems when looking up the videos Meta data.
Extract Meta Data There are several Meta objects MWG will extract. The rules responsible for the extraction are located in the parent rule set “Get Meta Information Via Youtube API”. They will be described below.
Get Category McAfee Web Gateway will try to extract the category ID from the API response. In API version 3 the category is no longer provided as a string but as a numerical identifier (which optionally can be translated into a string, see below).
Translate Category ID In order to translate the category ID (numerical value) into a readable value (for example “Autos & Vehicles”) McAfee Web Gateway can initiate another call to the API. This setting has a cache setting of 24 hours as categories usually do not change on a regular interval.
If you do not want to utilize categorization in your policy you can disable both rule sets. If you are happy with category IDs only you can disable the “Translate Category ID” rule set. This will save some of your available quota, however it will make category handling more inconvenient.
Get Title/Description This rule set is responsible for grabbing the videos title and description. Both can be used to search for specific keywords you would like to filter or to mark up the block template with the videos title and/or description, which can be helpful for users.
If you do not want to filter based on title or description you can disable this rule set.
3
Get Uploader/Channel In case you want to restrict access to specific uploaders/channels you can add the allowed and/or blocked uploaders to a list. McAfee Web Gateway will fetch a videos uploader via the API call and make it available for filtering.
If you do not want to filter based on Uploader/Channel you can disable this rule set.
Get Thumbnails This rule set can most likely be disabled. The default block templates contain a thumbnail of the video, which is grabbed here.
Filters Based on Meta Data The rule set comes with several examples which use the extracted Meta data in order to enforce a specific policy.
Filter By Category This will allow you to set up a “Allow only these categories” or a “Allow all but these categories” policy. You will have to fill the category ID or category name (if translation is enabled, see above) into the associated lists.
If you watch a video in the browser you can find the category name in the video description:
You can find the correct category ID by accessing the list of ID <-> category name mappings by making a browser call to the API: https://www.googleapis.com/youtube/v3/videoCategories?part=snippet®ionCode=us
If you are unable to see the result because there is no quote left please add your API key to the URL by adding “&key=
Filter By Keywords This rule set will allow you to add a very simple keyword filter based on wildcard found in a videos title or description. Please note that the list requires wildcard expressions, so in case you want to search for the word “naked” in the title or description, please type “*naked*” into the list. You can also apply regular expressions.
Filter By Uploader/Channel This rule set will allow you to set up a “Allow only these channels” or a “Allow all but these channels” policy, which will allow you to (for example) only allow your users to see the companies YouTube videos or to block specific YouTube channels which are time consuming or contain inappropriate materials.
You can find a videos uploader/channel name below a video if you watch it in the browser:
4
Filter By Video ID This is a very specific filter that will allow you to only allow or block specific videos. You can grab the video ID from the browsers address bar:
Filter By DLP Acceptable Use This filter will apply DLP rules to title/description of a video and can search for inappropriate words. More information about the DLP rules can be found in the official product documentation.
Fail-Open Error Handler Calling an external list may cause problems, for example when the remote server is not available or not responding fast enough. In such a case McAfee Web Gateway usually presents a block page and denies access for the user.
Therefore the rule set contains an additional Error Handler which is set as default while McAfee Web Gateway polls the API servers for a response and is set back to the Default error handler once this operation succeeds.
This error handler is configured to write a log line and fail-open, so that access to YouTube is granted rather than blocked when an API lookup does not work. In case this behaviour is not desired please turn off the “Get Meta Information Via Youtube API -> Set Fail-Open Error Handler” rule.
In case you are using a non-default error handler you may need to look more closely at the error handler configuration to make sure your policies uses the correct error handler. If unsure simply turn off the “Get Meta Information Via Youtube API -> Set Fail-Open Error Handler” and “Get Meta Information Via Youtube API -> Set Default Error Handler” rules.
Troubleshooting Please note this rule set is not officially supported. For any help, further comments or feature requests please use the McAfee Community at: https://community.mcafee.com/community/business/email_web/webgateway
5