Configuration of Stream Security

To get an introduction to stream security before deploying, please read the overview at:

It is important to note that if stream security is enabled, all resources will be signed and protected, even ones that do not have any access restrictions defined in their access control lists. Accessing resources with unsigned URLs will not be possible.

On a high level, to use Stream security, these steps are required:

URL Signing Service Installation

There are three modules that are built by default and need to be present on each Opencast node in order to initiate URL signing:

If these modules are present, the URL signing service will be available, to which the URL signing providers can then register themselves.

Minimal Configuration Example

This is a minimal configuration example which requires valid tokens for all static file downloads:

etc/org.opencastproject.security.urlsigning.filter.UrlSigningFilter.cfg:

enabled=true
url.regex.files=.*localhost:8080/static/.*

etc/org.opencastproject.security.urlsigning.provider.impl.GenericUrlSigningProvider.cfg

key.default.secret=THISISNOSECUREKEY
key.default.url=http://localhost:8080/static/

etc/org.opencastproject.security.urlsigning.verifier.impl.UrlSigningVerifierImpl.cfg:

key.default=THISISNOSECUREKEY

Configuration of Signing Providers

The GenericUrlSigningProvider that comes with Opencast has its own configuration file:

etc/org.opencastproject.security.urlsigning.provider.impl.GenericUrlSigningProvider.cfg

All signing providers follow the same configuration structure and support multiple configuration blocks, providing the settings for separate distributions (i.e. download or streaming servers, services or paths).

Each signing key configuration consists of the following attributes:

A typical configuration looks like this:

key.demoKeyOne.secret=6EDB5EDDCF994B7432C371D7C274F
key.demoKeyOne.url=http://download.opencast.org/engage

key.demoKeyTwo.secret=6EDB5EDDCF994B7432C371D7C274F
key.demoKeyTwo.url=http://download.opencast.org/custom
key.demoKeyTwo.organization=mh_default_org

It is also possible to use one key for multiple URL prefixes:

key.demoKeyThree.secret=6EDB5EDDCF994B7432C371D7C274F
key.demoKeyThree.url.http=http://download.opencast.org/custom
key.demoKeyThree.url.https=https://download.opencast.org/custom
key.demoKeyThree.url.streaming=http://streaming.opencast.org/custom
key.demoKeyThree.organization=mh_default_org

A Java regular expression can be defined to identify URLs to be excluded from URL signing. Any URL that matches this anchored regex will not be signed.

exclude.url.pattern=.*/.*/unprotected/.*/.*

Configuration of URL Signing Timeout Values

Once stream security is turned on by configuring the signing providers, multiple different services within Opencast will be signing URLs, and while some services are signing on behalf of administrative users working in the Opencast administrative user interface, others are signing URLs in order to grant access to learners playing back video content i.e. the functionality we have been talking about up to now.

This section explains how to best configure URLs to ensure that they expire at the right time. This might be required if the default valid times do not seem secure enough or is more secure than needed.

Signing for external access

The lifetime of the signed URLs can be configured by setting a custom value for the property url.signing.expires.seconds that defines the validity in seconds. The default valid time is 7200 seconds (2 hours). The signed URLs can also be configured to restrict access to the user’s IP address by setting the property url.signing.use.client.ip to true. By default this is disabled.

Overview of configuration files for services that are able to automatically sign URLs on behalf of users:

URLs That Are Signed Configuration File Name
Video player content org.opencastproject.security.urlsigning.SigningMediaPackageSerializer.cfg
Admin UI links org.opencastproject.adminui.endpoint.OsgiEventEndpoint.cfg

The URLs will be signed by the first signing provider that will accept the URL’s path based upon the signing provider’s configuration. This makes it flexible to support many different scenarios. For example, we could configure the signing provider to have one key for any URL that begins with one scheme, such as http, which would cover all of the URLs to be signed with a single key. Or it could be configured so that each different scheme and hostname pair would have a different keys protecting each host’s URLs separately etc. Having the timing configurations separate from the key configuration allows the different types of URLs to be signed differently depending on the needs of the users without needing to configure this timing for all of the different keys.

