Sample Solutions and Client Libraries

The API Sample solution demonstrates how to make calls to the Sage API. It also references libraries that simplify the use of Sage authentication and abstract the complexity of making HTTP requests.

Name	Download File
API Sample solution	Download
API Client library	Download

We provide a sample application to help you get up and running quickly.
The solution file APISamples.sln contains two projects:

1. APISampleWebSite
2. APISampleWinFormsApp

For detailed setup instructions, refer to the Using the Samples guide.

---

SageID.PublicClient

Overview

The APISampleWinFormsApp demonstrates how to embed a Chromium browser using CefSharp in a simple WinForms application to authenticate users via Sage ID.

Step-by-Step Flow

1. CefSharp Initialisation

• The application starts in Main(), where CefWrapper.Init() is called.
• This sets up the CefSharp browser environment, including:
  • Locale settings (en-GB)
  • GPU acceleration disabled
  • A persistent cache path for storing cookies and tokens, unique to your application

2. Form Load and Authentication Trigger

• When the main form (Form1) loads, the Form1_Load event is triggered.
• This calls AuthenticationProviderFactory.GetProvider().Logon() to initiate the Sage ID login process.

3. Authentication Provider Setup

• AuthenticationProviderFactory.GetProvider() ensures a single static instance of the authentication provider is created.
• The provider is configured with:
  • Client ID (must be set by the developer)
  • Audience (e.g., s200ukipd/sage200)
  • Domain (id.sage.com)

4. User Authentication

• The Logon() method internally calls LogonInner() from Sage.IdentityProvider.SageID.dll. This method:
  • Attempts a silent login using cached tokens
  • If no valid token is found, it prompts the user to log in via the embedded browser
  • On success, the token is cached using the CefSharp CachePath

5. Silent Login on Subsequent Runs

• If a user has previously authenticated, you can call AuthenticationProviderFactory.GetProvider().GetToken() instead of Logon().
• This attempts a silent login using the cached refresh token:
  • If the token is expired or invalid, the user will be prompted to log in again

6. Deployment Considerations for CefSharp

To successfully deploy your application with CefSharp support, ensure the following components are included:

Required Assemblies

Include the following five assemblies alongside your application:

• CefSharp.dll
• CefSharp.WinForms.dll
• CefSharp.Core.dll
• CefSharp.Core.Runtime.dll
• Sage.Proxy.CefSharp.dll

These are essential for embedding and managing the Chromium browser within your WinForms application.

Redistributable Files

You must also include the CefSharp redistributable files, which contain the Chromium binaries and supporting resources.

• For the version shipped with this sample, the Dependencies folder includes:
  • cef.redist.x86 version 120.2.70

This version is provided for convenience. However, the application uses Sage.Proxy.CefSharp.dll, which abstracts the CefSharp implementation, allowing flexibility to upgrade or change the CefSharp version if needed.

Although this sample uses CefSharp, it is technically possible to use other embedded browser frameworks (e.g., WebView2) for authentication. These alternatives are not included or demonstrated in this sample.

---

SageID.ConfidentialClient

The SageID.ConfidentialClient.dll is no longer required. Instead, use Microsoft Owin classes, as demonstrated in the Website sample.

To use this approach:

1. Set two properties in the Website sample’s Startup class:
   • For Sage 200 (all versions):
     • clientID = "Enter your client ID here";
     • clientSecret = "Enter your client secret here";
   • These values are specific to your application. You must register to obtain your own unique Client ID and Client Secret.

By following these instructions and using the provided samples and client libraries, you can effectively interact with the Sage API and streamline the authentication process.

Additional Resources

Sage ID uses OpenID Connect and OAuth 2.0 to authenticate users and obtain authorisation to access protected resources.

For further examples and implementation guidance, see the Auth0 Quickstarts, which provide practical examples of integrating OAuth 2.0 authentication flows.