QWebEngineWebAuthUxRequest Class

The QWebEngineWebAuthUxRequest class encapsulates the data of a WebAuth UX request. More...

Header: #include <QWebEngineWebAuthUxRequest>
CMake: find_package(Qt6 REQUIRED COMPONENTS WebEngineCore)
target_link_libraries(mytarget PRIVATE Qt6::WebEngineCore)
qmake: QT += webenginecore
Since: Qt 6.7
Instantiated By: WebEngineWebAuthUxRequest
Inherits: QObject

Public Types

enum class PinEntryError { NoError, InternalUvLocked, WrongPin, TooShort, InvalidCharacters, SameAsCurrentPin }
enum class PinEntryReason { Set, Change, Challenge }
enum class RequestFailureReason { Timeout, KeyNotRegistered, KeyAlreadyRegistered, SoftPinBlock, HardPinBlock, …, WinUserCancelled }
enum class WebAuthUxState { NotStarted, SelectAccount, CollectPin, FinishTokenCollection, RequestFailed, …, Completed }

Properties

Public Functions

QWebEngineWebAuthPinRequest pinRequest() const
QString relyingPartyId() const
QWebEngineWebAuthUxRequest::RequestFailureReason requestFailureReason() const
QWebEngineWebAuthUxRequest::WebAuthUxState state() const
QStringList userNames() const

Public Slots

void cancel()
void retry()
void setPin(const QString &pin)
void setSelectedAccount(const QString &selectedAccount)

Signals

void stateChanged(QWebEngineWebAuthUxRequest::WebAuthUxState state)

Detailed Description

This class contains the information and API for WebAuth UX. WebAuth may require user interaction during the authentication process. These requests are handled by displaying a dialog to users. QtWebEngine currently supports user verification, resident credentials, and display request failure UX requests.

QWebEngineWebAuthUxRequest models a WebAuth UX request throughout its life cycle, starting with showing a UX dialog, updating it's content through state changes, and finally closing the dialog.

WebAuth UX requests are normally triggered when the authenticator requires user interaction. It is the QWebEnginePage's responsibility to notify the application of the new WebAuth UX requests, which it does by emitting the webAuthUxRequested signal together with a newly created QWebEngineWebAuthUxRequest. The application can then examine this request and display a WebAuth UX dialog.

The QWebEngineWebAuthUxRequest object periodically emits the stateChanged signal to notify potential observers of the current WebAuth UX states. The observers update the WebAuth dialog accordingly.

For more information about how to handle web engine authenticator requests, see the Simple Browser.

Member Type Documentation

enum class QWebEngineWebAuthUxRequest::PinEntryError

This enum describes the errors that may prompt the authenticator to ask for a PIN.

ConstantValueDescription
QWebEngineWebAuthUxRequest::PinEntryError::NoError0No error has occurred.
QWebEngineWebAuthUxRequest::PinEntryError::InternalUvLocked1Internal UV is locked, so we are falling back to PIN.
QWebEngineWebAuthUxRequest::PinEntryError::WrongPin2The PIN the user entered does not match the authenticator PIN.
QWebEngineWebAuthUxRequest::PinEntryError::TooShort3The new PIN the user entered is too short.
QWebEngineWebAuthUxRequest::PinEntryError::InvalidCharacters4The new PIN the user entered contains invalid characters.
QWebEngineWebAuthUxRequest::PinEntryError::SameAsCurrentPin5The new PIN the user entered is the same as the currently set PIN.

enum class QWebEngineWebAuthUxRequest::PinEntryReason

This enum describes the reasons that may prompt the authenticator to ask for a PIN.

ConstantValueDescription
QWebEngineWebAuthUxRequest::PinEntryReason::Set0A new PIN is being set.
QWebEngineWebAuthUxRequest::PinEntryReason::Change1The existing PIN must be changed before using this authenticator.
QWebEngineWebAuthUxRequest::PinEntryReason::Challenge2The existing PIN is being collected to prove user verification.

enum class QWebEngineWebAuthUxRequest::RequestFailureReason

This enum describes the reason for WebAuth request failure.

