Mobotix 2023-R1 HUB APIGateway User manual

Administrator manual

MOBOTIX HUB API Gateway 2023 R1

Contents

Copyright 4

Overview 5

Introduction 5

What's new? 5

MOBOTIX HUB VMS 2023 R1 5

MOBOTIX HUB VMS 2022 R3 5

MOBOTIX HUB VMS 2022 R2 5

Limitations 5

Intended audience 6

API Gateway features 6

Authentication and authorization 6

RESTful APIs 6

WebRTC 6

Requirements and considerations 8

Considerations 8

For development, set up separate development system 8

Use HTTPS 8

Requirements 8

Server certificates and host names 8

MOBOTIX HUB users 8

WebRTC 9

Cross-Origin Resource Sharing CORS 9

No WebRTC connection through a symmetric NAT firewall 9

WebRTC connection on a local network uses mDNS 9

API Gateway support for mDNS 9

WebRTC connections across routers in a local network 9

Installation 11

Installation overview 11

Install the API Gateway 11

Install the API Gateway using the MOBOTIX HUB VMS product installer 11

Install the API Gateway using the API Gateway installer 11

2 / 33

Contents

Verify that the API Gateway is operational 12

Configuration 19

API Gateway configuration files 19

Editing configuration files 19

appsettings.json and appsettings.Production.json 19

Reverse proxy 21

Cross-Origin Resource Sharing (CORS) 23

WebRTC 25

STUN server address 25

Logging 26

Log levels 26

Log layout, log targets, etc 27

Troubleshooting 30

CORS errors 30

CORS error symptoms 30

Cause 30

Remedy 30

Cause 30

Remedy 31

No WebRTC connection 31

WebRTC connection through a symmetric NAT firewall 31

Remedy 31

WebRTC connection on a local network uses mDNS 31

Remedy 31

API Gateway doesn't answer requests 32

Symptoms 32

Cause 32

Remedy 32

3 / 33

Copyright

MOBOTIX AG • Kaiserstrasse • D-67722 Langmeil • Tel.: +49 6302 9816 0 • [email protected] • www.mobotix.com

MOBOTIX is a trademark of MOBOTIX AG registered in the European Union, the U.S.A., and in other countries. Subject

to change without notice. MOBOTIX do not assume any liability for technical or editorial errors or omissions

4 / 33

Overview

Introduction

The MOBOTIX HUB VMS is planned to include RESTful APIs and streaming protocols that expose the functionality

currently available through native .NET libraries and various proprietary protocols.

The API Gateway is installed on-premise and is intended to serve as a front-end and common entry point for RESTful

API and streaming services on all the current VMS server components (management server, event server, recording

servers, log server, etc). An API Gateway can be installed on the same host as the management server or separately,

and more than one can be installed (each on their own host).

What's new?

MOBOTIX HUB VMS 2023 R1

lSome changes to API Gateway configuration files.

lWebRTC is enabled by default and now supports mDNS.

MOBOTIX HUB VMS 2022 R3

lThe API Gateway can be configured to support Cross-Origin Resource Sharing (CORS).

lPre-release of WebRTC support.

MOBOTIX HUB VMS 2022 R2

lA number of syntax issues in the OpenAPI spec file have been fixed.

lMore complete coverage of the Configuration API.

lBreaking change: In some parts of the RESTful API, booleans were treated as strings, meaning that the values

when provided as input would have to be enclosed in quotation marks and also would be returned in this

form. As this is not in compliance with the JSON standard, and also not in accordance the OpenAPI spec file we

provide, we have decided to change it to use true/false without the quotation marks.

Limitations

lOnly the Configuration API is exposed as a RESTful API through the API Gateway.

lWebRTC cannot create a connection through a symmetric NAT firewall without using a TURN (Traversal Using

Relays around NAT) server. Currently, the API Gateway does not support using a TURN server.

lTo upgrade from the 2021 R2 pre-release of the API Gateway to later releases, you'll have to uninstall the 2021

R2 pre-release before upgrading.

5 / 33

Overview

Intended audience

This document is primarily aimed at system integrators and IT administrators. You are assumed to be somewhat

familiar with MOBOTIX HUB VMS products.

API Gateway features

The MOBOTIX HUB VMS offers a number of APIs to support integrations. The full functionality is currently available

through a plug-in environment, through native .NET libraries, and through various SOAP and native protocols. These

APIs are used internally by MOBOTIX HUB VMS, and a large number of integrations have been developed using these

APIs. But they are not practical for integrations in a cloud environment:

