Yubikeys - alphagov/notifications-manuals GitHub Wiki
All team members should either use their Yubikey or their GDS Managed mac as their MFA for logging into their Notify account.
Developers must Yubikeys for
- AWS MFA
- Github MFA
If you are going to have your yubikey plugged into your laptop all the time, you must have it set up so that it requires a physical tap to authenticate
- Google MFA set up
- AWS MFA set up
- Github MFA set up
- GPG set up(optional)
- Other one time passcode set up (optional)
You can use your YubiKey as your 2FA device for your Google Account.
Visit your Google account settings to add your YubiKey as a Security Key.
Alternatively, you can use your touch ID on your laptop:
- go to https://myaccount.google.com/signinoptions/passkeys
- click “+ create a passkey”
- click “create a passkey”
- optional - you might need to allow chrome to access passkeys at this point
- click “cancel” on the iCloud Keychain prompt
- click “Your Chrome Profile” on the create a passkey prompt
- click “continue”
- touch your fingerprint when prompted
When you use your Google account to log in to the GDS VPN, when prompted you will need to choose 'Get a one-time security code' as the pop up does not support your Yubikey or touch ID by default.
Choosing this option will tell you to get a code from another device but this is misleading. You can instead just visit https://g.co/sc from your browser to get the code.
You can use your YubiKey as your 2FA device for your Github account.
As Github accounts are not administrated by GDS, if you lose your form of MFA then you may be locked out forever. Therefore, you should at the very least have recovery codes stored securely and/or have a back up form of MFA such as a OTP app.
Visit your Github security settings to add your YubiKey as a Security Key
brew install ykman
To get the MFA secret code for your user you need to
- Sign in to https://gds-users.signin.aws.amazon.com/console using your existing MFA
- Navigate to IAM
- Navigate to your user
- Navigate to Security Credentials
- Manage MFA
- Remove MFA device (if you have an existing one)
- Add a new virtual MFA ("Authenticator app") device (do not choose any of the hardware options)
- The device name that you choose must be, or start with, your GDS email address
- Click "Show secret code"
- (Optional) You can also scan the QR into an authenticator app if you wish to have a back up until you are confident that your yubikey is working. When you are confident, you should remove the QR code from your authenticator app
ykman oath accounts add gds-users YOUR_MFA_SECRET --touch
And test it:
ykman oath accounts code gds-users
If you use the GDS CLI:
gds config yubikey true
Then test it by running
gds aws notify-tools -l
ykman oath accounts add <account name> <secret> and ykman oath accounts code <account name>
We buy https://www.amazon.co.uk/Yubico-Authentication-Security-Supported-Accounts/dp/B08DHL1YDL. The yubikey is purchased by getting in contact with GDS Business Operations who will provide payment details for ordering a yubikey. Ask Caley if you have any questions about the process.
- Tell the team as soon as possible.
- Arrange a video call with the developer on support to confirm your identity.
- Developer on support will need to downgrade your Notify account from platform admin to regular user and remove the yubikey from your account (TODO: how best to remove yubikey? write query here once we've done this once).
- Get a new yubikey.
- Once you have your new yubikey, log in to Notify, set up your new key, revoke your old key and log out.
- Log in to Notify using webauthn to check it all works correctly.
- Ask the developer on support to log on to the database and make you a platform admin again.
- For AWS access you will need to ask Reliability Engineering to reset your MFA
- For Google access you may need to ask IT to help you reset your MFA if you do not have a sufficient fall back method
We would like Yubikeys to be returned to the team if you leave so they can be factory reset and given out to other team members