Prerequisites
Prerequisites
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.
Ensure the Oloid Passwordless Service is installed and running on the target machine.
Obtain the API key for your application from the Oloid tenant admin portal.
Know the service URL for the Oloid Passwordless Service (typically
net.pipe://localhost/OloidService).Familiarize yourself with the sample applications provided to understand basic implementation patterns
Understanding Authentication Modes
The Oloid Passwordless SDK supports two authentication modes:
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.
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
Add the Oloid Passwordless SDK to your project via NuGet Package Manager or by including the SDK source files directly.
Install-Package OloidPasswordlessSdk
Step 2: Initialize the OloidClient
Create an instance of 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
Subscribe to authentication events, specifying the authentication type:
For Passive (badge-only) authentication:
await oloidClient.SubscribeToAuthenticationEvents(HandleAuthentication, AuthenticationType.Passive);
For Active authentication:
await oloidClient.SubscribeToAuthenticationEvents(HandleAuthentication, AuthenticationType.Active);
Step 4: Implement the Authentication Handler
Create a method to handle authentication events:
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
Implement the AuthenticateUser method according to your application's authentication system:
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
Update user profile with information provided by Oloid:
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)
To prompt the user for authentication in Active mode:
try
{
await oloidClient.RequestAuthentication();
}
catch (OloidException ex)
{
ShowErrorMessage($"Failed to request authentication: {ex.Message}");
}
Step 8: Using the Oloid User Token
The Oloid User Token contains user claims such as email ID and primary ID. You can use this token for subsequent API calls or to maintain user session:
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
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.
Security: Always handle authentication information and the Oloid User Token securely. Clear sensitive data from memory as soon as possible after use.
Error Handling: Implement robust error handling for all scenarios, including service unavailability and unexpected data.
User Experience: In Active mode, provide clear feedback to the user about the authentication process and any errors that occur.
Testing: Thoroughly test both Passive and Active authentication modes, including all possible authentication statuses.
Logging: Implement logging for troubleshooting, but ensure you're not logging sensitive information like passwords or tokens.
Configuration: Consider allowing the authentication type to be configurable, so you can switch between Passive and Active modes without code changes.
Token Management: Securely store and manage the Oloid User Token. Use it for maintaining user sessions and accessing Oloid APIs when needed.