Using AD FS for client authentication

Pexip Infinity can integrate with Active Directory Federation Services (AD FS) to provide Infinity Connect clients and other third-party applications with single sign-on access. This allows users to register their clients using their AD credentials.

This topic explains how to configure AD FS and Pexip Infinity to enable users to register their clients using their AD FS credentials. It covers:

How it works

The process of authenticating and registering an Infinity Connect client to Pexip Infinity via end-user SSO with AD FS works as follows:

  1. When the Infinity Connect client launches it opens up a sign-in page in a web browser for the user to sign in using their AD credentials.
  2. The user signs in with their AD credentials and is redirected back to the Infinity Connect client which requests an access token from AD FS.
  3. The AD FS server returns the AD FS access token to the client. This token proves that the user has successfully authenticated with AD FS.
  4. The Infinity Connect client sends a registration request for the device alias to a Conferencing Node and supplies the AD FS access token. Note that the user's AD credentials are never sent to Pexip Infinity.
  5. The Conferencing Node communicates with the AD FS server to obtain its signing certificate and thus verify that the AD FS access token came from the AD FS server. The Conferencing Node then checks that the AD FS access token is valid for the device alias the user is registering. This means the device alias must be configured as an SSO-enabled alias within Pexip Infinity and have an associated email address that matches the user's email address.
  6. The Conferencing Node sends a Pexip registration token to the Infinity Connect client, which the client then uses to maintain its registration with Pexip Infinity.

Note that:

  • The AD FS access token lasts for 8 hours. The Infinity Connect client automatically opens the sign-in page when it needs a new AD FS access token. This typically occurs when the user loads the client for the first time in the day. However, if the user is already signed into AD FS, then they might not notice anything because they will be immediately redirected back to the client without needing to sign in.
  • A Conferencing Node requests the signing certificate from the AD FS server the first time it needs to validate a token and then caches it for one hour for subsequent SSO registration requests.
  • The Pexip registration token is used by the Infinity Connect client to periodically refresh its registration with the Conferencing Node. This means that while the client remains registered, it does not matter if the AD FS access token expires. But if the client becomes unregistered (e.g. due to a long network connection failure) and the AD FS token has expired, then the user is asked to sign in to AD FS again.
  • The legacy Infinity Connect clients do not support AD FS authentication.

Prerequisites

Before you integrate your AD FS deployment with Pexip Infinity, you must make sure your AD FS deployment satisfies the following requirements.

AD FS version

You must be using a version of AD FS that supports OAuth 2.0, namely either:

  • AD FS 3.0 on Windows Server 2012 R2, or
  • AD FS 4.0 on Windows Server 2016.

Internet accessibility and security

Your Federation Service must be accessible by:

  • all Pexip Infinity Conferencing Nodes
  • all users who need to sign into AD FS to authenticate with Pexip Infinity.

In practice this means your Federation Service must be accessible from the internet. This raises security concerns, but Microsoft provide documentation about the recommended deployment of AD FS:

AD account with email address for each user

Pexip Infinity uses email addresses to identify users. This means every user in your organization who needs to authenticate to Pexip Infinity must have an Active Directory account that includes an email address.

Certificates

Each AD FS server must be provided with a valid and trusted Service Communication Certificate. The subject of this certificate needs to match the Federation Service Name.

Setting up an OAuth 2.0 Client on Windows Server

To set up an OAuth 2.0 Client, use the appropriate set of instructions below for your version of AD FS and Windows Server.

Registering and provisioning Infinity Connect

When your AD FS integration is complete, you can provision your Infinity Connect users with the relevant settings so that they can use AD FS services and their AD credentials to register their Infinity Connect clients to Pexip Infinity.

See Registering and provisioning the Infinity Connect client for instructions about how to do this and for details of the associated end-user experience.

Troubleshooting

You can test your AD FS configuration by going to Users > AD FS Authentication Clients, selecting the client you want to test, and then from the bottom of the page selecting Save and Test Connection.

The page will refresh and display one or more diagnostic messages indicating success or failure. Example error messages are:

Error message Possible cause and resolution
Unable to connect to the Federation Metadata located at https://<address>/FederationMetadata/2007-06/FederationMetadata.xml.

Check that the Federation Service Name FQDN is correct and reachable.

Each AD FS server must be provided with a valid and trusted Service Communication Certificate. The subject of this certificate needs to match the Federation Service Name.

The Entity ID 'http://<address>/adfs/services/trust' was found in the Federation Metadata located at https://<address>/FederationMetadata/2007-06/FederationMetadata.xml. This differs from the AD FS Identifier entered below. Please make sure it is entered correctly. There is a discrepancy between the Federation Service Identifier configured in Pexip Infinity and what is configured in the AD Federation Service Properties.
No signing certificates could be found in the Federation Metadata located at https://<address>/FederationMetadata/2007-06/FederationMetadata.xml. Each AD FS server must be configured with at least one Token-signing certificate. You can check these in your AD FS configuration by going to Service > Certificates and making sure at least one Token-signing certificate is listed and has not expired.

Typical success messages (no action is required) include:

  • "Successfully found one signing certificate in the Federation Metadata located at https://<address>/FederationMetadata/2007-06/FederationMetadata.xml."
  • "Successfully verified AD FS Identifier matches the Entity ID 'http://<address>/adfs/services/trust' in the Federation Metadata located at https://<address>/FederationMetadata/2007-06/FederationMetadata.xml."