lThe SOAP-based protocols relies on Windows Communication Framework (WCF) which is part of .NET

Framework, making it difficult to implement non-Windows integrations.

lMedia data streaming uses a proprietary protocol.

lTo use the protocols, your integration must keep track of a number of service endpoints.

The API Gateway simplifies this by providing a single entry point for all services.

Authentication and authorization

The API Gateway relies on an OpenID Connect and OAuth 2.0 Identity Provider (IDP) for authentication and

authorization.

To use the API Gateway, a client first authenticates and requests an access token from the Identity Provider. The

client receives a bearer token that grants privileges to access services and to perform operations, as determined by

the user's roles.

The client now uses the bearer token in the authorization header in subsequent requests. The client renews the

bearer token before it expires by posting a new access token request with the same credentials.

User credentials, bearer tokens, and other sensitive data are transmitted in cleartext if you do

not set up certificates and use HTTPS.

RESTful APIs

The API Gateway acts as broker, routing requests and responses between external clients and the various

downstream MOBOTIX HUB VMS services.

The RESTful API is implemented in part by each specific VMS server component, and the API Gateway can simply pass-

through these requests and responses, while for other requests, the API Gateway will convert requests and responses

as appropriate.

WebRTC

WebRTC is a peer-to-peer real-time communication framework, for example for video media data, based on open

protocols (RTP, RTCP, and SCTP). WebRTC is attractive for cloud-based services because:

6 / 33

Overview

lmost modern web browsers support WebRTC, eliminating the need for installing plug-ins,

lin many cases, media traffic can be routed directly between the peers, reducing the need for intermediary

servers.

The API Gateway supports:

la WebRTC signaling server that offers a simple RESTful API for establishing WebRTC connections,

lstreaming live H.264 encoded video from a camera installed on a recording server through the WebRTC

connection.

WebRTC cannot create a connection through a symmetric NAT firewall without using a TURN (Traversal Using Relays

around NAT) server. Currently, the API Gateway does not support using a TURN server.

7 / 33

Requirements and considerations

Considerations

For development, set up separate development system

You are recommended to use a separate development system.

Use HTTPS

You should consider setting up a server certificate and using HTTPS. While the IDP, API Gateway, and the

Management Server all can work with either HTTP or HTTPS, production systems should be set up with server

certificates.

User credentials, bearer tokens, and other sensitive data are transmitted in cleartext if you do

not set up certificates and use HTTPS.

Requirements

Installation of the HUB API Gateway requires MOBOTIX HUB VMS 2022 R1 or later

Server certificates and host names

If you set up the management server with encryption, you must also set up all API Gateway instances that connect to

the management server with encryption. To enable this, the IIS on the host that you install the API Gateway on must

be set up with a server certificate.

The server hostname you specify during installation of the API Gateway is used to connect the API Gateway to the

identity provider service (IDP) and management server in the MOBOTIX HUB VMS, and should match a DNS name in

the management server certificate.

MOBOTIX HUB users

The API Gateway installer must be able to log in to the MOBOTIX HUB VMS during the installation. The Windows user

account that you used for installing the MOBOTIX HUB VMS has been added in the MOBOTIX HUB VMS to the

Administrators role. You can use the same Windows account when you install the API Gateway.

To authenticate and access the API Gateway, you need an MOBOTIX HUB Basic user account.

lYou can create an MOBOTIX HUB Basic user during installation of the MOBOTIX HUB VMS.

lAfter installation, you can use the MOBOTIX HUB Management Client to create MOBOTIX HUB Basic or

Windows users.

8 / 33

Requirements and considerations

WebRTC

Cross-Origin Resource Sharing CORS

Yoy need to enable CORS if the sample webpage is not served from the same origin host URL as the API Gateway, see

Cross-Origin Resource Sharing (CORS) on page 23.

No WebRTC connection through a symmetric NAT firewall

WebRTC cannot create a connection through a symmetric NAT firewall without using a TURN (Traversal Using Relays

around NAT) server. Currently, the API Gateway does not support using a TURN server.

Check with your system administrator if you are behind a symmetric NAT firewall, or run the test described here: Am I

behind a Symmetric NAT?1.

In that case, a WebRTC connection is possible only within the symmetric NAT firewall, that is, both your browser and

the API Gateway must be behind the firewall.

WebRTC connection on a local network uses mDNS

To prevent private IP addresses from leaking from a local network when running WebRTC applications, modern

browsers by default send mDNS (multicast DNS) addresses as ICE Candidates to the signaling server.