Signing for Opencast-internal access

Signing of requests for internal use is performed by a core component called TrustedHttpClientImpl, which is used to establish all internal HTTP connections. More specifically, the HTTP client needs access to internal storage areas such as the working file repository as well as to distributed artifacts on the downloads and streaming servers, all of which are protected by verification components.

The default expiration time for signed internal requests is 60 seconds. This can be changed by setting a value in seconds for the org.opencastproject.security.internal.url.signing.duration property in the custom.properties configuration file. Since those URLs are signed right before the request is made, the valid time of 60 seconds should be sufficiently long.

Configuration of Verification Components

The verification components ensure that only valid and correctly signed URLs are accessible at any given time. URLs which are not properly signed or have expired will be rejected.

Out of the box, Opencast provides an internal verification component:

The following section is dedicated to the installation and configuration of the Opencast internal UrlSigningFilter. The stream security architecture allows the implementation for URL verification for third-party applications which are not covered in this documentation.

Configuration of Opencast verification filter

The Servlet filter providing the verification of requests to Opencast internal resources is implemented in the bundles:

The filter uses a set of regular expressions to determine which requests to an Opencast instance need to be verified.

Installation

The bundles are built by default and as soon as they are running in Opencast, the filter is active, and ready to be enabled.

Configuration

Two things need to be configured for the Opencast verification filter:

The configuration is located at:

etc/org.opencastproject.security.urlsigning.verifier.impl.UrlSigningVerifierImpl.cfg

Example:

key.demoKeyOne=6EDB5EDDCF994B7432C371D7C274F

key.demoKeyTwo=C843C21ECF59F2B38872A1BCAA774

The entries in this file need to have the same values for the signing providers configuration.

The second step is to configure the filter defining the endpoints to be protected. The configuration file is located at:

etc/org.opencastproject.security.urlsigning.filter.UrlSigningFilter.cfg

The configuration defaults to a set of regular expressions which match all of the endpoints that serve files, and avoid protecting endpoints that only serve data. Therefore, the remaining step is enabling the filter by setting the property enabled to true and determining whether strict or non-strict verification of the resource is required.

Note that strict verification of resources means the entire URL will be considered when comparing the incoming request for a resource against the policy, including the scheme (http, https, etc.), hostname and port. If turned off, only the path to the resource will be considered. So if the resource http://httpdserver:8080/the/full/path/video.mp4 is requested, only the /the/full/path/video.mp4 part of the URL will be checked against the policy’s path. As mentioned before, this is useful when using a load balancer so that the requested host name does not have to match the actual hostname or if a video player is rewriting requests, e.g. by inserting the port number.

Example:

enabled=true

strict=true

url.regex.collection=.*files\/collection\/.*
url.regex.mediapackage=.*files\/mediapackage\/.*
url.regex.staticfiles=(?\=(.*staticfiles.*))(?=^(?!.*staticfiles.*url|.*docs.*).*$)(.*)
url.regex.archive=.*archive\/archive\/mediapackage\/.*\/.*\/.*
url.regex.static=.*static.*

Configuration of Wowza URL Signing

To configure Wowza URL Signing, you should use the file configuration org.opencastproject.security.urlsigning.provider.impl.WowzaUrlSigningProvider.cfg.

You can find three properties to configure:

# key.wowzatoken.secret=myTokenPrefix@mySharedSecret
# key.wowzatoken.url=http://localhost:8080
# key.wowzatoken.organization=mh_default_org

Each property has the form: key.keyId.propertyName

key.wowzatoken.organization is optional. By deafult is *, that means any organization.

key.wowzatoken.url is mandatory. describes the url prefix that urls must have.

