Component environments for login

The MIP SDK (component) environments and how to log in to them.

Component environments for login

MIP SDK provides three environments for authentication and initialization in component (stand-alone) solutions: one general environment for most use cases, and two designed to handle special use cases. The three environments are:

Environment class Description
VideoOS.Platform.SDK.Environment

This environment handles the general case of one user connected directly to one XProtect VMS site.

Code samples: almost all component samples.
VideoOS.Platform.SDK.MultiEnvironment

MultiEnvironment is designed to have one or more users connect to two or more XProtect VMS sites. This makes it possible to combine data from several sites without them being set up in a MFA. Login settings and session data for each user is maintained in a VideoOS.Platform.UserContext.

Milestone Interconnect uses MultiEnvironment.

Code sample: System Status Client Console.
VideoOS.Platform.SDK.MultiUserEnvironment

MultiUserEnvironment is used to manage multiple users connected to one XProtect VMS site. The MultiUserEnvironment one overall user to monitor the XProtect VMS and update the VideoOS.Platform.UserContext for each logged-in users when configuration changes happen.

XProtect Mobile server uses MultiUserEnvironment.

Code sample: Multi-User environment.

Log in to the environments

Credential types

All three MIP SDK environments support the following credential types:

  • XProtect basic user - created locally with username and password in an XProtect VMS. An XProtect basic user won't be able to access MFA child sites.
  • Windows user - created in the AD (Active Directory) of the XProtect VMS and given access to the XProtect VMS.
  • OAuth token - authenticating using an identity token provided by an IDP (internal or external Identity Provider).

secureOnly and masterOnly

In all three MIP SDK environments, methods that update the environment in preparation of login have the parameters secureOnly and masterOnly.

Parameter Description

secureOnly

If true, only authentication over HTTPS is accepted. Can only be used for server versions 2021 R1 or newer. If false, authentication over both HTTP and HTTPS is accepted..

masterOnly

An XProtect VMS site that is part of a Milestone Federated Architecture (MFA) hierarchy can have one or more child sites. MFA requires Corporate license for parent (center) sites and Corporate or Expert licenses for child (remote) sites. masterOnly is only relevant for a MFA site with child sites.

Default is true. If false, also log in to and gather information from child sites to VideoOS.Platform.Configuration.

Credentials

The MIP SDK provides helper methods for creating and handling System.Net-based login credentials, and the class MipTokenCache for handling OAuth-based authentication.

Credentials Method Description

NetworkCredential

VideoOS.Platform.Login.Util.BuildNetworkCredential()

Provides credentials for password-based authentication schemes (Basic, Windows, or Windows default user).

CredentialCache

VideoOS.Platform.Login.Util.BuildCredentialCache()

Provides storage for multiple credentials.

MIPTokenCache

VideoOS.Platform.SDK.OAuth.MipTokenCache()

A MIPTokenCache can be instantiated with the URL of the IDP server and credentials. It will then get a new token and refresh the token as needed.

In some cases, users might want to use a ManualMipTokenCache, which is instantiated with the JWT token received from the IDP server. The ManualMipTokenCache will not update the token, but the object can be parsed to any methods that require a MIPTokenCache and the token can be updated using the method UpdateAccessToken.

The code snippets below uses different kind of credential mechanisms to demonstrate how credentials are created and used.

See also the section Login Process in .NET Library Initialization.

Log in to Environment

Log in as a Basic user to Environment using CredentialCache

VideoOS.Platform.SDK.Environment.Initialize();

Uri mangementServerUri = new Uri("https://mangementserverUrl");
bool secureOnly = true;
bool masterOnly = true;
Guid integrationId = new Guid("7A7B4B62-A6F1-49E4-9C61-D541CC54411A");
string integrationName = "TestIntegration";
string version = "1.0.0.0";
string manufacturerName = "TestCompany";

CredentialCache cc = VideoOS.Platform.Login.Util.BuildCredentialCache(mangementServerUri, "basicUser", "Password", "Basic");
VideoOS.Platform.SDK.Environment.AddServer(secureOnly, mangementServerUri, cc, masterOnly);
try
{
    VideoOS.Platform.SDK.Environment.Login(mangementServerUri, integrationId, integrationName, version, manufacturerName, masterOnly);
}
catch (. . .)
{
    . . .
}
Log in as a Windows (AD) user to Environment using MIPTokenCache

VideoOS.Platform.SDK.Environment.Initialize();

Uri managementServerUri = new Uri("https://mangementserverUrl");
Uri idpServerUri = new Uri("https://mangementserverUrl/IDP");
bool isBasicUser = false;
bool secureOnly = true;
bool masterOnly = false;
Guid integrationId = new Guid("7A7B4B62-A6F1-49E4-9C61-D541CC54411A");
string integrationName = "TestIntegration";
string version = "1.0.0.0";
string manufacturerName = "TestCompany";

NetworkCredential networkCredential = VideoOS.Platform.Login.Util.BuildNetworkCredential(managementServerUri, @"AD\AdUser", "Password", "Negotiate");
MipTokenCache mipTokenCache = new MipTokenCache(idpServerUri, networkCredential, isBasicUser);
VideoOS.Platform.SDK.Environment.AddServerOAuth(secureOnly, managementServerUri, mipTokenCache, masterOnly);
try
{
    VideoOS.Platform.SDK.Environment.Login(mangementServerUri, integrationId, integrationName, version, manufacturerName, masterOnly);
}
catch(. . .)
{
    . . .
}

Log in to MultiEnvironment

Log in as a Windows (AD) user to MultiEnvironment

VideoOS.Platform.SDK.Environment.Initialize();

bool secureOnly = true;
bool usingAD = true;

MultiEnvironment.InitializeUsingUserContext();
Uri mangementServerUri = new Uri("https://mangementserverUrl");
var userContext = MultiEnvironment.CreateSingleServerUserContext(secureOnly, @"domain\username", "password", usingAD, mangementServerUri);
bool loginSucceeded = MultiEnvironment.LoginUserContext(userContext);

Log in to MultiUserEnvironment


Uri managementServerUri = new Uri("https://managementserverUrl");

// This user must have a role with overall access, for example Administrators
VideoOS.Platform.SDK.MultiUserEnvironment.InitializeUsingUserContext(secureOnly: true, uri, "BasicUser", "Password", usingAD: false, masterOnly: false);
if (VideoOS.Platform.SDK.MultiUserEnvironment.InitializeLoggedIn == false)
{
    // Do some cleanup
    VideoOS.Platform.SDK.MultiUserEnvironment.UnInitialize();
    return;
}

// Create a MultiUserEnvironment and log in an ordinary user
UserContext userContext1 = VideoOS.Platform.SDK.MultiUserEnvironment.CreateUserContext(@"Domain\ADUser", "ADPassword", usingAD: true);
try
{
    VideoOS.Platform.SDK.MultiUserEnvironment.LoginUserContext(userContext1);

}
catch(Exception ex)
{
    throw new Exception("Login failed", ex);
}

Log in using protocols

Stand-alone integrations doesn't have to use the MIP SDK component .NET libraries; it is possible to log in and access an XProtect VMS using network protocols. XProtect supports several generations of protocols: SOAP and the MIP VMS API.

SOAP

MIP VMS API