WebAuthn Component

Properties   Methods   Events   Config Settings   Errors  

TBD.

Syntax

nsoftware.CloudSSO.WebAuthn

Remarks

The CreateNewCredential, VerifyNewCredential, NewCredentialRequest, and NewCredentialCompleted are used at registration.

The GetAssertionOptions, MakeAssertion, AssertionRequest, and AssertionCompleted are used at authentication.

TBD.

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

ExistingCredentialsTBD.
PublicKeyAlgorithmsTBD.
RpIdTBD.
RpNameTBD.
TimeoutTBD.
UserDisplayNameTBD.
UserNameTBD.
UserVerificationTBD.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

AddExistingCredentialTBD.
ConfigSets or retrieves a configuration setting.
CreateNewCredentialTBD.
GetAssertionOptionsTBD.
MakeAssertionTBD.
ResetResets the component properties.
VerifyNewCredentialTBD.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

AssertionCompletedTBD.
AssertionRequestTBD.
ErrorFired when information is available about errors during data delivery.
LogThis event fires once for each log message.
NewCredentialCompletedTBD.
NewCredentialRequestTBD.

Config Settings

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

BuildInfoInformation about the product's build.
GUIAvailableWhether or not a message loop is available for processing events.
LicenseInfoInformation about the current license.
MaskSensitiveDataWhether sensitive data is masked in log messages.
UseInternalSecurityAPIWhether or not to use the system security libraries or an internal implementation.

ExistingCredentials Property (WebAuthn Component)

TBD.

Syntax

public WACredentialList ExistingCredentials { get; }

Public ReadOnly Property ExistingCredentials As WACredentialList

Remarks

The user can populate this collection with AddExistingCredential.

1. The CreateNewCredential method uses this collection to generate the excludeCredentails of https://w3c.github.io/webauthn/#dictionary-makecredentialoptions.

2. The VerifyNewCredential method uses this collection to verify the new credential id is unique.

3. The GetAssertionOptions method uses this collection to generate the allowCredentials of https://w3c.github.io/webauthn/#dictionary-assertion-options.

4. The MakeAssertion method uses this collection to verify the existence of the new credential id that has been created.

TBD.

This property is read-only and not available at design time.

Please refer to the WACredential type for a complete list of fields.

PublicKeyAlgorithms Property (WebAuthn Component)

TBD.

Syntax

public string PublicKeyAlgorithms { get; set; }

Public Property PublicKeyAlgorithms As String

Default Value

"ES256,RS256"

Remarks

This is an ordered list of acceptable algorithms for the key. A numeric identifier for the algorithm to be used to generate the key pair. The links between identifier and algorithms are defined in https://www.iana.org/assignments/cose/cose.xhtml#algorithms. The value of ES256 is -7. The value of RS256 is -257.

Though those elements are sorted by preference (the first element being the most preferred), it is up to the client to choose among those elements for building the credential.

TBD.

RpId Property (WebAuthn Component)

TBD.

Syntax

public string RpId { get; set; }

Public Property RpId As String

Default Value

""

Remarks

https://w3c.github.io/webauthn/#dictionary-rp-credential-params.

It is a valid domain string identifying the WebAuthn Relying Party.

TBD.

RpName Property (WebAuthn Component)

TBD.

Syntax

public string RpName { get; set; }

Public Property RpName As String

Default Value

""

Remarks

https://w3c.github.io/webauthn/#dictionary-pkcredentialentity

Is is a human-palatable identifier for the Relying Party, intended only for display. For example, "ACME Corporation", "Wonderful Widgets, Inc.".

TBD.

Timeout Property (WebAuthn Component)

TBD.

Syntax

public int Timeout { get; set; }

Public Property Timeout As Integer

Default Value

60

Remarks

Make it in seconds. When sent to the client, convert it to milliseconds.

The timeout property, of the PublicKeyCredentialCreationOptions dictionary, represents an hint, given in milliseconds, for the time the script is willing to wait for the completion of the creation operation. This property is optional and merely is a hint which may be overridden by the browser.

TBD.

UserDisplayName Property (WebAuthn Component)

TBD.

Syntax

public string UserDisplayName { get; set; }

Public Property UserDisplayName As String

Default Value

""

Remarks

https://w3c.github.io/webauthn/#dictionary-user-credential-params.

A human-palatable name for the user account, intended only for display.

TBD.

UserName Property (WebAuthn Component)

TBD.

Syntax

public string UserName { get; set; }

Public Property UserName As String

Default Value

""

Remarks

https://w3c.github.io/webauthn/#dictionary-pkcredentialentity.

It is a human-palatable identifier for a user account. Examples of suitable values for this identifier include, "alexm", "+14255551234", "alex.mueller@example.com", "alex.mueller@example.com (prod-env)".

