Class

WebUserAuthentication

Passkeys

Authentication

TouchID

FaceID

Description

A control that can be dropped on to any WebPage or WebContainer, to initiate and handle the Passkey (WebAuthn) registration and authentication processes.

Properties

Name	Type	Read-Only
ApplicationName	String
ControlID	String	✓
Domain	String
Enabled	Boolean
Name	String	✓
Page	WebPage	✓
PanelIndex	Integer
Parent	WebView	✓
Timeout	Integer

Methods

Name	Parameters	Returns	Shared
Authenticate	Optional allowCredentials() As String
Close
ExecuteJavaScript	script As String
GoToURL	url As String, inNewWindow As Boolean = False
Register	userId As String, username As String = ", displayName As String = "
UpdateBrowser

Events

Name	Parameters	Returns
AuthenticationSucceeded	userId As String, credentialId As String, authenticationAttempts As Integer
Closed
CredentialRequested	userId As String, credentialId As String	WebAuthenticationCredential
Error	message As String
Opening
RegistrationSucceeded	userId As String, credential As WebAuthenticationCredential

Property descriptions

WebUserAuthentication.ApplicationName

ApplicationName As String

Displayed by some authenticators. This helps the user confirm they are accessing the app they think they are accessing.

WebUserAuthentication.ControlID

ControlID As String

Identifies the control on a per session basis.

This property is read-only.

WebUserAuthentication.Domain

Domain As String

The domain name used by the authenticator device to discover what credentials can be used, such as localhost or subdomain.example.com.

In the context of the WebAuthn specification, this is known as the Relying Party ID or rpID.

WebUserAuthentication.Enabled

Enabled As Boolean

When True the WebUserAuthentication object will respond. When False, the WebUserAuthentication object will not respond.

WebUserAuthentication.Name

Name As String

The name of the control.

This property is read-only.

WebUserAuthentication.Page

Page As WebPage

Identifies the web page that contains the control.

This property is read-only.

WebUserAuthentication.PanelIndex

PanelIndex As Integer

If the control has been placed on a WebTabPanel or WebPagePanel control, this is the panel (page/tab) that the control is on. If the control is not on a panel, it returns -1.

The first panel is numbered zero. If the control has been placed on a panel of a WebTabPanel or WebPagePanel control, it returns the panel number. If the control is not on a WebPagePanel or WebTabPanel, it returns -1. If you change the PanelIndex to a nonexistent panel, the control will disappear until you give it a PanelIndex value that corresponds to a panel that exists.

If you are looking to change the currently selected panel (page/tab), use SelectedPanelIndex.

This code displays the panel index of the control that is on the page.
MessageBox(Me.SelectedPanelIndex.ToString)

WebUserAuthentication.Parent

Parent As WebView

Used to get the control's parent control or page. If the parent control is a WebContainer, then it returns the WebContainer. If it is on a WebPage, it returns the WebPage.

This property is read-only.

WebUserAuthentication.Timeout

Timeout As Integer

Some authenticator devices will use this property to timeout/fail if the user doesn't react in the time specified by this property. The value must is in milliseconds. It defaults to 60000.

Method descriptions

WebUserAuthentication.Authenticate

Authenticate(Optional allowCredentials() As String)

When the user wishes to login, this method asks the browser to begin authentication. If the allowedCredentials parameter is passed, Xojo will ask the authenticator device to only allow the provided credentials IDs to be used for authentication.

In this example, a WebUserAuthentication object named Authenticate is on the layout. The CredentialRequested event will then be called so that you can return the credential for the user.
Authentication.Authenticate

WebUserAuthentication.Close

Close

Removes the control from the page.

WebUserAuthentication.ExecuteJavaScript

ExecuteJavaScript(script As String)

Executes the JavaScript passed. The JavaScript passed can call a JavaScript function in a WebPageSource control.

The Xojo web framework uses EcmaScript 6 which is more strict than previous versions of JavaScript. For more details, see the EcmaScript 6 documentation.

This code in the Pressed event of a Button displays an alert using JavaScript:
Me.ExecuteJavaScript("alert('Hello!');")
This code will select the text in a WebTextField (or WebTextArea):
WebTextField1.ExecuteJavascript("document.getElementById('" + _
WebTextField1.ControlID + "_inner').select();")

WebUserAuthentication.GoToURL

GoToURL(url As String, inNewWindow As Boolean = False)

Opens the passed url in place of the current web page or downloads a file. If inNewWindow is True, the browser is asked to open the url in a new window.

If the browser has popup windows disabled and inNewWindow is True, the method silently fails and the page is not shown.

If inNewWindow is False, the running web app is replaced with the specified url. If you want to display an external web site within your web app, use the WebHTMLViewer control.

Display a web site in a new popup window:
Me.GoToURL("http://www.wikipedia.org", True)

WebUserAuthentication.Register

Register(userId As String, username As String = "", displayName As String = "")

When the user wishes to create an account for the web application, this method asks the browser to begin registration. If the allowedCredentials parameter is passed, Xojo will ask the authenticator device to only allow the provided credentials IDs to be used for authentication.

In this example, a WebUserAuthentication object named Authenticate is on the layout that has a UserName WebTextField. The userID is being supplied via a Random UUID to make sure it's always unique while the username and displayname are both using whatever value the user provided in the UserName control:
Authentication.Register(Random.UUID, username.Text, username.Text)

WebUserAuthentication.UpdateBrowser

UpdateBrowser

Forces the current values of the control to be sent to the browser.

This method is useful when you are computing values in a loop and wish to update the browser immediately rather than wait until the current method ends.

This code iterates through a RowSet of database rows, updates a ProgressBar and then forces the updated ProgressBar to be sent to the browser via UpdateBrowser.
ProgressBar1.MaximumValue = SalesData.RowCount
For Each row As DatabaseRow in SalesData
  AnalyzeSales(row)
  ProgressBar1.Value = ProgressBar1.Value + 1
  ProgressBar1.UpdateBrowser
Next

Event descriptions

WebUserAuthentication.AuthenticationSucceeded

AuthenticationSucceeded(userId As String, credentialId As String, authenticationAttempts As Integer)

The server has received a valid authentication request with a previously stored WebAuthenticationCredential. The authenticationAttempts must be assigned to the stored credential, to ensure future authentication requests cannot come from a cloned authenticator device. Not every authenticator will use this value. A zero value is common.

WebUserAuthentication.Closed

Closed

The control has been removed from the page either because the page has closed or the control's Close method was called.

WebUserAuthentication.CredentialRequested

CredentialRequested(userId As String, credentialId As String) As WebAuthenticationCredential

During authentication the authenticator needs the credentials for the user. It is at this point that you would look in your database (or whatever storage you are using to track accounts) for an account whose userID and credentialID match those passed. You then create a WebAuthenticationCredential and return it from this event.

WebUserAuthentication.Error

Error(message As String)

An error has occurred during registration or authentication. The message is meant to the developer, not the end user.

WebUserAuthentication.Opening

Opening

The control has been created and the page is opening but has not been sent to the browser yet.

The Opening event handler can be used to initialize non-visual properties and settings for controls.

In most cases, you should use the Shown event to initialize controls.

WebUserAuthentication.RegistrationSucceeded

RegistrationSucceeded(userId As String, credential As WebAuthenticationCredential)

The authenticator has received a valid registration request. It is at this point that you should create a record in your database (or whatever account storage system you are using) with the userID and the information stored in the credential passed.

Sample code

Compatibility

Project Types	Web
Operating Systems	All