Registering and provisioning the Infinity Connect client

The Infinity Connect desktop client can register to a Pexip Infinity Conferencing Node. Infinity Connect clients that are registered to Pexip Infinity can:

  • receive calls (as well as place them)
  • use directory services to filter and lookup the contact details (phone book) of other devices or VMRs that are set up on the Pexip Infinity platform, making it easier to call those addresses.

Registration is optional. You do not need to register your device in order to make calls.

This topic covers the client authentication options, the DNS requirements, how to provision the clients , some example provisioning email template content, and a description of the associated user experience.

Client authentication options

When registering an Infinity Connect client to Pexip Infinity, the alias being registered by the client must match one of the entries on the Management Node under Users & Devices > Device aliases. When configuring a device alias, you can specify whether and how an Infinity Connect client that is attempting to register with that alias should authenticate itself (authentication is optional but recommended):

  • SSO: the client uses Single Sign-On (SSO) services such as AD FS to authenticate the registration.
  • Non-SSO: the username and password credentials associated with the alias to authenticate the registration.

For any given alias, we recommend that you enable Infinity Connect registrations for either SSO or non-SSO authentication, not both.

See Registering devices to Pexip Infinity for more information on the Pexip Infinity registrar service, including how to configure device aliases and their associated authentication options.

Setting up appropriate DNS records

The Infinity Connect desktop client uses its configured Registration Host and performs a DNS SRV lookup on _pexapp._tcp.<registration host address> to locate a Conferencing Node to which it can send its registration request.

You must therefore ensure that appropriate DNS records have been set up - for more information, see Setting up DNS records for Infinity Connect client connectivity.

Provisioning the Infinity Connect desktop client with registration and/or branding details

Users can manually enter their registration details (alias, credentials, registration server address) into their Infinity Connect client. However, as an administrator you can simplify this process by provisioning individual users with their registration details and automatically applying those registration settings to their Infinity Connect desktop client.

You can also provision the Infinity Connect desktop and mobile clients with instructions to use the same branding that has been uploaded to Pexip Infinity (and which is being used automatically by the web app).

You perform these provisioning tasks by supplying each user with a provisioning URI in the format:

https://<node_address>/api/client/v2/provision?data=<Base64 encoded name-value pairs>&message=<Base64 encoded message>

where:

  • <node_address> is the address of a Conferencing Node.
  • <Base64 encoded name-value pairs> are the data values used to provision the client, and are described below.
  • <Base64-encoded message> is the provisioning message that is displayed to the user. The message parameter is optional and by default is "Your Pexip App should have opened and asked to be provisioned. You can now close this window."

Base64 encoding is used to ensure that the data does not get modified by email clients. Note that Base64-encoded data is not encrypted.

For example, the provisioning URI might look like this: https://px01.vc.example.com/api/client/v2/provision?data=ZzUmVkaXJl...etc...D%3D&message=bkgY3VzdG9tIG1lc3Nh