The CreateNewCredential can parse input registration client data to populate this property or the GetAssertionOptions can parse input authentication client data to populate this property.

TBD.

UserVerification Property (WebAuthn Component)

TBD.

Syntax

public string UserVerification { get; set; }

Public Property UserVerification As String

Default Value

"preferred"

Remarks

https://w3c.github.io/webauthn/#enum-userVerificationRequirement.

Values: "required", "preferred", "discouraged"

Default value: "preferred"

TBD.

AddExistingCredential Method (WebAuthn Component)

TBD.

Syntax

public void AddExistingCredential(byte[] credentialId, string publicKey, int signCount, string algorithm);

Async Version
public async Task AddExistingCredential(byte[] credentialId, string publicKey, int signCount, string algorithm);
public async Task AddExistingCredential(byte[] credentialId, string publicKey, int signCount, string algorithm, CancellationToken cancellationToken);

Public Sub AddExistingCredential(ByVal credentialId As String, ByVal publicKey As String, ByVal signCount As Integer, ByVal algorithm As String)

Async Version
Public Sub AddExistingCredential(ByVal credentialId As String, ByVal publicKey As String, ByVal signCount As Integer, ByVal algorithm As String) As Task
Public Sub AddExistingCredential(ByVal credentialId As String, ByVal publicKey As String, ByVal signCount As Integer, ByVal algorithm As String, cancellationToken As CancellationToken) As Task

Remarks

When NewCredentialRequest is fired, user can call this method to add excluding credentials to the ExistingCredentials collection.

When AssertionRequest is fired, user can call this method to add allowing credentials to the ExistingCredentials collection.

TBD.

Config Method (WebAuthn Component)

Sets or retrieves a configuration setting.

Syntax

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);

Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

CreateNewCredential Method (WebAuthn Component)

TBD.

Syntax

public string CreateNewCredential(string data);

Async Version
public async Task<string> CreateNewCredential(string data);
public async Task<string> CreateNewCredential(string data, CancellationToken cancellationToken);

Public Function CreateNewCredential(ByVal data As String) As String

