Ubuntu SSO 2nd factor authentication FAQs



What is 2nd factor authentication?

Two factor authentication increases computer security further than just a user name and password. In addition to a password (the first factor) you need something else in order to access a system. Common ways to provide this extra level of security are:

  • A USB key (like the Yubikey)
  • A smart card
  • A special device or app running on a smart-phone
  • A fingerprint or retinal scan

By using more than one of these factors (eg: adding a 2nd factor), you increase the security of your system. See the 2-factor authentication article on Wikipedia for more information.

Note: We do not have plans to implement biometric 2-factor methods, such as a fingerprint scanner. This type of method is not compatible with OATH/HOTP, and is vulnerable to network-based attacks such as traffic capture and replay. The one-time password solution works because it changes at each login, but your fingerprint does not change.

Can I use it?


After being in beta for 7 years, as of November 23rd, 2021, 2-factor authentication is available (but optional) to all Ubuntu SSO users. It is also mandatory for Canonical employees and members of projects marked to require it.

Is it hard to use?

Not really. This adds one additional step to the login process. Instead of just username and password, you will need to enter your username, password, and one-time passcode. The one-time passcode changes each time.

How does it work?

Our 2-factor solution uses a standard, open, event-based OATH/HOTP/TOTP protocol. What this means is that the client and server both have a shared key and either a sequence counter or a synchronized real-time clock, and from this data they generate a predictable sequence of one-time passcodes. Each passcode is 6 decimal digits, from 000000 to 999999.

The shared key is 40 hex digits, and the sequence counter for HOTP is a simple number that starts at 0 and increases by 1 each time you log in. TOTP uses the device's clock to generate a code from the shared key, so the clock must be accurate.

NOTE: If you set up your device to use HOTP, it doesn't matter how much time passes between generating a passcode and consuming the passcode. Also, it means that you should avoid generating passcodes without using them, because it will cause the client and server to get out of sync and reject your login.

To help protect against accidental passcode consumption, the server will accept any of the next three passcodes in the sequence. This means you can 'click' your Yubikey up to twice between logins without getting locked out, but the third code should go to SSO or the client will get out of sync with the server and lock you out.

NOTE: If you set up your device to use time-based tokens (supported with the Google Authenticator app and other devices/applications which use TOTP), you must ensure your device's clock is accurate and correctly set. Each code is only valid for 30 seconds.

Why are you adding this to Ubuntu SSO?

Ubuntu SSO is the single identity and authentication system guarding a wealth of information at a large number of sites and services. We added this additional optional layer of security to help people protect their accounts and data when desired.

How do I add a new authentication device and start using 2-factor authentication?

This is fairly simple:

  1. Log in to https://login.ubuntu.com/ with your standard SSO account credentials.

  2. Click the "Authentication Devices" tab.
  3. Click "Add a new authentication device".
  4. Select a device type.
  5. Follow the instructions on screen.
  6. Select "Always" for "Require an authentication device", and click "Update".

After adding your primary device, a set of recovery/emergency codes (a "paper backup") will be generated and shown to you. You MUST print or otherwise store in a safe yet handy place, this set paper codes in addition to your primary device. Paper codes are easy to add, you can print them and have them stored somewhere secure (but handy) in case your main device gets lost, needs to be replaced, reflashed, etc.


What devices are supported?

These types of devices are officially supported right now:

  • Smartphones: Ubuntu Phone, Android, iOS, and Blackberry. Look in your device's App Store for any application that supports OATH 2-factor. Examples include Authy, Tofu, Google Authenticator and 1Password, but there are many more options to choose from.
  • Yubikey USB devices, running in OATH mode.
  • Feitian OTP c100 keyfobs.
  • Paper.

What unsupported devices work?

  • Smartphones: Maemo devices (Nokia N9 / N900).
  • oathtool
  • Any other OATH/TOTP/HOTP-compatible device.


Supported devices are those which run Ubuntu Phone, Android, iOS, or Blackberry.

Maemo-based devices (Nokia N9 / N900) can work too, using the unsupported HTML5 app detailed below.

Warning: If you flash your phone and do not have a backup device or paper codes you WILL get locked out! ALWAYS make sure you have a backup auth device and expect to delete and reconfigure 2-factor auth on your phone. Flashing the phone will make it forget your 2-factor login data and if you have no other device or paper codes, you WILL be locked out.

Initial setup