API Gateway support for mDNS

The signaling server running in the API Gateway supports resolving mDNS addresses when running on a Windows

version with native support for mDNS.

Native support for mDNS was introduced in Windows version 1809 (October 2018) or later, and is available in any

recently updated Windows Server 2019 or Windows 10 installations, and all Windows Server 2022 and Windows 11

installations.

WebRTC connections across routers in a local network

mDNS relies on multicast which by default will not pass through routers. This means that in enterprise environments,

mDNS will fail in many cases:

lmDNS over wired Ethernet works on the same local network segment, but in more complex network solution

(most enterprise environments), mDNS will fail.

lmDNS over WiFi will only work on simple network configurations (as for wired networks). In configurations

with WiFi extender or Mesh networks, mDNS will likely fail.

The signaling server running in the API Gateway supports a workaround for connections across routers on a local

network. The signaling server will attempt to get the client's local IP network address from X-Forwarded-For and

1https://webrtchacks.com/symmetric-nat/

9 / 33

Requirements and considerations

Remote_Addr headers in the HTTP request and use that to add an ICE Candidate with higher priority than the ICE

Candidate with the mDNS address. This will not work in all cases; on some networks, X-Forwarded-For is removed

and Remote_Addr will not contain the local IP address of client.

10 / 33

Installation

Installation overview

This installation overview describes the following tasks:

lInstalling the API Gateway, either during or after the initial installation of the MOBOTIX HUB VMS.

lVerifying that an API Gateway is operational.

Install the API Gateway

There are several ways to install an API Gateway:

lDuring installation of a either a Single computer or a Custom (distributed) MOBOTIX HUB VMS, using the

MOBOTIX HUB VMS product installer.

lAfter installation of a MOBOTIX HUB VMS, using the API Gateway installer downloaded from the management

server's Administrative Installation Page.

Install the API Gateway using the MOBOTIX HUB VMS product installer

The API Gateway is included by default in both Single computer and Custom installations.

The API Gateway will be installed on the same host as the management server and with the same server certificate if

you enable encryption.

Install the API Gateway using the API Gateway installer

The management server has a built-in public installation web page. From this web page, administrators and end-

users can download and install additional system components. For example, if you didn't initially install an API

Gateway, you can install it later.

1. From the computer where management server is installed, go to the management server's download web

page. In Windows' Start menu, select MOBOTIX > Administrative Installation Page and write down or copy

the address for later use when installing the system components on the other computers. The address is

typically http://[management server address]/installation/Admin/default-en-US.htm.

2. Log into the computer where you want to install the API Gateway.

3. Open the management server's download web page in a web browser.

4. Locate the API Gateway Installer section, and select All Languages to start downloading the installer. Save

the installer first, or run it directly from the web page.

5. Choose installation language.

6. Accept license terms.

7. Enter the management server address. Use HTTPS if the management server is configured to be secure.

11 / 33

Installation

8. Select the web site on the local IIS to use with the API Gateway, usually the Default Web Site.

9. If the management server is configured to be secure, you must select a server certificate for the API Gateway

host. If you are installing the API Gateway on the host of the management server, select the server certificate

you used when installing MOBOTIX HUB VMS.

10. Select the service account for the API Gateway, usually the Network Service account.

11. Select file location and product language.

12. Select Install.

Verify that the API Gateway is operational

Replace the hostname test-01.example.com, username seamrune, and password

Rad23Swops# in the following request samples.

In Windows Command Prompt (CMD), replace the line continuation character \ with ^.

12 / 33

Installation

1. Verify that you can get a list of well-known URIs from the API Gateway:

cURL

1 curl --insecure --request GET "https://test-01.example.com/api/.well-known/uris"

PowerShell

1$response = Invoke-RestMethod 'https://test-01.example.com/api/.well-known/uris' -

Method 'GET'

2$response | ConvertTo-Json

Response body

1 {

2 "ProductVersion": "22.1.5804.1",

3 "UnsecureManagementServer": "http://test-01.example.com/",

4 "SecureManagementServer": "https://test-01.example.com/",

5 "IdentityProvider": "https://test-01.example.com/IDP",

6 "ApiGateways": [

7 "https://test-01.example.com/API/"

8 ]

9 }

13 / 33

Installation

In case you had installed an API Gateway on another host, you could use the hostname

of that host.

14 / 33

Installation

2. Verify that you can authenticate and retrieve a bearer token from the built-in IDP.

cURL

