Using AD FS for client authentication

These instructions apply to AD FS 4.0 on Windows Server 2016.

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 AD FS Management Tool, in the left-hand panel expand AD FS > Service > Endpoints.

2. Locate and check the following 2 endpoints:

   • an OAuth type endpoint with path /adfs/oauth2/
     (this is used by users who sign in to AD FS)
   • a Federation Metadata type endpoint with path /FederationMetadata/2007-06/FederationMetadata.xml
     (this is used by Conferencing Nodes)

   Ensure that both of these endpoints are Enabled. If you are using a Web Application Proxy you must also ensure they are Proxy Enabled.

   

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 Infinity Connect client 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 adding the OAuth client details to the Management Node).

   In the Redirect URI field, enter 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.

   You may want to use a reverse proxy rather than a Conferencing Node for the redirect URI if you want to provide some redundancy capability.

   The Redirect URI you enter here must match exactly the URI used when provisioning the Infinity Connect client.

   

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).

   

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 the Pexip Infinity apps do 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", "object_guid", "first_name", "last_name", "display_name"), query = ";mail,objectGUID,givenName,sn,displayName;{0}", param = c.Value);

   The above rule queries Active Directory for the attributes: mail, objectGUID, givenName, sn and displayName, and then maps them to the claims: email, object_guid, 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 and object_guid claims are required by Pexip Infinity when verifying the token. If they are 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.

Determining Federation Service Properties

To add an AD FS OAuth 2.0 Client to the Pexip Infinity Management Node, you must first determine your Federation Service Name (this is the FQDN that clients use to access AD FS) and Federation Service Identifier. To check these:

• 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 and the Federation Service identifier is http://adfs.rd.pexip.com/adfs/services/trust.

Adding the AD FS OAuth 2.0 Client to the Pexip Infinity Management Node

1. From the Pexip Infinity Management Node, go to Users & Devices > AD FS Authentication Clients.
2. Select Add AD FS OAuth 2.0 Client.

3. Complete the fields as follows:

   Field	Description
   Name	The name to use to refer to this OAuth 2.0 client on AD FS.
   Description	An optional description of this OAuth 2.0 client.
   AD FS Server configuration
   Federation Service name	The FQDN which is used by clients to connect to AD FS. This is the name seen when Determining Federation Service Properties.
   Federation Service Identifier	The URL which identifies AD FS. This is the identifier seen when Determining Federation Service Properties.
   Resource Identifier	The URL which identifies the OAuth 2.0 resource on AD FS. This should be the identifier you gave the Web API resource which you created earlier.
   Client ID	The ID of the AD FS OAuth 2.0 Client. This will show a randomly generated GUID but you must replace this with the one that was generated earlier when Creating a Native Application.
   AD FS Domains
   AD FS Domain: #1
   Domain	An FQDN which, when present in a user's email address, permits that user to authenticate using this AD FS OAuth 2.0 client. For example, if a user has the email bob@example.com, then example.com must be configured as a Domain to allow that user to sign on with AD FS. A single domain can only be used by a single AD FS 2.0 OAuth client, but the same domain can also be used by a Google OAuth 2.0 credential.
   Description	An optional description of the AD FS domain.

4. Select Save and Test Connection. This will save your data and report success or failure details of this connection. See Troubleshooting for more information.

Users should now be able to use AD FS services and their AD credentials to register their Infinity Connect clients to Pexip Infinity.

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

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 AD FS Management Tool, in the left-hand panel expand AD FS > Service > Endpoints.

2. Locate and check the following 2 endpoints:

   • an OAuth type endpoint with path /adfs/oauth2/
     (this is used by users who sign in to AD FS)
   • a Federation Metadata type endpoint with path /FederationMetadata/2007-06/FederationMetadata.xml
     (this is used by Conferencing Nodes)

   Ensure that both of these endpoints are Enabled. If you are using a Web Application Proxy you must also ensure they are Proxy Enabled.

   

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.

    

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", "object_guid", "first_name", "last_name", "display_name"), query = ";mail,objectGUID,givenName,sn,displayName;{0}", param = c.Value);

   

   The above rule queries Active Directory for the attributes: mail, objectGUID, givenName, sn and displayName, and then maps them to the claims: email, object_guid, 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 and object_guid claims are required by Pexip Infinity when verifying the token. If they are 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.

   

Determining Federation Service Properties

To add an AD FS OAuth 2.0 Client to the Pexip Infinity Management Node, you must first determine your Federation Service Name (this is the FQDN that clients use to access AD FS) and Federation Service Identifier. To check these:

• 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 and the Federation Service identifier is http://adfs.rd.pexip.com/adfs/services/trust.