This provisioning URI can be inserted into email messages without the risk of the link being disabled (unlike the alternative pexip-provision:// URI scheme). This means users will have a directly clickable link without needing to copy and paste the link into their web browser.

Provisioning name-value pairs

The name-value pairs that can be provisioned in the data query string parameter are described in the following table. If you use Pexip Infinity to bulk provision device aliases and generate emails to each user, you can use the provided template variables and custom Pexip filters to obtain the values for some of the data items and generate the relevant URIs for each user/client. The table shows the common data items, and the additional data items that are used for AD FS SSO authentication:

Name Value Suggested template variable
name The name of the user as it will appear to other conference participants. device_username
registrationHost The address of the Conferencing Node to which the client should register, for example px01.vc.example.com. There is no suitable variable for this, as it is not a user specific value.
registrationAlias The alias of the device to register to Pexip Infinity. device_alias
registrationUsername

The username associated with the device alias (registrationAlias).

This does not apply if you are using SSO services.

device_username
registrationPassword

The password associated with the device alias (registrationAlias).

This does not apply if you are using SSO services.

device_password
brandingURL

A reference to a directory that contains customized branding configuration. In most cases this will be:

https://<node_address>/webapp2/custom_configuration/

where <node_address> is the FQDN of a Conferencing Node.

You typically use this to instruct the Infinity Connect client to use the same branding that has been uploaded to Pexip Infinity (and which is being used automatically by the web app). In advanced customization scenarios you can refer to a specific branding package hosted on a different server.

This parameter is supported on Infinity Connect clients version 1.3 or later.

See Customizing the Infinity Connect clients for more information.

There is no suitable variable for this, as it is not a user specific value.
Additional data items when using AD FS SSO authentication
adfsFederationServiceName† The Federation Service name e.g. adfs.example.com. There are no suitable variables for these items, as they are not user specific values.
adfsResource† The Resource Identifier e.g. https://pexipappsso.local.
adfsClientID† The Client ID e.g. a2a07b42-66d7-41e4-9461-9d343c25b7f3.
adfsRedirectURI

This is the URI you want the user to be redirected back to after they sign into AD FS. It does not correspond with a value configured on the Management Node but it must be one of the redirect URIs you set up when configuring AD FS on your Windows Server. We recommend you use:

https://<address>/api/client/v2/oauth2_redirect where <address> is the FQDN of a Conferencing Node or reverse proxy, for example https://px01.vc.example.com/api/client/v2/oauth2_redirect.

When the oauth2_redirect page loads it opens the Infinity Connect client to complete the sign-in process. The oauth2_redirect page will remain open but it displays a message which by default is "You have successfully signed in. You can now close this window."

You can change this message by including the optional base64-encoded message parameter on the oauth2_redirect page URL. For example, the message "my custom message" is "bXkgY3VzdG9tIG1lc3NhZ2U=" when base64-encoded. You would then specify the adfsRedirectURI as follows: https://confnode.example.com/api/client/v2/oauth2_redirect?message=bXkgY3VzdG9tIG1lc3NhZ2U=

† These AD FS related data values should correspond to what you have configured in Pexip Infinity (Users & Devices > AD FS Authentication Clients) for the OAuth 2.0 Client. See Using AD FS for client authentication for more information.

You do not have to provision all of the common name-value data items — if you supply a subset of the data, the user can manually enter the additional data if required. When using AD FS SSO provisioning, all of the AD FS data items must be included in the provisioning data. Note that the clients do not need to be registered in order to use the branding provisioning feature.

Example device email template content

The following example content for a device provisioning email template shows how you can build the relevant URI with base64-encoded provisioning data (using device provisioning variables populated from LDAP) and provide a clickable link for the recipient of the email that will provision their client. The first line in this example defines and sets various variables and the second line incorporates those variables in the paragraph text and link that is displayed to the recipient.

{%set provisiondata = "name=" + device_username|capitalize + "&registrationHost=confnode.example.com&registrationAlias=" + device_alias + "&registrationUsername=" + device_username + "&registrationPassword=" + device_password %}

<p>You can open <a href="https://confnode.example.com/api/client/v2/provision?{{pex_url_encode(('data', provisiondata|pex_base64))}}">this link</a> to automatically configure your client.</p>

Remember to substitute confnode.example.com with the address of your Conferencing Node.

You can extend the previous example and include the message URL parameter (set to 'Provision your app' in this example) in the provisioning link (the %set statement is identical to the previous example):

{%set provisiondata = "name=" + device_username|capitalize + "&registrationHost=confnode.example.com&registrationAlias=" + device_alias + "&registrationUsername=" + device_username + "&registrationPassword=" + device_password %}

<p>You can open <a href="https://confnode.example.com/api/client/v2/provision?{{pex_url_encode(('data', provisiondata|pex_base64), ('message', 'Provision your app'|pex_base64))}}">this link</a> to automatically configure your client.</p>

AD FS SSO examples

This is an example of a provisioning link which can be used to set up Single Sign-On via AD FS:

{%set provisiondata = "name=" + device_username|capitalize + "&registrationHost=confnode.example.com&registrationAlias=" + device_alias + "&adfsFederationServiceName=adfs.example.com&adfsResource=https://pexipappsso.local&adfsClientID=a2a07b42-66d7-41e4-9461-9d343c25b7f3&adfsRedirectURI=https://confnode.example.com/api/client/v2/oauth2_redirect" %}

<p>Simply open <a href="https://confnode.example.com/api/client/v2/provision?{{pex_url_encode(('data', provisiondata|pex_base64))}}">this link</a> to configure your client automatically.</p>

Remember to substitute confnode.example.com with the address of your Conferencing Node, and to set the adfsFederationServiceName, adfsResource and adfsClientID variables with the appropriate values for your AD FS service.

This next example shows how to include the "successfully signed in" message URL parameter (set to 'Successfully signed-in message' in this example) in the oauth2_redirect link:

{%set provisiondata = "name=" + device_username|capitalize + "&registrationHost=confnode.example.com&registrationAlias=" + device_alias + "&adfsFederationServiceName=adfs.example.com&adfsResource=https://pexipappsso.local&adfsClientID=a2a07b42-66d7-41e4-9461-9d343c25b7f3&adfsRedirectURI=https://confnode.example.com/api/client/v2/oauth2_redirect?" + pex_url_encode(('message', 'Successfully signed-in message'|pex_base64)) %}

<p>Simply open <a href="https://confnode.example.com/api/client/v2/provision?{{pex_url_encode(('data', provisiondata|pex_base64))}}">this link</a> to configure your client automatically.</p>

This final example shows how the "successfully signed in" message (on the oauth2_redirect URL) and the "provision your app" message (on the provision URL) can be customized:

{%set provisiondata = "name=" + device_username|capitalize + "&registrationHost=confnode.example.com&registrationAlias=" + device_alias + "&adfsFederationServiceName=adfs.example.com&adfsResource=https://pexipappsso.local&adfsClientID=a2a07b42-66d7-41e4-9461-9d343c25b7f3&adfsRedirectURI=https://confnode.example.com/api/client/v2/oauth2_redirect?" + pex_url_encode(('message', 'Successfully signed-in message'|pex_base64)) %}

<p>You can open <a href="https://confnode.example.com/api/client/v2/provision?{{pex_url_encode(('data', provisiondata|pex_base64), ('message', 'Provision your app'|pex_base64))}}">this link</a> to automatically configure your client.</p>

User experience when using the provisioning link

Non-SSO provisioning

When the user clicks on the provisioning link, they are typically asked to confirm or authorize the launch of the Infinity Connect application (the exact nature of the request varies according to the platform and the method of launching the link) and then the Infinity Connect client will launch and present the user with a confirmation screen:

1. Select Open Link to launch Infinity Connect.

2. Select Continue to apply and save the settings contained in the provisioning link.

The registration settings in the client are read-only when the client is successfully registered — you must Unregister if you want to change them.

AD FS SSO provisioning

When AD FS SSO provisioning is used, the user is also prompted to sign to AD FS with their AD credentials. Here are some examples of the screens that are displayed during the provisioning process (the exact nature varies according to the platform, browser and whether the messages have been customized):

1. Confirm to open the Infinity Connect client.

2. Select Continue to proceed with provisioning the client.

3. Sign in to AD FS.

4a. AD FS sign-in successful.

4b. Select Open Link to launch Infinity Connect and complete the sign-in process.

 

When a client has been configured (provisioned) with SSO registration information, the user name / password fields are blank and the registration settings can only be modified by resetting the app.

Alternative pexip-provision:// URI provisioning scheme

When the Infinity Connect client installs, it registers itself to the pexip-provision:// URI scheme. This provides an alternative provisioning URI that can be used to configure the client with personalized settings for each user. This URI takes the following format:

pexip-provision://settings/?data=<Base64 encoded name-value pairs>

where data is set to the same set of name-value pairs as described above.

We recommend using the https://<node_address>/api/client/v2/provision style links instead of the pexip-provision:// style links, as some mail clients (such as gmail) disable embedded pexip-provision:// style links and other mail clients (such as Outlook) may present users with a security notice warning that the hyperlink may be unsafe and users must choose to continue in order to launch the application.

The following example content for a device provisioning email template shows how you can build the relevant pexip-provision:// URI with base64-encoded provisioning data (using device provisioning variables populated from LDAP) and provide a clickable link for the recipient of the email that will provision their client.

{%set provisiondata = "name=" + device_username|capitalize + "&registrationHost=px01.vc.example.com&registrationAlias=" + device_alias + "&registrationUsername=" + device_username + "&registrationPassword=" + device_password %}

<p>You can open <a href="pexip-provision://settings?data={{provisiondata|pex_base64}}"> this link</a> to automatically configure your client.</p>

The generated URI for "this link" will take the form pexip-provision://settings?data=bmFtZT1...etc...HVhcA==