Setting up WebAuthn multifactor authentication

Using WebAuthn for multifactor authentication (MFA) is the best way to protect your account from takeover. It’s stronger and easier to use than OTP codes.

Prerequisite

To use WebAuthn, you will need at least one of the following:

• A hardware security token (sometimes called a security key), such as a YubiKey or Google Titan Key.
• A built-in hardware device, such as TouchID, FaceID or Windows Hello.
• A browser that supports the “Passkey” standard. Up-to-date versions of Chrome, Safari, Firefox and Edge all support this standard.

Unfortunately implementations of these experiences vary, so we can’t show the exact details, but we will point out the steps that are specific to using rubygems.org.

Enabling WebAuthn multi-factor authentication

1. Login to rubygems.org using your existing account and go to the edit settings page.
2. In the “Multifactor Authentication” section you will see two options: “Authentication App” and “Security Device”. Under “Security Device” you will see a field for “Nickname”.
3. Choose a name for your device. Use something that helps you remember which device you used. For example, you might use nicknames like “Mary’s YubiKey” or “Naveen’s iPhone”.
4. Below the Nickname field, click Register device.
5. Your browser will prompt you to set up a device or a Passkey. This experience varies according to browser. Chrome tries to set up a Passkey that it manages, though you can select “Try another way” to use a USB hardware token. Safari asks you to enable iCloud Keychain, but you can click “Other Options” to use a hardware token. Other browsers may vary.
6. You will now see your security device on the screen above the Nickname field.

Note: While Safari can be used for logging into the web UI using WebAuthn, it does not work for logging in with the CLI. This is due to Safari failing to implement a necessary feature.

Dealing with lost devices

WebAuthn often depends on a connection with the physical device you used as your security device. If you lose the device, you will be unable to login. There is no recovery code for WebAuthn MFA.

To manage the risk of losing a single device, you should enable multiple security devices. For example, you might enable your phone as well as a hardware token. Or you might use two hardware tokens and store the second token in a safe place that is separated from your computer (e.g. a fireproof safe or even a safe deposit box).

The process for enabling additional devices is the same as the process for enabling the first device. Choose a nickname, click Register device under the “Security Device” heading and follow the prompts.