Security API

Introduction

Opencast is distributing encoded media to download and streaming servers to make that media available to end users. At the same time, that media needs to be protected such that - once provided a link to the download and/or streaming representations - only authorized users are able to consume it.

This is achieved by handing signed URLs to end users which are validated by the distribution servers and become invalid after a given period of time (usually 1 hour, depending on the server configuration).

As a consequence, users of the External API who are presenting URLs to distributed media for playback will need to make sure that those urls are signed, otherwise the distribution servers will refuse to deliver the content and respond with a 401 NOT AUTHORIZED status.

Best practices

The use of signed URLs requires a set of best practices to be followed when clients interact with the External API, most notably in the area of performance and caching.

Performance

When consuming URLs that need to be signed before handing them to the user, client implementors may be inclinded to use the sign=true parameter for the events queries to request all URLs to be already signed. On one hand, this saves the client implementation from having to explicitly sign those URLs that users are visiting for playback. On the other hand, signing URLs introduces an overhead to performance for the pre-signing of all urls that are sent to the client, so in these cases it will be important to make sure not to transfer large lists and require presigning.

Caching

One obvious caveat when using pre-signed URLs is the use of cached responses. As described above, signed URLs have a maxmimum life time and therefore need to be refreshed on a regular basis so that a user's request to play back a recording won't be rejected by the distribution servers.

Secure access by source IP

The signing facility of the security API provides the ability to sign URLs and restrict that URL to a given IP address.

Even though this greatly increases security in sense that signed URLs can only be accessed from that device, it is important to note that in many network setups, source IP addresses of network packets will undergo network address translation (NAT) with NAT replacing the original source address from private networks with a single public address, thereby diminishing the security impact of adding the source IP address immensely.

URL Signing

POST /api/security/sign

Returns a signed URL that can be played back for the indicated period of time, while access is optionally restricted to the specified IP address.

Form Parameters Required Type Description
url yes string The URL to be signed
valid-until no datetime The date and time until when the signed URL is valid
valid-source no string The IP address from which the url can be accessed

Response

200 (OK): A JSON object containing the signed URL or an error message is returned:

Field Type Description
url string The signed URL
valid-until datetime The date and time until when the signed URL is valid

In case of an error:

Field Type Description
error string An error message describing the error

401 (NOT AUTHORIZED): The caller is not authorized to have the link signed.

Example

{
  "valid-until": "2018-03-19T13:08:39Z",
  "url":"http://localhost?policy=eyJTdGF0ZW1lbnQiOnsiQ29uZGl0aW9uIjp7IkRhdGVMZXNzVGhhbiI6MTUyMTQ2NDkxOTI4NH0sIlJlc291cmNlIjoiaHR0cDpcL1wvbG9jYWxob3N0In19&keyId=demoKeyOne&signature=717dd8f958a15c1cdb7e88a61417a07bb6a1e6238d9293805cc0893f798a07e8"
}

Error example:

{
  "error": "Given URL cannot be signed"
}