One moment please...
 
 
Exact Synergy Enterprise   
 

How-to: Synergy web service and Microsoft Entra ID - Connecting to a Synergy web service using Microsoft Entra ID

Introduction

This document describes how to connect to the Exact Synergy Enterprise web services using the Microsoft Entra ID for authentication. This document makes use of the OAuth protocol (SAML is not covered in this document, but works in a similar way). Together with this document, you will find an example in SoapUI.

Note:

  • This document is not a tutorial on how to set up Exact Synergy Enterprise and Microsoft Entra ID.
  • This document is not a detailed explanation of the authentication protocols used by Microsoft Entra ID.

Prerequisites

For the examples in this document, you will need the following:

  • A Microsoft Entra ID account,
  • a configured Microsoft Entra ID,
  • Synergy Enterprise, configured using Microsoft Entra ID with OAuth,
  • credentials of a Synergy user and administrator access to the Microsoft Entra ID, and
  • SoapUI.

Authentication process

Traditionally, Exact Synergy Enterprise supports Windows authentication (NTLM credentials) and Basic authentication (username and password). Recently, Exact Synergy Enterprise also supports Microsoft Entra ID in combination with the SAML or OAuth protocol.

For detailed information about the OAuth protocol used by Microsoft Entra ID, see https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-app-types.

Authentication process flow in a browser

When you log in to Exact Synergy Enterprise in a browser, you get redirected to a Microsoft Entra ID login page. On this page, you enter your credentials (username and password) and after a successful authentication, you will be redirected back to Exact Synergy Enterprise. 

Please note that this is an interactive authentication flow, and as such, the user must key in their credentials manually.

Authentication process flow in an App

When using an App, you have a similar flow as a browser. 

Please note that this is also an interactive authentication flow.

Authentication process flow for a server process

When you want to call the Exact Synergy Enterprise web services from a server process, you cannot use one of the authentication flows described above. You will need an authentication flow that does not require any user interaction. For this you can use the “resource owner password credential grant” flow.

This flow uses a combination of username, password, and client secret to get authentication. This flow does not use any user interaction, because only the owner of the Microsoft Entra ID can provide the client secret. The rest of the document will explain how to use this flow to successfully call an Exact Synergy Enterprise web service.

Note: Please be aware that the client secret must be kept secret for everyone. It is not something that should be shared with users or other parties.

Example

The call to an Exact Synergy Enterprise web service requires two steps:

  1. Retrieve a Microsoft Entra ID access token using OAuth.
  2. Call the Exact Synergy Enterprise web service and provide the access token.

Retrieve an access token

To retrieve an access token, you need the following information:

  • The Microsoft Entra ID endpoints.
  • Username and password of an Exact Synergy Enterprise user in Microsoft Entra ID.
  • The client ID of the Exact Synergy Enterprise instance in Microsoft Entra ID.
  • The client secret of the Exact Synergy Enterprise instance in Microsoft Entra ID.

Endpoints

You can find the endpoints by clicking Endpoints in the Microsoft Entra ID portal, via Default Directory > App registrations.

Username and password

You can find the users via Default Directory > Users - All users.

Client ID

The client ID uniquely identifies your application. You can find those at Default Directory > App registrations. For Exact Synergy Enterprise, you have configured two App registrations:

  1. Web Registration
  2. Public Registration

You will need the client ID from the web registration:

Client secret

Note: Be aware that the client secret must remain SECRET – never provide it to others!

The client secret can be found via the web application registration at Default Directory > App registrations XXXXXXXXX_ESE_WEB > Certificates & secrets.

Please note that when you create a client secret, the complete secret is displayed to you. You must write this down because you will not be able to retrieve it at a later moment.

Get the token

With all information above, you can retrieve the token by sending a POST message to the OAuth 2.0 token endpoint (v1). In the message content, you need to provide the client ID, client secret, username, and password. Please be aware that the values must be URL encoded.

client_id=58xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx81
&resource=58xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx81
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&username=WAAD@xxxxxxxxxxxxxxxx.onmicrosoft.com
&password=xxxxxxxxxxxxxxxx
&client_secret=1xx%1Cxxx%9AxxxxxxxxxxxxxxxxxxxxxxxxxxxxxU
&grant_type=password

The content-type header must be set to application/x-www-form-urlencoded.

This call returns a JSON message with the access token

{
      "token_type": "Bearer",
      "scope": "User.Read",
      "expires_in": "3600",
      "ext_expires_in": "3600",
      "expires_on": "1567169792",
      "not_before": "1567165892",
      "resource": "58xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx81",
      "access_token": "eyJ0...
                                                      ...QIA",
      "refresh_token": "AQAB...
                                                       ...IAA"
}

This access token will be used to authenticate with the Exact Synergy Enterprise web service (see next section).

Call a webservice

With the access token you have retrieved from the token endpoint of the Micrsoft Entra ID, you can now call an Exact Synergy Enterprise web service. In the example, we will retrieve a call to the Account web services.

Instead of providing the NTLM credentials, you now need to provide the Microsoft Entra ID access token. This is done via two HTTP headers:

  1. AccessTokenType
  2. AccessToken

AccessTokenType must be set to OAUTH and AccessToken must contain your access token. Please be aware that you should not provide any other authentication or authorisation.

GET http://localhost/ese/services/Exact.entity.REST.svc/Account?%24top=10 HTTP/1.1
Accept-Encoding: gzip,deflate
Accept: application/json,text/javascript; charset=utf-8
AccessToken: eyJ0 ... QIA
AccessTokenType: OAUTH
Content-Type: application/json
Host: localhost
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

SoapUI

For the complete SoapUI example, see this file WAAD-soapui-project.xml.

     
 Main Category: Attachments & notes  Document Type: Online help main
 Category:  Security  level: All - 0
 Sub category:  Document ID: 29.165.364
 Assortment: Exact Synergy Enterprise  Date: 30-07-2024
 Release:  Attachment:
 Disclaimer

Attachments
WAAD-soapui-project.xml 6.9 KB View Download