Sample Solutions and Client Libraries
Less than to read
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:
APISampleWebSite
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()
, whereCefWrapper.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
- Locale settings (
2. Form Load and Authentication Trigger
- When the main form (
Form1
) loads, theForm1_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 callsLogonInner()
fromSage.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 ofLogon()
. - 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
version120.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:
- 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.
- For Sage 200 (all versions):
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.