ConstantValueDescription
QWebEngineWebAuthUxRequest::RequestFailureReason::Timeout0The authentication session has timed out.
QWebEngineWebAuthUxRequest::RequestFailureReason::KeyNotRegistered1Key is not registered with the authenticator.
QWebEngineWebAuthUxRequest::RequestFailureReason::KeyAlreadyRegistered2Key is already registered with the authenticator. Try to register with another Key or use another authenticator.
QWebEngineWebAuthUxRequest::RequestFailureReason::SoftPinBlock3The authenticator is blocked as the user entered the wrong key many times.
QWebEngineWebAuthUxRequest::RequestFailureReason::HardPinBlock4The authenticator is blocked as the user entered the wrong key many times and reset the PIN to use the specific authenticator again.
QWebEngineWebAuthUxRequest::RequestFailureReason::AuthenticatorRemovedDuringPinEntry5Authenticator removed during PIN entry.
QWebEngineWebAuthUxRequest::RequestFailureReason::AuthenticatorMissingResidentKeys6Authenticator doesn't have resident key support.
QWebEngineWebAuthUxRequest::RequestFailureReason::AuthenticatorMissingUserVerification7Authenticator doesn't have user verification support.
QWebEngineWebAuthUxRequest::RequestFailureReason::AuthenticatorMissingLargeBlob8Authenticator doesn't have large blob support.
QWebEngineWebAuthUxRequest::RequestFailureReason::NoCommonAlgorithms9No common algorithm.
QWebEngineWebAuthUxRequest::RequestFailureReason::StorageFull10The resident credential could not be created because the authenticator has insufficient storage.
QWebEngineWebAuthUxRequest::RequestFailureReason::UserConsentDenied11User consent denied.
QWebEngineWebAuthUxRequest::RequestFailureReason::WinUserCancelled12The user clicked Cancel in the native windows UI.

enum class QWebEngineWebAuthUxRequest::WebAuthUxState

This enum describes the state of the current WebAuth UX request.

ConstantValueDescription
QWebEngineWebAuthUxRequest::WebAuthUxState::NotStarted0WebAuth UX request not started yet.
QWebEngineWebAuthUxRequest::WebAuthUxState::SelectAccount1The authenticator requires resident credential details. The application needs to display an account details dialog, and the user needs to select an account to proceed.
QWebEngineWebAuthUxRequest::WebAuthUxState::CollectPin2The authenticator requires user verification. The application needs to display a PIN request dialog.
QWebEngineWebAuthUxRequest::WebAuthUxState::FinishTokenCollection3The authenticator requires token/user verification (like tap on the FIDO key) to complete the process.
QWebEngineWebAuthUxRequest::WebAuthUxState::RequestFailed4WebAuth request failed. Display error details.
QWebEngineWebAuthUxRequest::WebAuthUxState::Cancelled5WebAuth request is cancelled. Close the WebAuth dialog.
QWebEngineWebAuthUxRequest::WebAuthUxState::Completed6WebAuth request is completed. Close the WebAuth dialog.

Property Documentation

[read-only] pinRequest : const QWebEngineWebAuthPinRequest

This property holds the WebAuth request's PIN request information.

This is needed when the current WebAuth request state is CollectPin. WebAuth Dialog displays a PIN request dialog. The user needs to enter a PIN and invoke setPin() to proceed.

Access functions:

QWebEngineWebAuthPinRequest pinRequest() const

See also QWebEngineWebAuthPinRequest, CollectPin, and setPin().

[read-only] relyingPartyId : const QString

This property holds the WebAuth request's relying party id.

Access functions:

QString relyingPartyId() const

[read-only] requestFailureReason : const RequestFailureReason

This property holds the WebAuth request's failure reason.

Access functions:

QWebEngineWebAuthUxRequest::RequestFailureReason requestFailureReason() const

See also stateChanged() and QWebEngineWebAuthUxRequest::RequestFailureReason.

[read-only] state : const WebAuthUxState

This property holds the WebAuth request's current UX state.

stateChanged() is emitted when the current state changes. Update the WebAuth dialog in reponse to the changes in state.

Access functions:

QWebEngineWebAuthUxRequest::WebAuthUxState state() const

Notifier signal:

void stateChanged(QWebEngineWebAuthUxRequest::WebAuthUxState state)

[read-only] userNames : const QStringList

This property holds the available user names for the resident credential support. This is needed when the current WebAuth request's UX state is SelectAccount. The WebAuth dialog displays user names. The user needs to select an account to proceed.

Access functions:

QStringList userNames() const

See also SelectAccount and setSelectedAccount().

Member Function Documentation

[slot] void QWebEngineWebAuthUxRequest::cancel()

Cancels the current WebAuth request.

See also QWebEngineWebAuthUxRequest::Cancelled and stateChanged().

[slot] void QWebEngineWebAuthUxRequest::retry()

Retries the current WebAuth request.

See also stateChanged().

[slot] void QWebEngineWebAuthUxRequest::setPin(const QString &pin)

Sends the pin to the authenticator that prompts for a PIN. This is needed when the current WebAuth request's UX state is CollectPin. The WebAuth request is blocked until the user responds with a PIN.

See also QWebEngineWebAuthPinRequest and CollectPin.

[slot] void QWebEngineWebAuthUxRequest::setSelectedAccount(const QString &selectedAccount)

Sends the selectedAccount name to the authenticator. This is needed when the current WebAuth request's UX state is SelectAccount. The WebAuth request is blocked until the user selects an account and invokes this method.

See also userNames and SelectAccount.

[signal] void QWebEngineWebAuthUxRequest::stateChanged(QWebEngineWebAuthUxRequest::WebAuthUxState state)

This signal is emitted whenever the WebAuth UX's state changes.

Note: Notifier signal for property state.

See also state and WebAuthUxState.