1 curl --insecure --request POST "https://test-01.example.com/idp/connect/token" \

2 --header "Content-Type: application/x-www-form-urlencoded" \

3 --data-urlencode "grant_type=password" \

4 --data-urlencode "username=seamrune" \

5 --data-urlencode "password=Rad23Swops#" \

6 --data-urlencode "client_id=GrantValidatorClient"

PowerShell

1$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"

2$headers.Add("Content-Type", "application/x-www-form-urlencoded")

3$body = @{grant_type='password'

4 username='seamrune'

5 password='Rad23Swops#'

6 client_id='GrantValidatorClient'}

7$response = Invoke-RestMethod 'https://test-01.example.com/idp/connect/token' `

8 -Method 'POST' -Headers $headers -Body $body

9$response | ConvertTo-Json

15 / 33

Installation

Response body

1 {

2 "access_token": "eyJhbG . . . YTWPjg",

3 "expires_in": 3600,

4 "token_type": "Bearer",

5 "scope": "managementserver"

6 }

Copy the access_token value from the response body; you will use the value as the bearer token value in the

following request.

16 / 33

Installation

3. Verify that you can submit a request through the API Gateway.

Replace the hostname test-01.example.com and the bearer token value eyJhbG . . . YTWPjg in the

following request samples.

cURL

1 curl --insecure --request GET "https://test-01.example.com/api/rest/v1/sites" \

2 --header "Authorization: Bearer eyJhbG . . . YTWPjg"

PowerShell

1$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"

2$headers.Add("Authorization", "Bearer eyJhbG . . . YTWPjg")

3$response = Invoke-RestMethod 'https://test-01.example.com/api/rest/v1/sites' `

4 -Method 'GET' -Headers $headers

5$response | ConvertTo-Json

Response body

{

"array": [

{

"displayName": "TEST-01",

"id": "2d12465c-3485-4ca8-a9fb-86a79de1a82f",

17 / 33

Installation

"name": "TEST-01",

"description": "",

"lastModified": "2021-11-11T11:11:11.1111111Z",

"timeZone": "Central Europe Time",

"computerName": "TEST-01",

"domainName": "example.com",

"lastStatusHandshake": "2021-11-11T11:11:11.1111111Z",

"physicalMemory": 0,

"platform": "[Not Available]",

"processors": 0,

"serviceAccount": "S-1-5-20",

"synchronizationStatus": 0,

"masterSiteAddress": "",

"version": "21.2.0.1",

"relations": {

"self": {

"type": "sites",

"id": "2d12465c-3485-4ca8-a9fb-86a79de1a82f"

}

]

}

18 / 33

Configuration

API Gateway configuration files

API Gateway configuration files are located in the installation location, by default %ProgramFiles%\MOBOTIX\HUB

API Gateway\.

These configuration files are relevant for the API Gateway:

lappsettings.json: Reverse proxy (routing), CORS, WebRTC, log levels, etc.

lappsettings.Production.json: Overrides the configuration settings in appsettings.json.

lnlog.config: Log layout, log targets, etc.

Editing configuration files

Use a validating editor to edit configuration files. Most popular code editors support JSON and

XML syntax validation, either by default or through extensions.

appsettings.json and appsettings.Production.json

Do not edit appsettings.json manually. This file is created by the product installer and

maintained by the Server Configurator.

If you need to override a configuration setting in appsettings.json, create appsettings.Production.json and

add configuration overrides here. appsettings.Production.json will not be removed or changed by product

updates.

To override configuration settings in appsettings.json, copy the complete top level property from

appsettings.json to appsettings.Production.json and remove the nested properties that you don't want to

change.

For example, to change the management server host address but no other ReverseProxy settings, include this in

appsettings.Production.json:

1 {

2 "ReverseProxy": {

3 "Clusters": {

19 / 33

Configuration

4 "managementserver": {

5 "Destinations": {

6 "hostname": {

7 "Address": "https://test-02.example.com/"

8 }

9 }

10 }

11 }

12 }

13 }

If you add several properties to appsettings.Production.json, remember to include a comma between the

properties, but no trailing comma:

1 {

2 "Logging": {

3 "LogLevel": {

4 "Yarp": "Information"

5 }

6 },

7 "ReverseProxy": {

8 "Clusters": {

9 "managementserver": {

10 "Destinations": {

11 "hostname": {

20 / 33

Page is loading ...

Mobotix 2023-R1 HUB APIGateway User manual

Mobotix 2023-R1 HUB APIGateway User manual

Related papers

Other documents