---
title: TokenProvider
summary: API reference for TokenProvider.
status: draft
owner: <owner>
last_reviewed: 2026-07-23
library: SAIF.Framework.SecurityModule
reference_type: package
---

# TokenProvider

`TokenProvider` is a `Friend`-scoped (assembly-internal) class that wraps the Win32 `LogonUser`/`DuplicateToken`/`CloseHandle` P/Invoke calls to exchange a username and password for a duplicated Windows logon token, used exclusively by `CookieAuthenticator` within this library.

## Purpose
- Perform a Windows domain/local logon (`LOGON32_LOGON_INTERACTIVE`) for a decrypted username/password pair and return a usable token handle.
- Encapsulate the Win32 P/Invoke surface (`advapi32.dll`, `Kernel32.dll`) so callers within the assembly do not interact with unmanaged APIs directly.

## Context
- Namespace: `SAIF.Framework.SecurityModule`
- Assembly/package: `SAIF.Framework.SecurityModule` (packaged inside the `SAIF.BOF.Framework` NuGet package)

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| `GetToken` | `Friend Shared Function GetToken(username As String, password As String) As IntPtr` | Calls `LogonUser` via `LogonWindowsDomainUser`, duplicates the resulting token (`DuplicateToken`), closes the original handle, and returns the duplicated token. Throws `Exception("Unable to login")` on failure (see [BR-004](../../business-rules.md#br-004-a-failed-windows-logon-is-treated-as-an-authentication-failure)). Carries a method-level `SecurityPermissionAttribute(SecurityAction.Assert, ControlPrincipal:=True, UnmanagedCode:=True)`. |
| `ReleaseToken` | `Friend Shared Sub ReleaseToken(token As IntPtr)` | Closes the given token handle via `CloseHandle`. |

Private supporting members (listed for architectural completeness, not externally callable):
- `LogonUser` (`DllImport("advapi32.dll")`) — raw Win32 logon P/Invoke declaration.
- `GetLastError`, `CloseHandle` (`DllImport("Kernel32.dll")`) — Win32 error/handle-management P/Invoke declarations.
- `DuplicateToken` (`Declare Auto ... Lib "advapi32.dll"`) — duplicates a token handle to a new security token type.
- `LogonWindowsDomainUser(username, password, ByRef uHandle) As Boolean` — invokes `LogonUser` with the `sec-logindomain` app setting as the domain and `LOGON32_LOGON_INTERACTIVE`/`LOGON32_PROVIDER_DEFAULT` constants; logs a warning on failure.

## Behavioral notes
- Because all members are `Friend` (assembly-internal) or `Private`, this type is only usable from within `SAIF.Framework.SecurityModule` itself — currently only `CookieAuthenticator.Authenticate` calls `GetToken`/`ReleaseToken`.
- The domain used for logon comes from the `sec-logindomain` `AppSettings` key with no code-level default; if unset, the value passed to `LogonUser` is empty/null.*
- A code comment notes the token duplication step is needed "to resolve framework 1.0 errors" and states the problem does not exist in framework 1.1, suggesting this workaround may be a legacy compatibility artifact.*

## Constraints and usage notes
- All public/friend members are `Shared`; the class is not intended to be instantiated.
- `GetToken` callers must ensure `ReleaseToken` is invoked (typically in a `Finally` block, as done by `CookieAuthenticator`) to avoid leaking the Windows token handle.

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts.

## Sources
- `SAIF.Framework.SecurityModule\TokenProvider.vb`