# Discovery

_(c) AMWA 2019, CC Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0)_

NMOS Discovery makes use of the DNS Service Discovery protocol as described in [RFC 6763][RFC-6763]. DNS-SD specifies a
mechanism for the use of Unicast or Multicast DNS for the purpose of identifying one or more endpoints on a network
associated with a named service.

## DNS-SD Advertisement

The preferred method of Authorization API advertisement is via unicast DNS-SD advertisement of the type
\_nmos-auth.\_tcp. Authorization APIs SHOULD additionally be capable of producing an mDNS advertisement. This MAY be
disabled via a user-configurable method.

The Authorization Server MUST advertise itself with the following service type:

```
_nmos-auth._tcp
```

The hostname and port of the Authorization Server MUST be identified via the DNS-SD advertisement, with the full HTTPS
path then being resolved as identified in section 3 of [RFC 8414][RFC-8414]. A DNS A record MUST be provided to allow
the hostname to be resolved.

Multiple DNS-SD advertisements for the same API are permitted where the API is exposed via multiple ports and/or
protocols.

Clients and Resource Servers MUST support discovering the Authorization Server through use of unicast DNS-SD service
discovery, as described in [RFC 6763][RFC-6763].

### Authorization Server Metadata Endpoint

The Server Metadata endpoint is described in [RFC 8414][RFC-8414]. The ".well-known" URI suffix of "oauth-
authorization-server" MUST be used to identify the Authorization Server metadata endpoint. The value of the
Authorization Server metadata URL should take the form:

```
<api_proto>://<hostname>:<port>/.well-known/oauth-authorization-server[/<api_selector>]
```

Where `/.well-known/oauth-authorization-server` forms the "well-known URI string" and the optional `api_selector`
is based on the "path component of the issuer identifier", with the latter enabling support for multiple
issuers per host. Placeholders are described in [DNS-SD TXT Records](#dns-sd-txt-records) below.

### Use with TLS

*   Clients and Resource Servers MUST verify the TLS certificate of the Authorization Server. The hostname and domain
used MUST match one of the Subject Alternate Names provided in the TLS certificate of the Authorization Server. The
hostname and domain used SHOULD be the Common Name on the TLS certificate of the Authorization Server.
*   Clients MUST verify the entire chain of trust of the Authorization Server TLS certificate, back to a trusted root
certificate. This ensures that the authorization server is trusted.
*   Clients and Resource Servers MUST provide a mechanism for installing root CA certificates used for verifying the
TLS certificate of Authorization Servers.
*   Clients and Resource Servers MUST NOT interact with Authorization Servers if the TLS certificate of the
Authorization Server cannot be validated.

### DNS-SD TXT Records

#### api_proto

The DNS-SD advertisement MUST be accompanied by a TXT record of name `api_proto` with a value of either `http` or
`https` dependent on the protocol in use by the Authorization API web server. In production environments this MUST be
set to `https`.

#### api_ver

The DNS-SD advertisement MUST be accompanied by a TXT record of name `api_ver`. The value of this TXT record is a
comma-separated list of API versions supported by the server. For example: `v1.0,v1.1,v2.0`. There should be no
whitespace between commas, and versions should be listed in ascending order.

This TXT record MUST NOT be used to form the URL of the authorization server endpoints, with the `api_selector` record
used instead to locate the server metadata endpoint. The `api_ver` TXT record should instead be used solely as an
indicator to the client of what versions of this specification the authorization service supports.

#### pri

The DNS-SD advertisement MUST include a TXT record with key `pri` and an integer value. Servers MAY additionally
present a matching priority via the DNS-SD SRV record `priority` and `weight` as defined in [RFC 2782][RFC-2782]. The
TXT record should be used in favour of the SRV priority and weight where these values differ, in order to overcome
issues in the Bonjour and Avahi implementations. Values 0 to 99 correspond to an active NMOS Authorization API
(zero being the highest priority). Values 100+ are reserved for development work to avoid colliding with a live system.

#### api_selector

The DNS-SD advertisement MAY include a TXT record of name `api_selector`. The value of this TXT record is a string
corresponding to the "path component of the issuer identifier", as described in Section 3.1 of [RFC 8414][RFC-8414],
with the initial '/' and any trailing '/' omitted.
It is used as described in [Authorization Server Metadata Endpoint](#authorization-server-metadata-endpoint) above.
If this record is omitted or is equal to an empty string, the ".well-known" URI does not include a path component.

For example, when the issuer identifier has the path `/x-nmos/auth/v1.0/`, the `api_selector` TXT record value MUST
be equal to `x-nmos/auth/v1.0`.

## Implementation Notes

It is expected that timeouts specified by DNS-SD and DNS specifications will be abided by when maintaining a cache,
however clients may wish to temporarily mark particular advertisements as invalid where they have timed out or produced
HTTP 5xx errors during API interactions. In the case of multicast DNS the re-query mechanism should be used, and is
particularly important for servers which cannot unregister their mDNS announcements before going offline.

Due to the caching mechanisms present within mDNS implementations, if a service disappears from the network without
cleanly removing its mDNS announcement, it will still be present in the caches of browsing systems until the defined
expiry time (120 seconds to 75 minutes dependent on record type). When mDNS advertised data is found to be invalid (for
example by performing an HTTP request to an advertised service API and seeing a time-out), the procedure defined in
[RFC 6762][RFC-6762] section 10.2 should be followed. Additionally, RFC 6762 section 10.5 may be used to pre-empt these
failures.


[RFC-2782]: https://tools.ietf.org/html/rfc2782 "A DNS RR for specifying the location of services (DNS SRV)"

[RFC-6762]: https://tools.ietf.org/html/rfc6762 "Multicast DNS"

[RFC-6763]: https://tools.ietf.org/html/rfc6763 "DNS-Based Service Discovery"

[RFC-8414]: https://tools.ietf.org/html/rfc8414 "OAuth 2.0 Authorization Server Metadata"
