<em class="text-neutral-600">How to use multi-factor authentication with gem CLI.</em>

Multi-factor authentication (MFA) greatly increases the security of your account.
RubyGems currently requires that owners of any gem with more than 180 million
cumulative downloads must enable MFA.

You can use MFA with the gem CLI via [WebAuthn](#using-webauthn) or
[one-time passwords (OTP)](#using-otp).

* [Using WebAuthn](#using-webauthn)
* [Using OTP](#using-otp)

Using WebAuthn
--------------

Multi-factor authentication (MFA) using WebAuthn works by using a
removable hardware token or touch biometric / facial biometric capabilities built
into your phone or computer. This is distinct from MFA based on typing or copying
a code generated by an authentication app or password manager, called OTP. For
OTP MFA see "[Using OTP](#using-otp)" below.

When you have enabled WebAuthn MFA, we will ask you to perform authentication on certain
commands based on your [authentication level](/setting-up-multifactor-authentication/#authentication-levels).

    Enter your RubyGems.org credentials.
    Don't have an account yet? Create one at https://rubygems.org/sign_up
    Email:   gem_author@example
    Password:

    [snip of API key setup]

    You have enabled multi-factor authentication.
    Please visit http://localhost:3000/webauthn_verification/<random>?port=<port>
    to authenticate via security device. If you can't verify using WebAuthn but
    have OTP enabled, you can re-run the gem signin command with the `--otp [your_code]`
    option.

Depending on your terminal program, you may be able to click, command-click or
control-click on the link to open it in your default browser. Otherwise you will
need to copy and paste the link into a new tab.

A webpage titled "Authenticate with Security Device" appears. Click "Authenticate".
Your browser will show a popup asking you to use a Passkey or other authentication
device (the exact popup will vary according to the browser).

Once you have authenticated using your WebAuthn device, you will see a
"Success" page. At this point you can close your browser tab and return to the
command line, which will say:

    You are verified with a security device. You may close the browser window.
    Signed in with API key: <your API key name>

Using OTP
---------

Multi-factor authentication (MFA) using OTP works by using an authenticator app on your phone
to generate a one-time password (OTP) that you then enter at the command line. For
WebAuthn instructions, see "[Using WebAuthn](#using-webauthn)" above.

When you have only enabled OTP MFA, and your MFA level is _UI and API_, we will ask you
to provide an OTP for `gem signin`, `gem push`, `gem owner --add` and `gem owner --remove`.
Check [setting up multi-factor authentication](/setting-up-multifactor-authentication)
for enabling MFA.

This level requires a recent enough `gem` command as shipped with Ruby 2.6+,
or [RubyGems 3.0+](https://rubygems.org/pages/download).

You can preemptively pass an OTP code using `--otp` flag or else we will prompt
for the OTP code when required:

    $ gem signin
    Enter your RubyGems.org credentials.
    Don't have an account yet? Create one at https://rubygems.org/sign_up
    Email:   gem_author@example
    Password:

    You have enabled multi-factor authentication. Please enter OTP code.
    Code:   111111
    Signed in.

Passing OTP as flag:

    $ gem signin --otp 111111
    Enter your RubyGems.org credentials.
    Don't have an account yet? Create one at https://rubygems.org/sign_up
    Email:   gem_author@example
    Password:

    Signed in.

Note that `gem signin` only fetches and stores your rubygems.org api key. `gem signin`
is not equivalent to creating a user session. We will check for OTP code every time you
use any of the commands mentioned above.

Publishing a gem after signing in from CLI:

    $ gem push hello-0.0.1.gem
    Pushing gem to https://rubygems.org...
    You have enabled multi-factor authentication. Please enter OTP code.
    Code:   111111
    Successfully registered gem: hello (0.0.1)