Multi-Factor Authentication (Coming Soon)

View as Markdown

CloudRepo supports multi-factor authentication (MFA) with a time-based one-time password (TOTP) from an authenticator app, and ten single-use backup codes. MFA is included on every plan.

Two different things are called MFA, and they do different jobs.

Your own MFA: Protects your sign-in to the CloudRepo portal, and ends your password’s use in build tools: see What setting up MFA changes. Any member who signs in with a password can set it up for their own account, at any time, without asking anyone. The exception is an organization on CloudRepo’s legacy Okta integration, where only the owner can set up MFA.
Your organization’s requirement: A policy the organization owner sets for everyone. It makes every member who signs in with a password set up MFA, and it stops passwords in build tools for the whole organization. In an organization on the legacy Okta integration, only the owner can set up MFA, and MFA cannot be required for the organization.

You can have either one without the other. Setting up your own MFA does not require MFA of anyone else, and an owner requiring MFA does not set it up for anyone: each member sets up their own the next time they sign in. In an organization on the legacy Okta integration, only the owner can set up MFA, and MFA cannot be required for the organization.

To move an organization to MFA without breaking a build, first move every pipeline that signs in with a member’s password to a service key or a repository token.

Set up MFA for your own account

These steps are for the owner, and for every member who signs in with a password. The exception is an organization on the legacy Okta integration, where only the owner can set up MFA.

Sign in to the CloudRepo portal. In the sidebar, click Your account security.

Expected: the Multi-factor authentication card, with a Not enrolled badge and a Set up authenticator app button.
Click Set up authenticator app. Read the warning about builds, tick My builds use a repository token, not this password., and click Set up authenticator app. In Confirm Your Identity, enter your password and click Confirm.

Expected: the Set Up Two-Factor Authentication page, with a QR code and, under it, a key you can type in by hand.

If you close Confirm Your Identity without confirming, nothing is set up, and the page says: Nothing was set up. We confirm your password before showing a new authenticator secret, so confirm it when asked to continue.
Scan the QR code with your authenticator app, or type the key into it. Enter the code the app shows under Verification code, and click Verify.

Expected: ten backup codes.
Save the backup codes somewhere you can reach without your phone: copy them or download them as a text file. Tick the box that says you have saved them, then click the button under it.

Expected: Your account security again, where the Multi-factor authentication card shows the Enrolled badge and the date you set MFA up.

What setting up MFA changes

Two things change for you.

Every later sign-in to the portal asks for a code from your authenticator app after your password.
Once you turn on a second factor, build tools and package managers cannot use your password. Use a repository token instead.

The second sentence is the portal’s own, on the card where you set MFA up. A build tool that sends the password of a member who has a second factor gets the same answer as for a wrong password: a 401 Unauthorized that names no cause, because CloudRepo does not say who has a second factor. (Docker’s answer is the registry error UNAUTHORIZED, “authentication required”.) This holds for Maven, Gradle, npm, pip, twine and Docker. (An organization that requires MFA refuses every password with its own sentence, as the section below says.) A repository token keeps working, and so do subscriber keys and your organization’s service keys. Repository tokens shows where a token goes for each build tool.

Require MFA for your organization

Only the organization owner can do this.

In the sidebar, click Security, then click the Organization MFA policy card.

Expected: the MFA Enforcement card, with a Disabled badge.
Tick Require MFA for password logins.

Expected: a dialog headed Enable MFA enforcement? that names the members whose credentials stop working in build tools once you confirm. Nothing is saved until you confirm. In an organization on the legacy Okta integration, only the owner can set up MFA, and MFA cannot be required for the organization.
Click Enable MFA enforcement. In Confirm Your Identity, enter the code from your authenticator app under Authenticator Code and click Confirm. If you have not set up MFA on your own account, the dialog asks for your password instead.

Expected: the badge reads Enabled.

Change a pipeline that signs in with a member’s password to a service key or a repository token first: Service keys for your pipelines shows how.

What requiring MFA does

In the portal. Every member who signs in with a password is asked to set up MFA at their next sign-in. They are not locked out: they confirm their builds use a repository token, set up an authenticator, enter a code, and carry on. This includes the owner. When you turn the requirement on, every member is signed out and signs in again. The owner is not signed out: the session that made the change, and the owner’s other sessions, keep working, and the requirement applies at the owner’s next sign-in. In an organization on the legacy Okta integration, only the owner can set up MFA, and MFA cannot be required for the organization.

In build tools. A password is refused at every package door, with no grace period, and the build receives this (status 401):

Password authentication is disabled because MFA is required for this organization. Use an API token instead.

Repository tokens, npm tokens, subscriber keys and your organization’s service keys are not affected: this is the supported way to run CI in an organization that requires MFA. The refusal’s name, mfa_required, is explained on the error codes page. The message calls the credential an API token; it is the repository token you create under Repository Tokens.

When it takes effect

A build can still succeed for up to a minute after you turn the requirement on. A build that succeeds just after you enable it does not mean the requirement failed to apply. Wait a minute, then run it again.

Members who had already set up MFA