Async Version
Public Function CreateNewCredential(ByVal data As String) As Task(Of String)
Public Function CreateNewCredential(ByVal data As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

1. This method parse client registration data.

2. Fire NewCredentialRequest event, let user call AddExistingCredential method to add all user-related credentials to the ExistingCredentials.

3. Generate json format response. Example: {"rp":{"id":"fido2-net-lib.passwordless.dev","name":"WebAuthn Test"},"user":{"name":"testName","id":"QnjZC2XuY0uWDJ4CbkKV-PT9jT8peFVIVSr9xx70tJU","displayName":"testDisplayName"},"challenge":"U02lnAqw67nokWiFr_Hj2w","pubKeyCredParams":[{"type":"public-key","alg":"-7"},{"type":"public-key","alg":"-257"}],"timeout":60000,"attestation":"none","authenticatorSelection":{"userVerification":"preferred"},"excludeCredentials":[],"extensions":{}}

TBD.

GetAssertionOptions Method (WebAuthn Component)

TBD.

Syntax

public string GetAssertionOptions(string data);

Async Version
public async Task<string> GetAssertionOptions(string data);
public async Task<string> GetAssertionOptions(string data, CancellationToken cancellationToken);

Public Function GetAssertionOptions(ByVal data As String) As String

Async Version
Public Function GetAssertionOptions(ByVal data As String) As Task(Of String)
Public Function GetAssertionOptions(ByVal data As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

1. This method parse client authentication data.

2. Fire AssertionRequest event, let user call AddExistingCredential method to add all user-related credentials to the ExistingCredentials.

3. Generate json format response. Example: {"rpId":"fido2-net-lib.passwordless.dev","challenge":"qs2oz6qkWqFCVJw72ixFvg","timeout":60000,"userVerification":"preferred","allowCredentials":[{"id":"LrPbJZFbkNgSYft8vVzHRpICDq7MeK8hHTEaKZYR3EY","type":"public-key"}],"extensions":{}}

TBD.

MakeAssertion Method (WebAuthn Component)

TBD.

Syntax

public void MakeAssertion(string data);

Async Version
public async Task MakeAssertion(string data);
public async Task MakeAssertion(string data, CancellationToken cancellationToken);

Public Sub MakeAssertion(ByVal data As String)

Async Version
Public Sub MakeAssertion(ByVal data As String) As Task
Public Sub MakeAssertion(ByVal data As String, cancellationToken As CancellationToken) As Task

Remarks

1. This method verify the assertion according to https://w3c.github.io/webauthn/#sctn-verifying-assertion.

2. After verification, fire AssertionCompleted expose credentialId, signCount, UvInitialized.

TBD.

Reset Method (WebAuthn Component)

Resets the component properties.

Syntax

public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);

Public Sub Reset()

Async Version
Public Sub Reset() As Task
Public Sub Reset(cancellationToken As CancellationToken) As Task

Remarks

This method resets all message and key properties to their default values.

VerifyNewCredential Method (WebAuthn Component)

TBD.

Syntax

public void VerifyNewCredential(string data);

Async Version
public async Task VerifyNewCredential(string data);
public async Task VerifyNewCredential(string data, CancellationToken cancellationToken);

Public Sub VerifyNewCredential(ByVal data As String)

Async Version
Public Sub VerifyNewCredential(ByVal data As String) As Task
Public Sub VerifyNewCredential(ByVal data As String, cancellationToken As CancellationToken) As Task

Remarks

1. This method verify the new credential according to https://w3c.github.io/webauthn/#sctn-registering-a-new-credential.

2. After verification, fire NewCredentialCompleted expose credentialId, publicKey, signCount, UvInitialized, COSE algorithm, userName.

TBD.

AssertionCompleted Event (WebAuthn Component)

TBD.

Syntax

public event OnAssertionCompletedHandler OnAssertionCompleted;

public delegate void OnAssertionCompletedHandler(object sender, WebAuthnAssertionCompletedEventArgs e);

public class WebAuthnAssertionCompletedEventArgs : EventArgs {
  public string CredentialId { get; }
  public byte[] CredentialIdB { get; }
  public int SignCount { get; }
  public bool UvInitialized { get; }
}

Public Event OnAssertionCompleted As OnAssertionCompletedHandler

Public Delegate Sub OnAssertionCompletedHandler(sender As Object, e As WebAuthnAssertionCompletedEventArgs)

Public Class WebAuthnAssertionCompletedEventArgs Inherits EventArgs
  Public ReadOnly Property CredentialId As String
  Public ReadOnly Property CredentialIdB As Byte()
  Public ReadOnly Property SignCount As Integer
  Public ReadOnly Property UvInitialized As Boolean
End Class

Remarks

TBD.

AssertionRequest Event (WebAuthn Component)

TBD.

Syntax

public event OnAssertionRequestHandler OnAssertionRequest;

public delegate void OnAssertionRequestHandler(object sender, WebAuthnAssertionRequestEventArgs e);

public class WebAuthnAssertionRequestEventArgs : EventArgs {
  public string UserName { get; }
}

Public Event OnAssertionRequest As OnAssertionRequestHandler

Public Delegate Sub OnAssertionRequestHandler(sender As Object, e As WebAuthnAssertionRequestEventArgs)

Public Class WebAuthnAssertionRequestEventArgs Inherits EventArgs
  Public ReadOnly Property UserName As String
End Class

Remarks

TBD.

Error Event (WebAuthn Component)

Fired when information is available about errors during data delivery.

Syntax

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, WebAuthnErrorEventArgs e);

public class WebAuthnErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As WebAuthnErrorEventArgs)

Public Class WebAuthnErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component throws an exception.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Log Event (WebAuthn Component)

This event fires once for each log message.

Syntax

public event OnLogHandler OnLog;

public delegate void OnLogHandler(object sender, WebAuthnLogEventArgs e);

public class WebAuthnLogEventArgs : EventArgs {
  public int LogLevel { get; }
  public string Message { get; }
  public string LogType { get; }
}

Public Event OnLog As OnLogHandler

Public Delegate Sub OnLogHandler(sender As Object, e As WebAuthnLogEventArgs)

Public Class WebAuthnLogEventArgs Inherits EventArgs
  Public ReadOnly Property LogLevel As Integer
  Public ReadOnly Property Message As String
  Public ReadOnly Property LogType As String
End Class

Remarks

This event fires once for each log message generated by the component. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the level of message. Possible values are as follows:

0 (None) No events are logged.
1 (Info - default) Informational events are logged.
2 (Verbose) Detailed data are logged.
3 (Debug) Debug data are logged.

The value 1 (Info) logs basic information, including the URL, HTTP version, and status details.

The value 2 (Verbose) logs additional information about the request and response.

The value 3 (Debug) logs the headers and body for both the request and response, as well as additional debug information (if any).

Message is the log entry.

LogType identifies the type of log entry. Possible values are as follows:

  • "Info"
  • "RequestHeaders"
  • "ResponseHeaders"
  • "RequestBody"
  • "ResponseBody"
  • "ProxyRequest"
  • "ProxyResponse"
  • "FirewallRequest"
  • "FirewallResponse"

NewCredentialCompleted Event (WebAuthn Component)

TBD.

Syntax

public event OnNewCredentialCompletedHandler OnNewCredentialCompleted;

public delegate void OnNewCredentialCompletedHandler(object sender, WebAuthnNewCredentialCompletedEventArgs e);

