Skip to content

feat(totp): Consistent user experience for TOTP setup #792

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kasparsd merged 8 commits into from
Feb 13, 2026
Merged

feat(totp): Consistent user experience for TOTP setup #792

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
793ce26
Group styles, scripts and remove extra leftover markup
kasparsd Feb 13, 2026
423abae
Additional markup to allow dynamic time updates
kasparsd Feb 13, 2026
30cbe1e
Group the input as step 3
kasparsd Feb 13, 2026
0aef4af
Inline right away
kasparsd Feb 13, 2026
fd2f3db
Better wording
kasparsd Feb 13, 2026
f13b5cc
Make it shorter and to the point
kasparsd Feb 13, 2026
759a186
Match the UX
kasparsd Feb 13, 2026
0c8e3a5
Spelling
kasparsd Feb 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file modified .wordpress-org/screenshot-1.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified .wordpress-org/screenshot-2.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified .wordpress-org/screenshot-3.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified .wordpress-org/screenshot-4.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified .wordpress-org/screenshot-5.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
126 changes: 58 additions & 68 deletions providers/class-two-factor-totp.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -311,59 +311,71 @@ public function user_two_factor_options( $user ) {
if ( empty( $key ) ) :
$key = $this->generate_key();
$totp_url = $this->generate_qr_code_url( $user, $key );

$datetime = wp_date( get_option( 'date_format' ) . ' ' . get_option( 'time_format' ) );
$tz_display = wp_timezone_string();
?>
<p class="two-factor-server-datetime"
data-server-epoch="<?php echo esc_attr( time() ); ?>">
<?php
/* translators: 1: server date and time, 2: timezone. */
printf(
esc_html__( 'Your server date and time is %1$s (%2$s). Please verify this is correct to ensure TOTP will work.', 'two-factor' ),
Copy link
Collaborator Author

@kasparsd kasparsd Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moved this notice to the footer -- bellow the code input since that is where it could fail due to server time offset.

esc_html( $datetime ),
esc_html( $tz_display )
);
?>
</p>
<p>
<?php esc_html_e( 'Please follow these steps in order to complete setup:', 'two-factor' ); ?>
</p>

<ol class="totp-steps">
<li>
<?php esc_html_e( 'Install an authenticator app on your desktop/laptop and/or phone. Popular examples are Microsoft Authenticator, Google Authenticator and Authy.', 'two-factor' ); ?>
</li>
<li>
<?php esc_html_e( 'Scan this QR code using the app you installed:', 'two-factor' ); ?>

<p id="two-factor-qr-code">
<a href="<?php echo esc_url( $totp_url, array( 'otpauth' ) ); ?>">
<?php esc_html_e( 'Loading…', 'two-factor' ); ?>
<img src="<?php echo esc_url( admin_url( 'images/spinner.gif' ) ); ?>" alt="" />
</a>
</p>

<p>
<?php
esc_html_e(
'If scanning isn’t possible or doesn’t work, use the secret key shown below to manually add the account to your chosen app:',
'two-factor'
);
?>
<br />
<code><?php echo esc_html( $key ); ?></code>
</p>
</li>
</ol>
<?php esc_html_e( 'Please follow these steps in order to complete setup:', 'two-factor' ); ?>
</p>
<ol class="totp-steps">
<li>
<?php esc_html_e( 'Install an authenticator app on your desktop/laptop and/or phone. Popular examples are Microsoft Authenticator, Google Authenticator and Authy.', 'two-factor' ); ?>
</li>
<li>
<?php esc_html_e( 'Scan this QR code using the app you installed:', 'two-factor' ); ?>
<p id="two-factor-qr-code">
<a href="<?php echo esc_url( $totp_url, array( 'otpauth' ) ); ?>">
<?php esc_html_e( 'Loading…', 'two-factor' ); ?>
<img src="<?php echo esc_url( admin_url( 'images/spinner.gif' ) ); ?>" alt="" />
</a>
</p>
<p>
<?php
esc_html_e(
'If scanning isn\'t possible or doesn\'t work, click on the QR code or use the secret key shown below to add the account to your chosen app:',
'two-factor'
);
?>
</p>
<p>
<code><?php echo esc_html( $key ); ?></code>
Copy link
Collaborator Author

@kasparsd kasparsd Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is now in own line for simple copy-paste. I also experimented with adding a "Copy" button next to it but decided to leave it to a follow-up pull request.

</p>
</li>
<li>
<p><?php esc_html_e( 'Enter the code generated by the Authenticator app to complete the setup:', 'two-factor' ); ?></p>
Copy link
Collaborator Author

@kasparsd kasparsd Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is now all part of the third step instead of being outside of the <ol>.

<p>
<input type="hidden" id="two-factor-totp-key" name="two-factor-totp-key" value="<?php echo esc_attr( $key ); ?>" />
<label for="two-factor-totp-authcode">
<?php esc_html_e( 'Authentication Code:', 'two-factor' ); ?>
<?php
/* translators: Example auth code. */
$placeholder = sprintf( __( 'eg. %s', 'two-factor' ), '123456' );
?>
<input type="text" inputmode="numeric" name="two-factor-totp-authcode" id="two-factor-totp-authcode" class="input" value="" size="20" pattern="[0-9 ]*" placeholder="<?php echo esc_attr( $placeholder ); ?>" autocomplete="off" />
</label>
<input type="submit" class="button totp-submit" name="two-factor-totp-submit" value="<?php esc_attr_e( 'Verify', 'two-factor' ); ?>" />
</p>
<p class="description">
<?php
printf(
/* translators: 1: server date and time */
esc_html__( 'If the code is rejected, check that your web server time is accurate: %1$s. Your device and server times must match.', 'two-factor' ),
Copy link
Collaborator Author

@kasparsd kasparsd Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reworded this from:

Your server date and time is %1$s (%2$s). Please verify this is correct to ensure TOTP will work.

so that:

  • mention when this is relevant (if the code is rejected),
  • explain why it is relevant (device and server time must match).

sprintf(
'<time class="two-factor-server-datetime-epoch" datetime="%1$s">%2$s (%3$s)</time>',
esc_attr( wp_date( 'c' ) ),
Copy link
Collaborator Author

@kasparsd kasparsd Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Introduced datetime for standard timestamp string that can be useful for any dynamic updates in the future. I had it updating via JS every second from the initial timestamp but I realized that nothing was changing because we don't have the seconds in there.

esc_html( wp_date( get_option( 'date_format' ) . ' ' . get_option( 'time_format' ) ) ),
esc_html( wp_timezone_string() )
)
);
?>
</p>
</li>
</ol>
<style>
#two-factor-qr-code {
/* The size of the image will change based on the length of the URL inside it. */
min-width: 205px;
min-height: 205px;
}
</style>

