workspace sdk logon providers

About logon providers

Logon providers customize how operators log on to Security Center client applications. They replace the default logon mechanism with a custom authentication flow, enabling integration with external identity systems.

Use logon providers when operators need to authenticate through a mechanism that Security Center does not natively support. Examples include:

• Authenticating with a smart card or hardware security token.
• Integrating with a corporate single sign-on (SSO) system.
• Implementing multi-factor authentication using a third-party service.

How logon providers work

1. The module registers a LogonProvider with the workspace during Load.
2. The system selects the provider with the highest Priority value.
3. When the logon dialog appears, the system calls LogOn() on the provider.
4. The provider collects credentials from a UI, hardware, or an external system and calls LogOnAsync() with a LogonInfo object.
5. The provider raises the Connecting event to indicate authentication is in progress.
6. LogOnAsync() returns a ConnectionStateCode indicating success or the reason for failure.
7. If the application enters idle mode due to inactivity, the system calls LogOn() again. Check IsIdleMode to handle reconnection differently.

LogonProvider

Inherit from LogonProvider and implement the required members Name, UniqueId, and LogOn:

public class MyLogonProvider : LogonProvider
{
    public override string Name => "My Logon Provider";

    public override Guid UniqueId => new Guid("A1B2C3D4-E5F6-7890-ABCD-EF1234567890");

    public override async void LogOn()
    {
        var logonInfo = new LogonInfo(m_server, m_username, m_password);

        var result = await LogOnAsync(logonInfo);

        if (result != ConnectionStateCode.Success)
        {
            // Handle logon failure
        }
    }
}

LogonProvider members

Member	Type	Description
Name	Property (abstract)	The logon provider's display name.
UniqueId	Property (abstract)	A stable GUID that uniquely identifies this logon provider.
ConfigurationName	Property (virtual)	The logon provider configuration name. Defaults to null.
IsIdleMode	Property	Whether the application is in idle mode due to operator inactivity.
Priority	Property (virtual)	Provider priority. Higher values take precedence. Defaults to 0.
LogOn()	Method (abstract)	Implement the logon mechanism. Collect credentials and call LogOnAsync with a LogonInfo object.
LogOnAsync(LogonInfo, CancellationToken)	Method (protected)	Perform the logon operation. Returns a ConnectionStateCode indicating the result.

Events

Event	Description
Canceled	Raised when the operator cancels the logon operation.
Connecting	Raised when the logon operation is in progress.

LogonInfo

LogonInfo provides the credentials for a logon operation.

Constructors

Create a LogonInfo with the server address and credentials:

// Log on with username and password
var info = new LogonInfo("server-address", "username", "password");

// Log on with a certificate
var info = new LogonInfo("server-address", "username", certificate);

// Log on with current Windows credentials
var info = new LogonInfo("server-address");

LogonInfo properties

Member	Type	Description
Server	string	The server address for the connection.
Username	string	The username for authentication.
Password	string	The password for authentication.
Certificate	X509Certificate2	The certificate for authentication.
UseWindowsCredentials	bool	Whether to log on using the current Windows credentials.
RetryCount	int	Number of connection retries. Defaults to -1 (no retry limit).
SupervisorName	string	The supervisor's username for supervised operations.
SupervisorPassword	string	The supervisor's password for supervised operations.

ConnectionStateCode

The LogOnAsync method returns a ConnectionStateCode indicating the result:

Value	Description
Success	Connection was successful.
InvalidCredential	Invalid credentials were provided.
InsufficientPrivileges	The operator does not have sufficient privileges.
Timeout	The connection timed out.
LicenseError	A license error prevented the connection.
PasswordExpired	The password has expired.
UserAccountDisabledOrLocked	The operator account is disabled or locked.
LogonAborted	The operator aborted the logon.
Failed	The connection failed.

Registering a logon provider

Note

Logon providers do not require an SDK certificate.

Register the provider in your module's Load method:

public class SampleModule : Module
{
    private MyLogonProvider m_logonProvider;

    public override void Load()
    {
        m_logonProvider = new MyLogonProvider();
        m_logonProvider.Initialize(Workspace);
        Workspace.Components.Register(m_logonProvider);
    }

    public override void Unload()
    {
        if (m_logonProvider != null)
        {
            Workspace.Components.Unregister(m_logonProvider);
            m_logonProvider.Dispose();
        }
    }
}

Important

LogonProvider implements IDisposable. Call Dispose when unregistering the provider to release resources.

See also

• About the Workspace SDK: Workspace SDK architecture and module lifecycle.
• About components: The component registry and registration lifecycle.
• About Workspace SDK certificates: Certificate requirements for workspace components.
• About workspace modules: Workspace module class and Load/Unload lifecycle.