Closed lo-simon closed 7 months ago
We need to work out where "Fatal error: No IPv4/IPv6 address(es) for "nmos-api.local" available" comes from... I wonder if this early error causes the test suite to assume testssl.sh is not available? Obviously later on at least nmos-api.local is working fine...
"Fatal error: No IPv4/IPv6 address(es) for "nmos-api.local" available"
Seems likely related to https://github.com/drwetter/testssl.sh/issues/1099
It's bizarre... both your Windows 2019 runners consistently show this in testoutput:
Fatal error: No IPv4/IPv6 address(es) for "nmos-api.local" available
Whereas on master, that doesn't happen on either Windows 2019 runner. And on my PR #282, it only happens on the Windows 2022 runner, not the Windows 2019.
It seems repeatable in our respective branches.
How can this be?!?!
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, theAuthorization Code Grant
, theClient Credentials Grant
and theDevice 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 thecode_verifier
tocode_challenge
with the following logic:In step 3, includes the
code_challege
and the hashing method used to generate thecode_challenge
in the authorization code request. In step 4, send thecode_verifier
and theauthorization code
for exchanging the token. The Authorization Server uses thecode_verifier
to recreate the matchingcode_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
The purpose of the authorization behaviour thread is to:
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
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 thenmos::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 anOAuth 2.0
enabled NMOS Registry.