public class WebAuthnNewCredentialCompletedEventArgs : EventArgs {
  public string CredentialId { get; }
  public byte[] CredentialIdB { get; }
  public string UserName { get; }
  public string PublicKey { get; }
  public int SignCount { get; }
  public bool UvInitialized { get; }
  public string Algorithm { get; }
}

Public Event OnNewCredentialCompleted As OnNewCredentialCompletedHandler

Public Delegate Sub OnNewCredentialCompletedHandler(sender As Object, e As WebAuthnNewCredentialCompletedEventArgs)

Public Class WebAuthnNewCredentialCompletedEventArgs Inherits EventArgs
  Public ReadOnly Property CredentialId As String
  Public ReadOnly Property CredentialIdB As Byte()
  Public ReadOnly Property UserName As String
  Public ReadOnly Property PublicKey As String
  Public ReadOnly Property SignCount As Integer
  Public ReadOnly Property UvInitialized As Boolean
  Public ReadOnly Property Algorithm As String
End Class

Remarks

TBD.

NewCredentialRequest Event (WebAuthn Component)

TBD.

Syntax

public event OnNewCredentialRequestHandler OnNewCredentialRequest;

public delegate void OnNewCredentialRequestHandler(object sender, WebAuthnNewCredentialRequestEventArgs e);

public class WebAuthnNewCredentialRequestEventArgs : EventArgs {
  public string UserName { get; }
  public string DisplayName { get; }
  public string Attestation { get; }
  public string UserVerification { get; }
}

Public Event OnNewCredentialRequest As OnNewCredentialRequestHandler

Public Delegate Sub OnNewCredentialRequestHandler(sender As Object, e As WebAuthnNewCredentialRequestEventArgs)

Public Class WebAuthnNewCredentialRequestEventArgs Inherits EventArgs
  Public ReadOnly Property UserName As String
  Public ReadOnly Property DisplayName As String
  Public ReadOnly Property Attestation As String
  Public ReadOnly Property UserVerification As String
End Class

Remarks

TBD.

WACredential Type

TBD.

Remarks

TBD.

The following fields are available:
  • Id
  • PublicKey
  • SignAlgorithm
  • SignCount

    • Fields

    Id
    string
    Default: ""

    TBD.

    IdB
    byte []
    Default: ""

    TBD.

    PublicKey
    string
    Default: ""

    TBD.

    SignAlgorithm
    string
    Default: "0"

    TBD.

    SignCount
    int
    Default: 0

    TBD.

    Constructors

    public WACredential();

    Public WACredential()

    Config Settings (WebAuthn Component)

    The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

    Base Config Settings

    BuildInfo:   Information about the product's build.

    When queried, this setting will return a string containing information about the product's build.

    GUIAvailable:   Whether or not a message loop is available for processing events.

    In a GUI-based application, long-running blocking operations may cause the application to stop responding to input until the operation returns. The component will attempt to discover whether or not the application has a message loop and, if one is discovered, it will process events in that message loop during any such blocking operation.

    In some non-GUI applications, an invalid message loop may be discovered that will result in errant behavior. In these cases, setting GUIAvailable to false will ensure that the component does not attempt to process external events.

    LicenseInfo:   Information about the current license.

    When queried, this setting will return a string containing information about the license this instance of a component is using. It will return the following information:

    • Product: The product the license is for.
    • Product Key: The key the license was generated from.
    • License Source: Where the license was found (e.g., RuntimeLicense, License File).
    • License Type: The type of license installed (e.g., Royalty Free, Single Server).
    • Last Valid Build: The last valid build number for which the license will work.
    MaskSensitiveData:   Whether sensitive data is masked in log messages.

    In certain circumstances it may be beneficial to mask sensitive data, like passwords, in log messages. Set this to true to mask sensitive data. The default is true.

    This setting only works on these components: AS3Receiver, AS3Sender, Atom, Client(3DS), FTP, FTPServer, IMAP, OFTPClient, SSHClient, SCP, Server(3DS), Sexec, SFTP, SFTPServer, SSHServer, TCPClient, TCPServer.

    UseInternalSecurityAPI:   Whether or not to use the system security libraries or an internal implementation.

    When set to false, the component will use the system security libraries by default to perform cryptographic functions where applicable. In this case, calls to unmanaged code will be made. In certain environments, this is not desirable. To use a completely managed security implementation, set this setting to true.

    Setting this configuration setting to true tells the component to use the internal implementation instead of using the system security libraries.

    On Windows, this setting is set to false by default. On Linux/macOS, this setting is set to true by default.

    If using the .NET Standard Library, this setting will be true on all platforms. The .NET Standard library does not support using the system security libraries.

    Note: This setting is static. The value set is applicable to all components used in the application.

    When this value is set, the product's system dynamic link library (DLL) is no longer required as a reference, as all unmanaged code is stored in that file.

    Trappable Errors (WebAuthn Component)