Adding the AD FS OAuth 2.0 Client to the Pexip Infinity Management Node

In this step you add the details of the OAuth 2.0 client to the Pexip Infinity Management Node.

1. From the Pexip Infinity Management Node go to Users & Devices > AD FS Authentication Clients.
2. Select Add AD FS OAuth 2.0 Client.

3. Complete the fields as follows:

   Field	Description
   Name	The name to use to refer to this OAuth 2.0 client on AD FS.
   Description	An optional description of this OAuth 2.0 client.
   AD FS Server configuration
   Federation Service name	The FQDN which is used by clients to connect to AD FS. This is the name seen when Determining Federation Service Properties.
   Federation Service Identifier	The URL which identifies AD FS. This is the identifier seen when Determining Federation Service Properties.
   Resource Identifier	The URL which identifies the OAuth 2.0 resource on AD FS. This should be the identifier you gave the Relying Party Trust which you created earlier.
   Client ID	The ID of the AD FS OAuth 2.0 Client. This will show a randomly generated GUID which you may leave as is.
   AD FS Domains
   AD FS Domain: #1
   Domain	An FQDN which, when present in a user's email address, permits that user to authenticate using this AD FS OAuth 2.0 client. For example, if a user has the email bob@example.com, then example.com must be configured as a Domain to allow that user to sign on with AD FS. A single domain can only be used by a single AD FS 2.0 OAuth client, but the same domain can also be used by a Google OAuth 2.0 credential.
   Description	An optional description of the AD FS domain.

4. Select Save.

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. This command can be generated for you on the Pexip Infinity Management Node as follows:

1. From the Pexip Infinity Management Node, select the AD FS OAuth 2.0 client you just created.
2. From the bottom of the page, select Save and Get Setup Config.

3. On this page, copy the command in the Add-AdfsClient field.

   The command will look something like:

   Add-AdfsClient -Name "AD FS 2012" -ClientId "c5bddcf3-f3fd-48c0-acc4-6d1af4ddf434" -RedirectUri @("pexip-auth://adfs", "https://<Conference Node or Reverse Proxy>/api/client/v2/oauth2_redirect") -Description "AD FS Server for Connect clients"

   This uses the Name, Description and Client ID configured for this AD FS OAuth 2.0 Client.

   It also specifies two redirect URIs that may be used when provisioning the Infinity Connect clients. In the second URI you must replace <Conference Node or Reverse Proxy> with the actual address of either your Conferencing Node or your reverse proxy.

   Note that the pexip-auth://adfs is an alternative redirect URI that immediately redirects the user back to the app. This redirect method causes the AD FS sign-in page to remain open and thus may cause user confusion as it is not clear the user has successfully signed in. You can enter both types of redirect URI when configuring AD FS. The redirect URI that is actually used is the one that the Infinity Connect client is provisioned with.

   One of the Redirect URIs you enter here must match exactly the URI used when provisioning the Infinity Connect client.

4. On your AD FS server, open PowerShell and issue the above command.

5. You must also enable Refresh tokens for the Relying Party Trust. This is done using the following PowerShell command:

   Set-AdfsRelyingPartyTrust -TargetName “<Relying Party Trust Display Name>" -IssueOAuthRefreshTokensTo AllDevices

   Where <Relying Party Trust Display Name> is the Display name of the Relying Party Trust which was created earlier.

6. You can now test your connection. Return to the Pexip Infinity Management Node, select the AD FS client again and select Save and Test Connection. This will save your data and report success or failure details of this connection. See Troubleshooting for more information.

Other commands are also available from the AD FS Setup Config page:

• To verify the changes have been saved, use the Get-AdfsClient command.
• If you need to modify the client, use the Set-AdfsClient command.

For information about these and other relevant commands, see the following Microsoft documentation:

• Add-AdfsClient: https://docs.microsoft.com/en-us/powershell/module/adfs/add-adfsclient
• Set-AdfsClient: https://docs.microsoft.com/en-us/powershell/module/adfs/set-adfsclient
• Get-AdfsClient: https://docs.microsoft.com/en-us/powershell/module/adfs/get-adfsclient
• Enable-AdfsClient: https://docs.microsoft.com/en-us/powershell/module/adfs/enable-adfsclient
• Disable-AdfsClient: https://docs.microsoft.com/en-us/powershell/module/adfs/disable-adfsclient
• Set-AdfsRelyingPartyTrust: https://docs.microsoft.com/en-us/powershell/module/adfs/set-adfsrelyingpartytrust

Users should now be able to use AD FS services and their AD credentials to register their Infinity Connect clients to Pexip Infinity.