Configuring AD FS SSO for personal VMRs

The VMR Scheduling for Exchange feature allows you to create an add-in that enables Microsoft Outlook desktop and Web App users in Office 365 or Exchange environments to quickly and easily add a Pexip VMR to their meeting invitations, enabling any meeting to be held over video.

You can set up VMR Scheduling for Exchange to offer users the option to use their personal VMRs when scheduling meetings. This requires Single Sign-On (SSO).

This topic explains how to configure AD FS to enable SSO for VMR Scheduling for Exchange when using personal VMRs.

In this topic:

How it works

The process of VMR Scheduling for Exchange users authenticating to Pexip Infinity via AD FS in order to obtain their personal VMRs works as follows:

  1. When the Outlook add-in launches, it opens up a pop-up window for the user to sign in to AD FS using their AD credentials.
  2. After the user has successfully signed in, they are redirected back to the Outlook add-in, which then requests an access token from AD FS.
  3. The AD FS server returns the AD FS access token to the Outlook add-in. This token proves that the user has successfully authenticated with AD FS.
  4. Pexip Infinity then updates its record for that user so that the user does not need to log in again when they next activate the add-in.

This process means that:

  • users' SSO credentials are not stored by Pexip Infinity

  • if you delete and recreate a user's record on Pexip Infinity (Users & Devices > Users), they will need to sign in to AD FS again.

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 Windows Server that supports OAuth 2.0 with AD FS, i.e. Windows Server 2012 R2 or later.

Internet accessibility and security

Your Federation Service must be accessible by:

  • all Pexip InfinityConferencing Nodes or, if you are using a reverse proxy for VMR Scheduling for Exchange, all Conferencing Nodes to which the reverse proxy points
  • 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:

Certificates

Each AD FS server must be provided with a valid certificate which is trusted by your Pexip Infinity deployment. 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.

  • Windows Server 2016 and later
  • AD FS 3.0 on Windows Server 2012 R2

These instructions apply to Windows Server 2016 and later.

Creating a Native Application