Their authenticator and backup codes do not change. They are signed out with everyone else and sign in again with a code. An organization requirement does not remove or replace anyone’s authenticator.

Members cannot turn off their own MFA while it is required

While your organization requires MFA, nobody can remove their own second factor, the owner included. The attempt is refused with:

Your organization requires multi-factor authentication, so it cannot be turned off for your account.

An owner who wants their own second factor off first turns the organization requirement off. This is not the way back from a lost authenticator: see If someone loses their authenticator.

Turn the requirement off

The owner clears Require MFA for password logins the same way they set it, including the identity check. Turning the requirement off asks for the same proof as turning it on, because it is the change that weakens every member’s sign-in.

An owner who has lost their authenticator cannot use a backup code at this step: the identity check takes a code from the authenticator. Get the factor back first (see If someone loses their authenticator), then clear the requirement.

Two things are worth knowing:

Nobody’s MFA is removed. Every member who set up an authenticator keeps it and is still asked for a code at sign-in. A member who wants to stop being asked turns off their own MFA, which is possible again once the requirement is off.
Passwords work in build tools again, after the one-minute delay above, for every member except those who have a second factor: build tools cannot use their passwords (see What setting up MFA changes).

Turning the requirement off does not sign anybody out.

Backup codes

Backup codes are how you sign in when you do not have your authenticator. Each code works once. You have ten when you set MFA up, CloudRepo shows them once, and they cannot be shown again.

If you are the organization owner and lose them or use them up, generate a new set:

In the sidebar, click Your account security. The Backup Codes section shows how many codes you have left.

Expected: the section lists how many of 10 remain.
Click Regenerate Codes and enter the code from your authenticator app.

Expected: a new set of ten codes on the page, with a notice that the previous codes are now invalid.

Generating a new set invalidates the previous set completely. Save the new codes before you leave the page.

If you are a member, Regenerate Codes is not offered to you. To get a new set, ask your organization’s owner to reset your MFA (see below); you then set up your authenticator again and receive a new set of codes. If your organization does not require MFA and you still have your authenticator, you can instead turn MFA off and on again: on Your account security, click Disable my MFA, which asks for your password and a code from your authenticator app. Turning MFA off signs you out of every portal session, this one included. Sign in again with your password, then on Your account security click Set up authenticator app. Read the warning about builds, tick My builds use a repository token, not this password., and click Set up authenticator app. Setting MFA up gives you a new set of ten codes.

If someone loses their authenticator

If you still have a backup code, sign in with it.

If you are the organization owner and have lost your own authenticator, Your account security offers Reset authenticator app. It removes your authenticator and your backup codes and ends every portal session you hold, including the one you reset from. The next time you sign in with your password, CloudRepo asks you to confirm your builds use a repository token, then to set up a new authenticator. It also gives you a new set of backup codes.

If you are a member and have lost your authenticator, the owner resets your MFA, as described next. You cannot do it yourself: turning MFA off takes a code from your authenticator, and a backup code does not count.

If you have lost both your authenticator and your backup codes, the way back depends on your role. A member asks the organization’s owner to reset their MFA in the admin portal. An owner contacts support@cloudrepo.io: another administrator who manages users confirms the reset in the admin portal, and every administrator is emailed. The owner then resets their password with Forgot Password, and after 24 hours the reset completes at their first sign-in with the new password. If there is no other administrator who can confirm, support verifies the owner’s identity without relying on email, and the same steps apply: a 24-hour hold, then Forgot Password and a sign-in with the new password. Every administrator is emailed when support confirms the reset. Support never resets MFA on an email alone.

Resetting a member’s MFA

The owner can reset a member’s MFA from two places:

Security, then Organization MFA policy, in the User Enrollment Status table, with Reset MFA.
The member’s page under Users, with Reset MFA for this member.

Either one asks the owner to confirm their own identity first. The reset removes the member’s authenticator and backup codes and ends their portal sessions. For a member on the legacy Okta integration, a reset ends their sessions and does not ask them to set up MFA. After a reset, the member sets up MFA again at their next sign-in. If your organization does not require MFA, their password alone works again with Maven, npm and PyPI clients until they set up MFA again. In an organization on the legacy Okta integration, only the owner can set up MFA, and MFA cannot be required for the organization.

If a reset reports it couldn’t finish, it may already have ended their sessions and removed their MFA. Run the reset again to finish it.

Both places read the same list, which holds every member CloudRepo has an authenticator for, however they set it up.

If the portal says your multi-factor authentication must be reset, ask your organization’s owner to reset it. (Error code mfa_reset_required.)

If the portal says your second factor can’t be used here and you have no backup codes left, ask your organization’s owner to reset your MFA, or contact support. (Error code mfa_factor_unavailable_here.)

When a member leaves

Deleting a member from Users removes their MFA along with the rest of their access. If your identity provider removes or deactivates them through SCIM, their MFA is removed in the same operation. Whoever is later given the same email address sets MFA up from scratch, and does not inherit the previous holder’s authenticator.

Repository tokens, the credentials build tools use, and service keys for pipelines.
Error codes, what each MFA refusal means.
User management, for creating members and setting their permissions.
Security hardening, for the wider security configuration guide.