Networked Media Open Specifications

AMWA BCP-003-02: Authorization in NMOS Systems

Index↑

Please see the IS-10 Specification at NMOS Authorization for further details regarding implementing authorization with the NMOS suite of APIs.

Use of Normative Language

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Scope

The AMWA IS-10 Specification describes how to implement a general OAuth 2.0 authorization system, in line with current best practices. This document outlines additional requirements placed upon Resource Servers and Clients which implement or interact with specific NMOS Interface Specifications.

Authorization Grant Constraints

As identified in IS-10, Authorization Clients are expected to use the Authorization Code OAuth grant type unless they are a confidential client which needs to peform machine to machine operations with no user interaction. Client interactions which MAY use the Client Credentials grant are detailed below.

The above list will be added to in the future if additional use cases for client credentials are identified.

Alternative uses of the Client Credentials grant MUST be arranged on a deployment specific basis and MUST NOT form the default mode of operation.

Authorization Servers SHOULD be configured to enforce the scopes which are permitted to use Client Credentials during the dynamic client registration or token exchange process where supported.

NMOS APIs

IS-04 - Discovery and Registration

Node Manifest Href Authorization

Nodes which support IS-04 and IS-05 and operate in authorized mode SHOULD use the IS-05 transportfile paths matching their Sender IDs when publishing IS-04 manifest_href Sender attributes.

Control systems which identify an IS-05 path in the manifest_href (identified via the presence of the base path /x-nmos/connection) MUST determine whether an authorization token is required to access this file via the IS-04 Device controls authorization attribute. Where the Node does not use an IS-05 path for the manifest_href the control system SHOULD assume that authorization is not required for this path unless this requirement and relevant claims have been established out of band.

Registry Client Authorization

When registering resources with an instance of an IS-04 Registry, the Registry MUST capture the Client ID of the client performing the initial ‘node’ resource type registration. The Client ID can be found within the client_id claim of the valid JWT access token used in the HTTP request. Where the client_id is not specified the same identifier can be found in the azp claim.

Subsequent requests to register, modify or delete resources which belong to Node ID(s) which were registered by this client MUST be validated to ensure that the Client ID used matches the client_id or azp claim in the JWT access token used in the HTTP request making the modifications. This is to ensure that clients do not, maliciously or incorrectly, alter resources belonging to other Nodes. Unsuccessful validation of a matching Client ID MUST result in the Resource server rejecting the request with a ‘403’ HTTP response code and a WWW-Authenticate header using the error value of insufficient_scope as specified in RFC 6750. All IS-04 resources can be related back to a single Node ID by following the IS-04 Referential Integrity guide.

Registry WebSocket Authorization

When creating an IS-04 Registry WebSocket subscription, whether by using a POST to the /subscriptions resource or by using an Upgrade HTTP header, the JSON Web Token used MUST be validated to ensure it contains a write claim matching the subscriptions path, for example:

"x-nmos-query": {
  "write": ["subscriptions"],
  "read": ["*"]
}

When connecting to an IS-04 Registry WebSocket subscription, the JSON Web Token used MUST be validated to ensure it contains a read claim matching all data which may be returned according to the subscription’s resource_path configuration. Note that the resource_path includes a leading slash where token claims do not. The ws_href path MUST NOT be validated against the token claims.

For example, access to the following subscription would require token claims as follows:

{
  "max_update_rate_ms": 100,
  "resource_path": "/receivers",
  "params": {},
  "persist": false,
  "secure": false,
  "ws_href": "wss://172.29.80.52:8870/ws/?uid=6a52dbd5-a737-4c4e-823f-909ade8f8bf4",
  "id": "6a52dbd5-a737-4c4e-823f-909ade8f8bf4"
}
"x-nmos-query": {
  "read": ["receivers/*"]
}

IS-05 - Device Connection Management

Transport File Authorization

Where an IS-05 Sender exposes a transport file via the /single/senders/{sender_id}/transportfile path, this MUST NOT use HTTP redirects when the API is operating in authorized mode. The API MUST return an HTTP 200 code as opposed to a 3xx code when the request is successful.

Requests to the transport file path MUST be checked for a valid authorization token as specified in IS-10, including checks that the requested path is included in the private claims. An example of claims from such a token is shown below.

"x-nmos-connection": {
  "read": ["single/senders/*/transportfile"]
}

IS-07 - Event and Tally

WebSocket Authorization

When connecting to an IS-07 WebSocket, the JSON Web Token used MUST be validated to ensure it contains a read claim matching all Source data which may be returned by the WebSocket. These Source paths match those used by the IS-07 Events API.

For example, access to the IS-07 Source IDs ‘9f463872-9621-4939-aa3a-dc3c82d8578b’ and ‘7f87027c-ebb4-4640-b878-14952915249a’ only would require token claims as follows.

"x-nmos-events": {
  "read": ["sources/9f463872-9621-4939-aa3a-dc3c82d8578b",
           "sources/7f87027c-ebb4-4640-b878-14952915249a"]
}

Alternatively, access to all IS-07 Source IDs may be requested with a token claim as follows.

"x-nmos-events": {
  "read": ["sources/*"]
}

Specific token claims are not required in order to send IS-07 WebSocket commands such as ‘subscription’ and ‘health’, provided the token covers the ‘events’ scope and includes claims for any Sources which are being requested.

Index↑