key.wowzatoken.secret=myTokenPrefix@mySharedSecret is mandatory. It is a pair separated by @. First value, myTokenPrefix, means defines the prefix that all parameters of signed urls will have. Second value, mySharedSecret, defines a secret value, to secure urls.

After configuring the Opencast server, the steps to configure enable stream security in Wowza are:

  1. Open your Wowza server webpage (Normally http://<wowza-server>:8088/enginemanager) , log in and enter to your desired VOD application
  2. In the menu, select Playback-Security and click in edit
  3. Select Protect all protocols using hash (SecureToken version 2)
  4. Shared Secret write the mySharedSecret set in the first step
  5. Hash-Algorithm: SHA-256
  6. Hash Query Parameter Prefix write the myTokenPrefix set in step one
  7. Save changes and restart the application

Testing

Once all components of Stream Security are installed and properly configured, it is important to verify that the system is working as expected. It is especially important to try to access resources that should not be accessible.

The following explains how to test if Stream Security has been correctly configured.

Step 1: Creating Signed URLs with Signing Endpoint

The signing service provides a REST endpoint, which allows for the signing of arbitrary URLs. For manual use it is recommended to visit the endpoint’s documentation page at http://localhost:8080/signing/docs.

Is the URL accepted?

Check if the URL to be signed is accepted by the signing service (or by one of its signing providers respectively) by using the /signing/accepts endpoint. If that is not the case, the configuration of the signing providers should be checked again to ensure that at least one signing provider is responsible for the URL in question.

If the service is fully operational, the response code will be 200 OK and the response body either true (accepted) or false (refused).

Step 2: Signing the URL

On the same documentation page URLs can be signed using the /signing/sign endpoint, and the access policy may be specified in that form as well. With this, several scenarios can be tested. Examples are:

Step 3: Verifying the URL

The signed URLs can then be passed to the appropriate testing tool (web browser, cURL, player, …) to test the functionality of the verification component(s). The following table is the return codes associated with different rejection conditions:

Case Return Code
If any of the query string parameters are missing or are the wrong case / spelt incorrectly Bad Request (400)
If any of the required policy variables are missing Bad Request (400)
No encryption key that matches the KeyID known by the plugin Bad Request (400)
The Policy and Signature don’t match in any way Forbidden (403)
If client IP is specified and doesn’t match Forbidden (403)
The current time has passed the DateGreaterThan, the time the URL expires Gone (410)
The current time is before the DateLessThan, the time the URL becomes available Gone (410)

The components that verify a URL is signed will run before a request is checked to be valid, so if a non-existent URL is signed for example, the above conditions will need to be fixed before a missing (404) response code will be returned.

Step 4: Inspect policy

The generated policy which is added to the signed URLs can be inspected. It needs to be decoded from Base64 and the result must be a JSON document that contains exactly the values which have been passed during signing.

Decoding this Base64 encoded policy

eyJTdGF0ZW1lbnQiOnsiUmVzb3VyY2UiOiJodHRwOlwvXC9vcGVuY2FzdC5vcmdcL2VuZ2FnZVwvcmVzb3VyY2UubXA0IiwiQ29uZGl0aW9uIjp7IkRh
dGVMZXNzVGhhbiI6MTQyNTE3MDc3NzAwMCwiRGF0ZUdyZWF0ZXJUaGFuIjoxNDI1MDg0Mzc5MDAwLCJJcEFkZHJlc3MiOiIxMC4wLjAuMSJ9fX0

…would result in this JSON document (policy):

{
  "Statement":{
    "Resource":"http:\/\/opencast.org\/engage\/resource.mp4",
    "Condition":{
      "DateLessThan":1425170777000,
      "DateGreaterThan":1425084379000,
      "IpAddress":"10.0.0.1"
    }
  }
}

Inspecting and modifying the policy is useful for advanced testing, such as:

Further information

For an overview of Stream Security:

For further developer information, please have a look at the stream security section in the developer guide.