Oloid Passwordless SDK Usage Guide for Windows Developers

​

Prerequisites

​

Prerequisites

1. Download SDK and Sample Applications:
   • Log in to the Oloid tenant admin portal.
   • Navigate to the “Files” section.
   • Download the Oloid Passwordless SDK files and sample applications.
   • These files will provide you with the necessary components and examples to get started.
2. Ensure the Oloid Passwordless Service is installed and running on the target machine.
3. Obtain the API key for your application from the Oloid tenant admin portal.
4. Know the service URL for the Oloid Passwordless Service (typically net.pipe://localhost/OloidService).
5. Familiarize yourself with the sample applications provided to understand basic implementation patterns

​

Understanding Authentication Modes

1. Passive Mode:
   • Used for badge-only authentication.
   • Does not require a user interface.
   • Suitable for background authentication processes.
   • Example use case: Automatic login when an employee badges into their workstation.
2. Active Mode:
   • Used for all authentication use cases.
   • Launches the Oloid User Interface to capture credentials.
   • Supports various authentication methods: Badge, PIN, Face, NFC, etc.
   • Example use case: User-initiated login process requiring multiple factors.

​

Step 1: Install the SDK

Install-Package OloidPasswordlessSdk

​

Step 2: Initialize the OloidClient

using OloidPasswordlessSdk;

// ...

string serviceUrl = "net.pipe://localhost/OloidService";
string apiKey = "your-api-key-from-oloid-tenant-admin-portal";

OloidClient oloidClient = new OloidClient(serviceUrl, apiKey);

​

Step 3: Subscribe to Authentication Events

await oloidClient.SubscribeToAuthenticationEvents(HandleAuthentication, AuthenticationType.Passive);

await oloidClient.SubscribeToAuthenticationEvents(HandleAuthentication, AuthenticationType.Active);

​

Step 4: Implement the Authentication Handler

private void HandleAuthentication(object sender, AuthenticationEventArgs e)
{
    switch (e.Result.Status)
    {
        case AuthenticationStatus.Success:
            // Successful authentication
            AuthenticateUser(e.Result.Username, e.Result.Password, e.Result.OloidUserToken);
            UpdateUserProfile(e.Result.UserInfo);
            break;
        case AuthenticationStatus.Failed:
            ShowErrorMessage("Authentication failed. Please try again.");
            break;
        case AuthenticationStatus.UserBlocked:
            ShowErrorMessage("User account is blocked. Please contact support.");
            break;
        case AuthenticationStatus.UserInactive:
            ShowErrorMessage("User account is inactive. Please contact support.");
            break;
        case AuthenticationStatus.NoCredentialsFound:
            ShowErrorMessage("No credentials found. Please try again or contact support.");
            break;
    }
}

​

Step 5: Implement Authentication Logic

private void AuthenticateUser(string username, string password, string oloidUserToken)
{
    // Your authentication logic here
    if (ValidateCredentials(username, password))
    {
        SetAuthenticatedUser(username);
        StoreOloidUserToken(oloidUserToken);  // Store for future use if needed
        ShowMainWindow();
    }
    else
    {
        ShowErrorMessage("Authentication failed");
    }
}

​

Step 6: Handle User Information

private void UpdateUserProfile(UserInfo userInfo)
{
    if (userInfo != null)
    {
        CurrentUser.Id = userInfo.Id;
        CurrentUser.Name = userInfo.Name;
        CurrentUser.Email = userInfo.Email;
        CurrentUser.PrimaryId = userInfo.PrimaryId;
        // ... update other relevant fields
    }
}

​

Step 7: Request Authentication (Active Mode Only)

try
{
    await oloidClient.RequestAuthentication();
}
catch (OloidException ex)
{
    ShowErrorMessage($"Failed to request authentication: {ex.Message}");
}

​

Step 8: Using the Oloid User Token

private void UseOloidUserToken(string oloidUserToken)
{
    // Use the token for API calls or session management
    // Example: Attach to HTTP headers for API requests
    _httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", oloidUserToken);
}

​

Best Practices

1. Mode Selection: Choose Passive mode for badge-only scenarios where background authentication is sufficient. Use Active mode when you need user interaction or multiple authentication factors.
2. Security: Always handle authentication information and the Oloid User Token securely. Clear sensitive data from memory as soon as possible after use.
3. Error Handling: Implement robust error handling for all scenarios, including service unavailability and unexpected data.
4. User Experience: In Active mode, provide clear feedback to the user about the authentication process and any errors that occur.
5. Testing: Thoroughly test both Passive and Active authentication modes, including all possible authentication statuses.
6. Logging: Implement logging for troubleshooting, but ensure you’re not logging sensitive information like passwords or tokens.
7. Configuration: Consider allowing the authentication type to be configurable, so you can switch between Passive and Active modes without code changes.
8. Token Management: Securely store and manage the Oloid User Token. Use it for maintaining user sessions and accessing Oloid APIs when needed.