Using AD FS for client authentication

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.

    

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.

   

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 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 (WAP) you must also ensure they are Proxy Enabled.

   

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.
   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 Connect apps. 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 Connect app is provisioned with.

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

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