In this step you create a new application group with a new native application for the OAuth client — which is the Outlook add-in in this case.

  1. Log on to a computer that can make configuration changes to your Federation Service. If your AD FS deployment uses Windows Internal Database (WID), this must be the Primary AD FS Server. If your AD FS deployment uses SQL Server then any AD FS server can make configuration changes.

  2. From the top right of the Server Manager application window, select Tools > AD FS Management.

  3. From the left panel, select Application Groups and then from the right panel select Add Application Group.

  4. At the Welcome screen, enter a Name and Description for the application group. Then from the Template section, under Standalone applications, select Native application.

  5. At the Native application screen, enter a Name for the application. A new Client Identifier is randomly generated for you (this will be required later when configuring the User OAuth client ID on Pexip Infinity.

    In the Redirect URI field, enter:

    https://<address>/api/client/v2/msexchange_schedulers/oauth_redirect
    where <address> is the Add-in server FQDN configured on Pexip Infinity, for example
    https://px01.vc.example.com/api/client/v2/msexchange_schedulers/oauth_redirect

  6. At the Summary screen, review the settings and select Next.

The new application group, along with the new native application, is created.

Creating a Web API Resource

In this step you create a Web API within your application group. The Web API acts as the resource that is accessed when users authenticate to Pexip Infinity using their AD credentials.

  1. On the AD FS Management Tool, from the left-hand panel select Application Groups and from the middle panel select the application group you have just created. From the right-hand panel, select Properties.
  2. At the bottom of the Properties window, select Add application...
  3. At the Welcome screen, from the Template section, select Web API.

  4. At the Configure Web API screen, enter a Name and an Identifier (which must be in URL format). You must use this URL as the AD FS Resource Identifier on Pexip Infinity when configuring a VMR scheduling for Exchange integration.

  5. At the Choose Access Control Policy screen select an appropriate policy. The default is Permit everyone.
  6. At the Configure Application Permissions screen, ensure the native application you created above appears in the list of Client applications. All the Permitted scopes should be deselected because VMR Scheduling for Exchange does not request any scopes.

  7. At the Summary screen, review the entered settings then select Next.

The new Web API should now be created.

Configuring Claim Rules

In this step you configure an Issuance Transform Rule for the Web API. This rule specifies which claims should be sent to the Relying Party (i.e. which claims will be inside the OAuth token that is sent to Pexip Infinity).

Pexip Infinity requires certain claims to be present inside the token in order to establish the user's identity. These are claims that come from the user's Active Directory account.

  1. Ensure there is an Attribute Store configured for Active Directory. To do this, from the AD FS Management Tool, in the left-hand panel expand Service and select Attribute Stores. Select the attribute store called Active Directory. Open its properties and ensure its Attribute store type is Active Directory.

    If the Attribute Store is not present, add it by selecting Add Attribute Store. In the Add an Attribute Store window, enter a Display name of Active Directory and select an Attribute store type of Active Directory.

  2. Add the Issuance Transform Rule on the Web API you just created. To do this, from the AD FS Management Tool, at the bottom of the left-hand panel select Application Groups. Select the Application Group you just created and open its Properties.
  3. Select the Web API you created earlier and then select Edit.

  4. Select the Issuance Transform Rules tab and then select Add Rule.

  5. Select a Claim rule template of Send Claims Using a Custom Rule and then select Next.
  6. Enter a Claim rule name and enter the following as the Custom rule.

    c:[Type ==
    "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
    => issue(store = "Active Directory", types = ("email", "first_name", "last_name", "display_name"), query = ";mail,givenName,sn,displayName;{0}", param = c.Value);

    The above rule queries Active Directory for the attributes: mail, givenName, sn and displayName, and then maps them to the claims: email, first_name, last_name and display_name which will appear in the token payload that is returned when the user successfully logs in. The email claim is required by Pexip Infinity when verifying the token. If it is not present in the token, the user will fail to authenticate to Pexip Infinity.

  7. Select Finish, and in the next window ensure you select Apply.

Checking and enabling AD FS endpoints

In this step you ensure that the appropriate AD FS endpoints have been enabled to support Pexip's requirements. In the context of AD FS, an endpoint is a URL that AD FS is configured to serve.

To find the details of these AD FS endpoints:

  1. From the Server Manager application window, select Tools > AD FS Management.
  2. From the AD FS Management Tool, in the left-hand panel expand AD FS > Service > Endpoints.
  3. Locate and check the following endpoint:

    • an OAuth type endpoint with path /adfs/oauth2/
      (this is used by users who sign in to AD FS)

    Ensure that this endpoint is Enabled. If you are using a Web Application Proxy (WAP) you must also ensure they are Proxy Enabled.

Determining Federation Service Properties

To configure AD FS SSO for personal VMRs on the Pexip Infinity Management Node, you must first determine your Federation Service Name (this is the FQDN that clients use to access AD FS). The Federation Service Name will be used as the domain part of the User OAuth authorization URI and the User OAuth token URI. To check this:

  • From the AD FS Management Tool, from the left-hand panel select the top level AD FS folder, and then select Edit Federation Service Properties.

In the example below, the Federation Service Name is adfs.rd.pexip.com.

These instructions apply to AD FS 3.0 on Windows Server 2012 R2.

Creating a Relying Party Trust

In this step you create a Relying Party Trust, which acts as the resource that is accessed when users authenticate to Pexip Infinity using their AD credentials.

  1. Log on to a computer that can make configuration changes to your Federation Service. If your AD FS deployment uses Windows Internal Database (WID), this must be the Primary AD FS Server. If your AD FS deployment uses SQL Server then any AD FS server can make configuration changes.

  2. From the Server Manager application window, select Tools > AD FS Management.
  3. From the left-hand panel, expand AD FS > Trust Relationships > Relying Party Trusts. Then from the right-hand panel select Add Relying Party Trust....

  4. At the Add Relying Party Trust Wizard welcome screen, select Start.
  5. At the Select Data Source screen, select Enter data about the relying party manually and select Next.

  6. At the Specify Display Name screen, enter a Display name and Note, and select Next.

  7. At the Choose Profile screen, select AD FS profile and select Next.

  8. At the Configure Certificate screen, do not configure a certificate. Simply select Next.

  9. At the Configure URL screen, do not enable support for either the WS-Federation Passive or the SAML 2.0 WebSO protocols. Simply select Next.

  10. At the Configure Identifiers screen, enter a Relying Party Trust Identifier. This must be unique against all of your Relying Party Trusts, and must be in URL format.

    You will need to enter this later when adding an AD FS Resource Identifier on Pexip Infinity when configuring a VMR scheduling for Exchange integration.

  11. At the Configure Multi-factor Authentication Now? screen, optionally enable multi-factor authentication. Enabling multi-factor authentication will affect how your users sign in to AD FS.

  12. At the Choose Issuance Authorization Rules screen, select Permit all users to access this relying party.

  13. At the Ready to Add Trust screen, review the settings and then select Next.

  14. At the Finish screen, verify that the relying party trust was added successfully. Choose to Open the Edit Claim Rules dialog... then select Close.

Configuring Claim Rules

In this step you configure an Issuance Transform Rule for the Relying Party. This rule specifies which claims should be sent to the Relying Party (i.e. which claims will be inside the OAuth token that is sent to Pexip Infinity).

Pexip Infinity requires certain claims to be present inside the token in order to establish the user's identity. These are claims that come from the user's Active Directory account.

  1. Ensure there is an Attribute Store configured for Active Directory. To do this, in the AD FS Management Tool, from the left-hand panel expand AD FS > Trust Relationships > Attribute Stores. Look for the attribute store called Active Directory. Open its properties and ensure its Attribute store type is Active Directory.

    If the Attribute Store is not present, add it by selecting Add Attribute Store. In the Add an Attribute Store window, enter a Display name of Active Directory and select an Attribute store type of Active Directory.

  2. From the left-hand panel expand AD FS > Trust Relationships > Relying Party Trusts, select the Relying Party you just created, and from the right-hand panel select Edit Claim Rules....

  3. Select the Issuance Transform Rules tab, then select Add Rule....

  4. At the Select Rule Template screen, select a Claim rule template of Send Claims Using a Custom Rule.

  5. At the Configure Rule screen, enter a Claim rule name, and in the Custom rule section enter the following:

    c:[Type ==
    "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
    => issue(store = "Active Directory", types = ("email", "first_name", "last_name", "display_name"), query = ";mail,givenName,sn,displayName;{0}", param = c.Value);

    The above rule queries Active Directory for the attributes: mail, givenName, sn and displayName, and then maps them to the claims: email, first_name, last_name and display_name which will appear in the token payload that is returned when the user successfully logs in. The email claim is required by Pexip Infinity when verifying the token. If it is not present in the token, the user will fail to authenticate to Pexip Infinity.

  6. Select Finish.
  7. You are returned to the Issuance Transform Rules tab. Select Apply.

Checking and enabling AD FS endpoints

In this step you ensure that the appropriate AD FS endpoints have been enabled to support Pexip's requirements. In the context of AD FS, an endpoint is a URL that AD FS is configured to serve.

To find the details of these AD FS endpoints:

  1. From the Server Manager application window, select Tools > AD FS Management.
  2. From the AD FS Management Tool, in the left-hand panel expand AD FS > Service > Endpoints.
  3. Locate and check the following endpoint:

    • an OAuth type endpoint with path /adfs/oauth2/
      (this is used by users who sign in to AD FS)

    Ensure that this endpoint is Enabled. If you are using a Web Application Proxy (WAP) you must also ensure they are Proxy Enabled.

Determining Federation Service Properties

To configure AD FS SSO for personal VMRs on the Pexip Infinity Management Node, you must first determine your Federation Service Name (this is the FQDN that clients use to access AD FS). The Federation Service Name will be used as the domain part of the User OAuth authorization URI and the User OAuth token URI. To check this:

  • From the AD FS Management Tool, from the left-hand panel select the top level AD FS folder, and then select Edit Federation Service Properties.

In the example below, the Federation Service Name is adfs.rd.pexip.com.

Adding the OAuth 2.0 Client to AD FS

In this final step you add the OAuth 2.0 client to AD FS. This is done using the Add-AdfsClient PowerShell command.

A client ID is required to run this command. To obtain an appropriate client ID you can either:

After you have obtained a client ID, open PowerShell on your AD FS server, then run this command:

Add-AdfsClient -Name "<name>" -ClientId "<client id>" -RedirectUri "https://<address>/api/client/v2/msexchange_schedulers/oauth_redirect" -Description "<description>"

where:

  • <name> is a name of your choice used to identify the AD FS client
  • <client id> is the the User OAuth client ID obtained in either of the two ways described above
  • <address> is the Add-in server FQDN configured on Pexip Infinity (i.e. the FQDN of the reverse proxy or Conferencing Node that provides the add-in content)
  • <description> is an optional description.

For example:

Add-AdfsClient -Name "Pexip Scheduling" -ClientId "141c7f59-790b-46f7-add1-7490ee4b489e" -RedirectUri "https://tobyrp.rd.pexip.com/api/client/v2/msexchange_schedulers/oauth_redirect" -Description "The OAuth Client for Pexip Scheduling personal VMRs"

To verify this worked, run Get-AdfsClient and make sure the client you just added is in the results.


Next steps

  1. Configuring Pexip Infinity to integrate with your Microsoft Exchange deployment and create the VMR Scheduling for Exchange add-in.
  2. Making the add-in available to users within your Microsoft Exchange deployment.