| layout | default | ||
|---|---|---|---|
| title | Using multi-factor authentication in command line | ||
| url | /using-mfa-in-command-line | ||
| previous | /setting-up-otp-mfa | ||
| next | /mfa-requirement-opt-in | ||
| redirect_from |
|
How to use multi-factor authentication with gem CLI.
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 or one-time passwords (OTP).
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" below.
When you have enabled WebAuthn MFA, we will ask you to perform authentication on certain commands based on your authentication level.
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>
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" 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
for enabling MFA.
This level requires a recent enough gem command as shipped with Ruby 2.6+,
or RubyGems 3.0+.
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)