Copy link
Collaborator Author

@kasparsd kasparsd Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All the JS and CSS was grouped under the inputs for consistency. Eventually we want to move them into external JS and CSS per #562.

<script>
(function(){
var qr_generator = function() {
Expand Down Expand Up @@ -397,27 +409,6 @@ public function user_two_factor_options( $user ) {
window.addEventListener( 'DOMContentLoaded', qr_generator );
}
})();
</script>
<hr />
<ol class="totp-steps" start="3">
<li>
<?php esc_html_e( 'Enter the code generated by the Authenticator app to complete the setup:', 'two-factor' ); ?>
</li>
</ol>
<p>
<input type="hidden" id="two-factor-totp-key" name="two-factor-totp-key" value="<?php echo esc_attr( $key ); ?>" />
<label for="two-factor-totp-authcode">
<?php esc_html_e( 'Authentication Code:', 'two-factor' ); ?>
<?php
/* translators: Example auth code. */
$placeholder = sprintf( __( 'eg. %s', 'two-factor' ), '123456' );
?>
<input type="text" inputmode="numeric" name="two-factor-totp-authcode" id="two-factor-totp-authcode" class="input" value="" size="20" pattern="[0-9 ]*" placeholder="<?php echo esc_attr( $placeholder ); ?>" autocomplete="off" />
</label>
<input type="submit" class="button totp-submit" name="two-factor-totp-submit" value="<?php esc_attr_e( 'Verify', 'two-factor' ); ?>" />
</p>

<script>
(function($){
// Focus the auth code input when the checkbox is clicked.
document.getElementById('enabled-Two_Factor_Totp').addEventListener('click', function(e) {
Expand Down Expand Up @@ -459,7 +450,6 @@ public function user_two_factor_options( $user ) {
} );
})(jQuery);
</script>

<?php else : ?>
<p class="success">
<?php esc_html_e( 'An authenticator app is currently configured. You will need to re-scan the QR code on all devices if reset.', 'two-factor' ); ?>
Expand Down Expand Up @@ -724,7 +714,7 @@ protected static function pad_secret( $secret, $length ) {
* @param int $digits The number of digits in the returned code.
* @param string $hash The hash used to calculate the code.
* @param int $time_step The size of the time step.
*
*
* @throws InvalidArgumentException If the hash type is invalid.
*
* @return string The totp code
Expand All @@ -744,7 +734,7 @@ public static function calc_totp( $key, $step_count = false, $digits = self::DEF
break;
default:
throw new InvalidArgumentException( 'Invalid hash type specified!' );
}
}

if ( false === $step_count ) {
$step_count = floor( self::time() / $time_step );
Expand Down