External IDP (explained)

IDP is an acronym for Identity Provider. An external IDP is an external application and service where you can store and manage user identity information and provide user authentication services to other systems. You can associate an external IDP with the XProtect VMS.

XProtect supports external IDPs that are compatible with OpenID Connect (OIDC).

User authentication

With an external IDP configured, the XProtect clients support the use of external IDPs as an additional authentication option.

When the computer address in the client login screen points to an XProtect VMS with an external IDP configured, an API call will be triggered and the authentication option for the external IDP will be available on the login screen. The API call is activated when the client is started and whenever the address is changed.

The particular API that the client queries is a public API that does not require any user authentication, so this information can always be read by the client.

Claims

A claim is a statement that an entity such as a user or an application makes about itself.

The claim consists of a claim name and a claim value. For example, the claim name could be a standard name that describes the content of the claim value, and the claim value could be the name of a group. See more example of claims from an external IDP: Example of claims from an external IDP.

Claims are not mandatory. However, they are required in order to automatically link external IDP users to roles in the XProtect VMS in order to determine the users' permissions. The claims are included in the users’ ID token from the external IDP and through the association with roles they determine the user's permissions in XProtect.

If claims related to the XProtect VMS roles are not provided for the external IDP users, the external IDP users can be created in the XProtect VMS when they log on for the first time. In this case the external IDP users are not linked to any roles. The XProtect VMS administrator must then manually add the users to roles.

Prerequisites for external IDPs

The following steps should be completed in the external IDP before it is configured in the VMS.

The client ID and secret for use with the XProtect VMS must have been created in the external IDP. For more information, see Unique user names for external IDP users .
The authentication authority for the external IDP must be known. For more information, see the information about authentication authority for the external IDP in the Options dialog box. must be known.
The redirect URIs to the XProtect VMS must have been configured in the IDP. For more information, see Add redirect URIs for the web clients.
Optionally, VMS related claims must have been configured for the users or groups in the IDP.
The XProtect VMS must be fully configured with certificates to ensure that all communication is done over encrypted https. otherwise, most external IDPs will not accept requests from the XProtect VMS and its clients, or a part of the communication flow and security token exchange will fail.
It must be possible for the XProtect VMS and all client computers or smart phones that should use the external IDP to contact the external IDPs login address

Enable users to log in to the XProtect VMS from an external IDP

From the external IDP, create the users and create claims to identify users as external IDP users in the XProtect VMS. The creation of claims is not a mandatory step but this is how you enable automatically linking users to roles. For more information, see Claims.
From the XProtect VMS, create a configuration that enables the Identity Provider, that is built into the VMS, to contact the external IDP. For more information about how to create a configuration for an external IDP, see Add and configure an external IDP.
From the XProtect VMS, establish authentication of users by mapping the user claims from the external IDP to XProtect roles. For more information about how to map claims to roles, see Map claims from an external IDP to roles in XProtect.
Log into an XProtect client using an external IDP for user authentication, see Log in via an external IDP.

Redirect URIs

The redirect URI specifies the page that the user is sent to after a successful authentication. In your external IDP, you must add the address of the management server followed by the Callback path you defined in XProtect Management Client. For example, https://management-server-computer.company.com/idp/signin-oidc

Depending on how the XProtect VMS is accessed, how the network, servers and Microsoft Active Directory is configured, several redirect URIs may be needed, you can see some examples below:

Examples

Management server with or without the domain in the URL:

“https://[server_name]/idp/signin-oidc”
“https://[server_name].[domain_name]/idp/signin-oidc”

Mobile server with or without the domain in the URL:

“https://[server_name]:[mobile_port]/idp/signin-oidc”
“https://[server_name].[domain_name]:[mobile_port]/idp/signin-oidc”

If the mobile server is set up to be accessed over the internet, you must also add the public address and ports.

Unique user names for external IDP users

User names are created automatically for users that log in to Milestone XProtect via an external IDP.

The external IDP provides a set of claims to automatically create a name for the user in XProtect, and in XProtect an algorithm is used to pick a name from the external IDP that is unique in the VMS database.

Example of claims from an external IDP

The claims consist of a claim name and a claim value. For example:

Claim name	Claim value
name	Raz Van
email	123@domain.com
amr	pwd
idp	00o2ghkgazGgi9BIE5d7
preferred_username	321@domain.com
vmsRole	Operator
locale	en-US
given_name	Raz
family_name	Lindberg
zoneinfo	America/Los_Angeles
email_verified	True

Using sequence number of claim to create user names in XProtect

In XProtect, the search priority for when creating a user in the XProtect VMS is controlled by the sequence number of the claims in the table below. The first available claim name will be used in the XProtect VMS:

Claim name	Sequence number	Description
UserNameClaimType	1	Configured mapping with one claim to define the user name. The claim is defined in the Claim to use to create user name field on the External IDP tab under Tools > Options.
preferred_username	2	Claim that can come from the external IDP. A standard claim that is normally used for this in Oidc (OpenID Connect).
name	3
given_name family_name	4	Given name and family name in a combination such as Bob Johnson.
email	5
First available claim + #(first available number)	6	For example, Bob#1

Defining specific claims to create user names in XProtect

The XProtect administrators can define a specific claim from the external IDP that should be used to create a user name in the XProtect VMS. When an administrator define a claim to use for the creation of the user name in the XProtect VMS, the claim name must be written exactly as the claim name coming from the external IDP.

The claim to use for the user name can be defined in the Claim to use to create user name field on the External IDP tab under Tools > Options .

Deleting external IDP users

Users created in XProtect by an external IDP login are deleted the same way as a basic user and the user can be deleted at any time after the user is created.

If a user is deleted in XProtect and the user logs in again from the external IDP, a new user will be created in XProtect. However, the data associated with the user in XProtect such as private views and roles are lost and this information has to be created again for the user in XProtect.

If an external IDP is deleted in the Management Client, any users connected to the VMS via the external IDP are also deleted.