Go to https://login.ubuntu.com/device-list and follow the instructions to "Add a new authentication device". It will walk you through setting up "Google Authenticator" which is our supported app for iOS, Android and Blackberry devices and is free to download from official app stores. You can also use Authenticator in Ubuntu Phone, which is configured and works in a similar way, or any other 2-factor application that supports the OATH HOTP or TOTP protocols; some of these are Free software like Red Hat's FreeOTP or Tofu Authenticator. Please check your device's app store for compatible applications to choose one.

Once you have done this, a paper backup will be generated for you. Print this and store somewhere safe but handy.

If a paper backup is not generated for you, please do generate one manually and print the codes.

Does the smartphone need internet access to work (after installation)? I travel a lot and my phone doesn't always have data access.

No, it does not require internet access to work.




The Yubikey is a small USB device designed to fit onto a key ring. It pretends to be a USB keyboard, so it can type in your passcodes for you. This makes it both secure and convenient.

http://www.yubico.com/yubikey https://store.yubico.com/

Can I keep using this for existing sites as well as adding SSO support?

Most likely, yes. Recent model Yubikeys have two configuration slots (one on short press, the other on long press) which can be programmed independently. As long as you haven't used both of these for other systems, you'll be fine. SSO provides instructions to do this when you add a Yubikey to your account.

Initial setup

The only difference from the general instructions above is that you must run a command-line tool to configure your Yubikey:

  1. Before adding your first Yubikey device, run sudo apt-get install yubikey-personalization.

  2. The command for configuring your Yubikey will be displayed by SSO while adding a device. Copy/paste this into a terminal.

NOTE: If you are already using your Yubikey to authenticate at other sites, use the command for configuring slot 2! Otherwise, your existing configuration will be overwritten and cannot be recovered. It is possible to re-add Yubi-protocol functionality to your device, but your original key will be lost. If this happens, contact ISD support for instructions.


When SSO requests a one-time passcode, insert your Yubikey into a USB slot and then touch its button. The Yubikey should type in your passcode for you and press enter to submit the form.

Feitian OTP c100

This zero-footprint keyfob is small enough to fit on a key chain and works all by itself with no external power or connections. It has one button and an 8-digit LCD.


Initial setup

The device must be configured by an account administrator. Email ISD the shared AES key of your device and we will let you know when it's ready to use.


When SSO asks you for a one-time passcode, press the button on your c100 and copy the number onscreen into SSO.


Paper is simple, portable, low-tech, and pretty secure. Simply print a new sheet of one-time passcodes whenever you run out, then keep it in your wallet or purse for when you need it.

Initial setup

SSO now includes a feature for paper authentication. You need to log in, and click on "Add a new authentication device", and choose "Printable Backup Codes". Click on the button "Add device", and you will get a list of 25 codes, that you can print using the button "Print codes".


Whenever SSO asks for a one-time passcode, copy the next number from your sheet of codes and then cross it out. When you use up the entire sheet, generate and print a new one. You can have more than one device of type “Printable Backup Codes”, if you choose to do so, name the devices and the printed sheets appropriately (useful to know when your codes are finishing!) Take to account that when you generate a new set of codes the old ones will be invalidated. This means that every time a new set of codes is generated you’ll need to print the new ones again, as old ones aren’t good anymore.

Maemo devices (Nokia N9 / N900)

Maemo otp package

