Add IS-10 support

[lo-simon]

NMOS Authorization

This is based on the OAuth 2.0 recommendation, it is used for protecting the NMOS APIs, which allows NMOS Node and Registry to give limited access to the third-party application. Third-party applications including Broadcast Controller, which queries Registry via the AMWA IS-04 for the NMOS Nodes information and issues the IS-05 connection on Nodes. NMOS Nodes also act as the third party for the Registry to perform the AMWA IS-04 node registration.

General idea of how it works

A client such as Broadcast Controller provides credentials to the Authorization Server. The required access token(s) is then granted to the Controller for accessing the protected APIs on the Resource(s) Server, such as the NMOS Node. The Resource Server will verify the access token for the level of the access right. If all goes well, the protected API is accessible.

The access token is time-limited, it must be refreshed before it expired. It is recommended to attempt a refresh at least 15 seconds before the expiry or the half-life of the access token.

To speed up the token validation process, the Resource(s) Server periodically fetches the Authorization Server's public keys, typically once every hour. The public keys allow the Resource(s) Server to perform local token validation without bombarding the Authorization Server on every API access validation.

A similar idea is also applied to how NMOS Node performs node registration, Registry obtains the public keys from the Authorization Server, and the Node obtains the registration access token from the Authorization Server. Once the Node obtains the token, it embeds it into the registration request for node registration, and registry heartbeat.

Authorization Server Metadata

Clients, such as NMOS Broadcast Controller, Registry and Node must obtain the location of the Authorization API endpoints via the DNS-SD Authorization Server discovery. The Authorization Server has a well-known endpoint for returning the server metadata information. Details are shown in the client registration sequence diagram.

Client Registration

Clients must be registered to the Authorization Server before using the OAuth 2.0 protocol. Once the client is registered, the Authorization Server will provide it with a client_id for all both public and confidential clients and a client_secret for the confidential client. It is, however, important that the public client which is using the Authorization Code Flow must register one or more redirect URLs for security purposes, which allows Authorization Server to ensure any authorization request is genuine and only the valid redirect URLs are used for returning the authorization code. While using Client Credentials Flow, Private Key JWT can be used for client authentication for extra security.

See the client registration sequence diagram below on how an NMOS Node is registered to the Authorization Server.

Access Token

There are a number of ways to request the access token, it is based on the type of authorization grant. The grant type depends on the location and the nature of the client involved in obtaining the access token. A number of grant types are defined in OAuth 2.0. NMOS is focused on using the following types, the Authorization Code Grant, the Client Credentials Grant and the Device Code Grant(for the future).

Authorization Code Grant

This is the most recommended type, it should be used if the client has a web browser, such as the Broadcast Controller. An Authorization code is returned by the Authorization Server via the client's redirect URI. The client can then exchange it for a time-limited access token, and renew it with the refresh token.

For public clients, there is a potential security risk with an attacker hijacking the Authorization code. To prevent that Proof Key for Code Exchange (PKCE) is used to further secure the Authorization Code Flow.

In step 1, create a high entropy cryptographic random string, code_verifier.
In step 2, convert the code_verifier to code_challenge with the following logic:

code_challenge=BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

In step 3, includes the code_challege and the hashing method used to generate the code_challenge in the authorization code request.
In step 4, send the code_verifier and the authorization code for exchanging the token. The Authorization Server uses the code_verifier to recreate the matching code_challenge to verify the client.

Client Credentials Grant

This type of authorization is used by clients to obtain the access token without user authorization, such as a hardware NMOS Node which has no web browser supported. To gain extra security the Private Key JWT is used by the NMOS Node as a form of client authentication by the Authorization Server before handing out the token.

Authorization Server Public Keys

The public keys are used by the Resource(s) Server for validating the access token before giving access right to the protected APIs. The client must periodically poll the Authorization Server's public keys, typically once every hour. In the event, that the Authorization Server is no longer available, the last fetched public keys will be kept in use until the Authorization Server connection is restored.

The token validation is done by re-generating the matching token signature by signing the token header and the token payload.

Authorization behaviour

nmos/authorization_behaviour.cpp

The purpose of the authorization behaviour thread is to:

• discovery of the Authorization Server
• fetch Authorization Server metadata for Authorization Server endpoints and supported features
• Authorization client registration
• fetch Authorization Server public keys
• fetch Bearer token for accessing protected endpoints

Note: The Device Code Authorization Grant is not shown in the diagram

The state machine implemented by the nmos::experimental::authorization_behaviour_thread is shown below:

Missing public keys to validate the access token

nmos/authorization_handlers.cpp
nmos/authorization_behaviour.cpp

If no matching public key is available to validate the incoming access token. The validation handler will trigger the authorization token issuer thread to fetch and cache the public keys from this token's issue, which will then be possible to validate any token issued by this issuer.

The state machine implemented by the nmos::experimental::validate_authorization_handler and the nmos::experimental::authorization_token_issuer_thread are shown below:

OAuth 2.0 Node Registration Example

Following is an overview of how an OAuth 2.0 NMOS Node registers to an OAuth 2.0 enabled NMOS Registry.

[jonathan-r-thorpe]

LGTM