Exact Synergy Enterprise

How-to: Calling web services using federated identity

Introduction

This document describes how the web services can be called using the federated identity with Microsoft Visual Studio 2015 as an example, assuming Exact Synergy Enterprise is configured for the federated identity environment.

To call the web services, do the following:

• Set the parameters that are required to acquire the security token.
• Acquire the security token.
• Create the authentication provider object that will be used for the service authentication.
• Call the service. 

Description

1. Open Microsoft Visual Studio 2015.
2. Create a Microsoft Windows project called FIDWebServiceClient.
   
3. Go to the Solution explorer. Click the FIDWebServiceClient project, and then click References. Add the following:
   
   • Exact.Identity.dll — This is used to acquire the security token.
   • Exact.Services.Client.dll — This is used to call the web services.
             
4. The following dll files are required by Exact.Identity.dll. Make sure the following dll files are available for the application to run correctly.
• DotNetOpenAuth.dll
• Microsoft.IdentityModel.Clients.ActiveDirectory.dll
• Newtonsoft.Json.dll
• System.IdentityModel.Tokens.Jwt.dll
• System.IdentityModel.Tokens.ValidatingIssuerNameRegistry.dll
5. Define the fields in the FIDWebServiceClient screen.
• Parameters (to acquire token) section — This is the user credentials and parameters that are required to acquire the security token.
• Web services section — Type the relevant information at the URL, Entity name, and Batch size fields.
• Result section — The result of the entities will be displayed if the authentication is successful.
          
6. Add the following references to the project.
       
7. To acquire the security tokens, a set of authentication parameters must be assigned (for more information, see the Parameters section). Create the List<KeyValuePair<KeyName, string>> object and assign the identity provider's Connection, Authority, Client ID, Username, and Password to the object.
       
8. Create the IdentityConnectionMetadata object and set the parameters created in step 7. Create the IdentityConnectionManager with the IdentityConnectionMetadata object. Based on these parameters, IdentityConnectionManager will look for the correct identity provider that will be used to acquire the security token.
       
9. Assign the security token, service URL (for example, the format is http://localhost/Synergy/services), security token type, username, password, and web session behavior to the AuthenticationProvider object. These information are required to authenticate and access the service.
       
10. Call the entities service via ServiceCallFactory and pass in the AuthenticationProvider object, entity name, and batch size. ServiceCallFactory can be used to retrieve different available services, such as entity service, entities service, and action service.
         
11. The result is as follows:
        
12. The security token can expire based on the expiration setting that is configured in the identity provider's portal. The expiration date and time can be retrieved via the Expiration property in the TokenResult class. To acquire the refresh security token, call the AcquireAccessTokenByRefreshToken method from the IdentityConnectionManager class. You need to store the refresh security token somewhere in the memory, cache, or web session, and pass it back to the AcquireAccessTokenByRefreshToken method to acquire the new refresh security token.
        

Parameters

The following table displays the mandatory parameters for Microsoft Entra ID that are required to acquire the security token. For example, to acquire the Microsoft Entra ID token in the active connection mode, the following information from both the Mandatory parameters and Connection Mode: Active columns are required:

• Authority
• Resource
• Client ID
• Username
• Password