The Maemo distro has a client program which is compatible with SSO. It's called 'otp' and it's in extras-testing.

  • On login.ubuntu.com, select "Generic HOTP device".
  • Install the 'otp' package from extras-testing (http://maemo.org/packages/view/otp/).

  • Start OTP.
  • Select "Create New Token" from the menu. In this dialog:
    • Name: whatever you like, e.g. "Ubuntu SSO"
    • Algorithm: HOTP
    • Counter type: event-based
    • Key: enter the shared AES key displayed on login.ubuntu.com
    • Generate new key: don't tap this or it'll overwrite the key you just entered
  • Tap OK.
  • Select the token you just generated, e.g. "Ubuntu SSO".
  • Select "Edit" from the menu.
  • Uncheck "Display Hexadecimal" and change "Digits" to 8 (although 6 will work too).
  • Press "Generate" to generate a one-time password for login.ubuntu.com.


Laptops / notebooks

If you travel with your notebook, we do not recommend using it as a 2-factor authentication device. It works, but it is less secure than having a physically-separate auth device.

I don't want to use the supported app. Can I use something else?

Yes, our 2nd factor authentication uses the open OATH/HOTP protocol so there are many apps which will work with it and it's relatively easy to write your own too. Be aware, however, that we won't support these alternative apps so you will be responsible for getting it working and for keeping it working.


What if I lose my Yubikey, my phone battery dies, or my authentication device is otherwise unavailable?

You can add multiple 2fa devices to your account; the system will auto-detect which one you use at each login. We recommend having at least two devices associated with your account so you will have a backup in case the main device fails or locks you out. It's also required to have a "printable backup codes" device in case all your electronic devices become unavailable.

On the other hand, more auth devices means less secure. So, we recommend having no more than three auth devices associated with your account. So, if you ever stop permanently to use a device, please also delete it from your account.

I got locked out of my account. What should I do?

You have a backup auth device, right? Use it to log in, remove your broken primary auth device, and re-add the primary device with a fresh key.

Note that this is not possible with Feitian OTP c100 devices, since they cannot be reprogrammed. If your c100 stops working, skip to the next question.

No, I'm really locked out of my account. What should I do?

If you have trouble to log in because your device is ahead of sequence compared to the server, you'll be provided a link where you can enter 3 *consecutive* passcodes and the server will sync with the device.

If you're using a TOTP (Time-based) device, of the kind where codes are valid for a short time only and a new code appears automatically after 30 seconds, your phone's clock may be out of sync with what the server expects. In this case, just make sure your phone's clock is correct to the second and try again.

If you still can't make it work, send an email to isd-support@canonical.com with the subject '2fa locked out - my_sso_email@address'. Please include the type of device you are using for 2-factor authentication, and what your next 6-digit passcode is. This will allow us to re-sync the server to your device if possible.

Note however that if you lose all your devices (most commonly because changing phones or reinstalling an authenticator application that doesn't back the codes up), we will have no way of verifying your ownership of the account, and we can't disable 2FA based on an e-mail request, since it could be someone compromising your e-mail account and attempting to gain access, the very thing 2FA is designed to prevent. So In the case where all your devices are unavailable, the account will be irretrievably lost. For this reason, you must have "Printable Backup Codes" associated to your account.

Also note that we do not accept official proof of identity (government ID, passport), because we don't ask for this when you create an account, therefore we have no way of validating you are the person who created the account originally. In essence we don't need to verify your "identity", we need to verify "you're the person who created and owns the account" and an official ID doesn't help with that.


How can I maximize my security?

2-factor auth security

If you are using a smartphone or Yubikey or c100, your security should already be pretty good. Just try not to lose both your notebook and your auth device at the same time.

If you don't have a dedicated auth device, these ideas can make the system more secure:

  • Consider using paper, as described above.
  • Don't keep your 2FA keys/sequences on your notebook. If you use a command-line app, use it from a remote server or USB stick instead, so you won't lose your keys if your notebook gets stolen.

General security

  • Make sure you have a strong password on your computer.
  • Encrypt your home directory.
  • Don't let your browser cache your password. Or, at least use a master password for your browser's password store.
  • Take care to not leave your computer unattended or unlocked when you're not using it.
  • Check to make sure that secure sites you're viewing are what they claim to be.
  • Log out of sites as you finish using them, especially if you're using a shared computer or are in a public place.
  • Use a password on your ssh keys. The inconvenience can be mitigated by using ssh-agent.
  • If you work in public places, consider routing all your traffic (including DNS) over a trusted VPN.

Will this feature be released to the public?

2-factor authentication is public as of November, 2021.

Can I see the code?

Yes, it's open source. You can get it at https://code.launchpad.net/canonical-identity-provider/

What does this feature protect me against?

That depends on how you use it. At a minimum, it will protect you against compromised SSO credentials; even if someone manages to guess or steal your username and password, they will still be unable to access protected sites via your account. If your 2nd factor software is running on the same machine you use to access sites (eg: your laptop or mobile device) and you also have your credentials saved in your browser on that device then it won't prevent someone who steals it from accessing protected sites via your account.

How is this different than RSA SecurID, which was compromised in 2011?

RSA SecurID had a central point of failure, which was the RSA company itself. RSA's database was compromised, thus giving away all the secret keys for every client. Our solution doesn't have this issue because we issue our own keys and don't depend on any third parties. The key is only stored on our server and on your auth device.

If your auth device is stolen or compromised, your password protects against usage until you invalidate the device with the server. If the server gets compromised, it can request that all users reinitialize their devices with fresh keys, which was not possible with SecurID.

So, our system is less likely to be compromised, and makes post-compromise recovery cheaper and easier.

SSO/FAQs/2FactorAuthentication (last edited 2021-11-30 22:09:49 by roadmr)