Turn on MFA and SSO without breaking your builds

View as Markdown

This guide moves an organization to multi-factor authentication (MFA), single sign-on (SSO), or both, in an order that keeps every build running. It names who does each step, what keeps working at each change, and what each refusal means and how to fix it.

Included on every plan: MFA and SSO are part of every CloudRepo plan.

The short version

Requiring MFA, enforcing SSO, and allowing SSO sign-in for a member each stop passwords working in build tools. A member who sets up a second factor on their own account loses their password in build tools too: they use a repository token instead. Turning on SSO without enforcing it leaves every password working.
Subscriber keys and your organization’s service keys keep working through every change in this guide: requiring MFA, turning on SSO, enforcing it, switching identity providers, and members leaving.
Once SSO is enforced, a member’s repository token works only if the member created it after signing in through your current identity provider. When you switch identity providers, tokens created after a sign-in through the old one stop working, whether or not SSO is enforced, with one exception for older tokens, named in If you switch identity providers.
Enforcing SSO does not affect anonymous pulls of a public image: Public Access serves them without a sign-in. Enforcing SSO does not make a repository private: a client that reads a public repository without asking for a token can still read it. Making the repository private is what stops anonymous reads.
When you delete a member in CloudRepo, their password and their tokens stop working. Removing someone only in your identity provider ends their sign-ins through it and nothing else: their tokens keep working until they expire, and a token can be set to never expire.
The organization owner signs in with a password, never through SSO. Enforcing SSO needs the owner to have a second factor, and keeps it in place.

Who does what

Who	What they do
The organization owner	Sets up their own second factor, creates service keys, requires MFA, sets up and enforces SSO, and allows SSO sign-in for members. Only the owner can change these settings.
Your identity provider’s administrator	Creates the CloudRepo app in your identity provider and assigns your people to it.
Each member	Sets up MFA when CloudRepo asks. Once SSO is on, signs in through your identity provider and creates new repository tokens for the places they use one.
Whoever owns your pipelines	Moves every pipeline off passwords, onto a service key, before anything else changes.

What keeps working

Each row is a change you make. Each column is a credential a build can use. Find the change you are about to make and read across. Works means the credential keeps working wherever it worked before the change.

Password: a member’s CloudRepo password.
Token, password sign-in: a repository token a member created while signed in with a password.
Token, SSO sign-in: a repository token a member created after signing in through your identity provider.
Subscriber key: a key you issue to a subscriber, to distribute your software.
Service key: a key that belongs to your organization, not to a person. See Service keys for your pipelines.

You	Password	Token, password sign-in	Token, SSO sign-in	Subscriber key	Service key
A member sets up their own second factor	Stops for that member: a plain 401	Works	Works	Works	Works
You require MFA	Stops: `mfa_required`	Works	Works	Works	Works
You turn on SSO	Works	Works	Works	Works	Works
You allow SSO sign-in for a member	Stops for that member	Works	Works	Works	Works
You enforce SSO	Stops: `sso_enforced`	Stops: `sso_enforced`	Works	Works	Works
You switch identity providers	No change	No change	Stops if made through the old one: `idp_switched`	Works	Works
You delete a member in CloudRepo	Stops	Stops	Stops	Works, their own keys too	Works
You remove a member only in your identity provider	No change	No change	Works	Works	Works

A member’s tokens include the ones npm login creates for them.

Repository tokens the owner creates keep working through every change in the table. Enforcing SSO can stop an older owner token; the step 10 dialog counts them before you confirm. If one is refused, create a new one.

The switch row has one exception for older tokens, named in If you switch identity providers.

Maven, npm, pip and Docker see every change in this guide within a minute. A Docker client that already holds a token from CloudRepo when you enforce SSO or switch identity providers keeps its access for up to five minutes. A build that passes in the first minutes after you change a setting proves nothing yet: wait, then run it again.

The checklist

Do these in order. Each step says what you should see before you go on.

Before you change anything

Find every pipeline that signs in to CloudRepo with a member’s password, including shared build users. Give each pipeline a service key, as Service keys for your pipelines shows, and put the key where the password was. Do not move a pipeline onto a member’s own repository token: it stops working when that member leaves. Once a build user’s pipelines all use a service key, delete the build user on the Users page.

Expected: no build configuration, CI secret or settings.xml holds a CloudRepo password, and each pipeline passes with its service key. Requiring MFA, allowing SSO sign-in (step 8) and enforcing SSO each end passwords in build tools, so this comes first.

Sign in as the owner and set up a second factor on your own account. Click the person icon at the top right (the account menu), then Your account security. On the Multi-factor authentication card, 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. Scan the code with your authenticator app, enter the code the app shows, and click Verify. Save the backup codes somewhere you can reach without your phone.

Expected: your next sign-in asks for a code from your authenticator app, and so does the service-key script in step 1 when you next run it. CloudRepo needs this before it lets you enforce SSO or allow SSO sign-in for members.

Require MFA

This applies to members who sign in to CloudRepo with a password.

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? names the members whose passwords stop working in build tools once you confirm (a long list ends with and N more), and says MFA enforcement applies to password sign-ins only. If SSO is already on, it says instead: CloudRepo MFA applies to password logins. Users who sign in through your identity provider are governed by its MFA policy.
Click Enable MFA enforcement. In Confirm Your Identity, enter the code from your authenticator app under Authenticator Code and click Confirm. It does not ask for your password: once you have a second factor (step 2), the dialog asks for that instead.

Expected: a banner reads MFA enforcement enabled., and the badge reads Enabled. Every member is signed out of CloudRepo, and each member who signs in with a password sets up MFA at their next sign-in.
Wait one minute, then run a build that uses a service key or a repository token.

Expected: it passes. A build that still uses a password fails with mfa_required.

Turn on SSO, then enforce it

Open Security in the portal, then OIDC or SAML. On SSO Settings, choose the same type: the page shows the values your identity provider’s app for CloudRepo needs, then the fields to fill in, for Okta, Microsoft Entra ID or another OIDC or SAML provider. Fill them in and click Configure OIDC (or Configure SAML). In Confirm Your Identity, enter the code from your authenticator app under Authenticator Code and click Confirm. Saving does not turn SSO on: the badge still reads Disabled. Click Enable SSO, and confirm your identity the same way. Do not enforce it yet. Get the connection right now: once anyone has signed in through SSO, CloudRepo refuses Disconnect SSO, and disconnecting and setting SSO up again counts as switching identity providers.

Expected: SSO Settings shows the Enabled badge. Members’ passwords and tokens still work in build tools. From now on, Continue on the sign-in page takes members to your identity provider, and CloudRepo refuses that sign-in for a member who already has a CloudRepo account, with sso_link_required, until you allow it in step 8.

On SSO Settings, under Member SSO sign-in, click Allow SSO sign-in for all members. In the dialog headed Allow SSO sign-in for all members?, type ALLOW ALL, click Allow SSO sign-in, and enter a code from your authenticator app. Then click Allow SSO sign-in next to each member the page lists as needing their own allowance.

Expected: before you confirm, the dialog says that each member’s CloudRepo password, open sessions and second factors end now, that the repository and npm tokens they created keep working, and This cannot be undone: nothing gives back the passwords and second factors it ends. Each allowance waits 7 days for that member’s first sign-in through your identity provider. From here on, fix a sign-in problem in your identity provider, with the values SSO Settings shows, and do not disconnect: Disconnect SSO removes every allowance still waiting.

If the page says Enable SSO first, then allow SSO sign-in. instead, SSO is not on yet, and CloudRepo refused the click with sso_not_enabled: click Enable SSO as in step 7, then allow SSO sign-in again.

Within 7 days of step 8, ask each member to sign in through your identity provider: they go to https://admin.cloudrepo.io/login, enter your organization ID and click Continue. Then, in the sidebar, they click Repository Tokens, click Create token, and when CloudRepo asks them to confirm their identity, click Re-authenticate with your identity provider. They replace the tokens on their own machines with these.

Expected: a banner reads Token created. These are the tokens that keep working once you enforce SSO. A member who first signs in after the 7 days is refused with sso_link_required: allow them again, as in step 8. If a member’s sign-in fails for another reason, fix it in your identity provider, not with Disconnect SSO (step 8 says why).

On SSO Settings, click Enforce SSO. Read the counts in the dialog: they are the member passwords and repository tokens that stop working when you confirm. Read every address too: each one loses password sign-in. If a pipeline signs in with a member’s password or with one of those tokens, a build user’s included, click Cancel and move it to a service key first, as in step 1. A public Docker repository still serves anonymous pulls when SSO is enforced; only private repositories need a credential. You cannot turn enforcement off yourself. Enforcing SSO does not make a repository private: to stop anonymous reads, make the repository private. sso_enforced says what a consumer you know can use instead.

Expected: a dialog headed Enforce SSO? that counts what stops working and says, before you confirm, that members’ repository tokens stop working, including npm login tokens, unless created after signing in through your identity provider. It says that service keys, subscriber access keys, and tokens members create after signing in through your identity provider are still working. It says Move CI to a service key before you enforce. with a link, How to create a service key, and As the owner, you can still sign in with your password and a second factor.
Click Enforce SSO in the dialog. In Confirm Your Identity, enter the code from your authenticator app under Authenticator Code and click Confirm.

Expected: a banner reads SSO enforced., and SSO Settings shows the Enforced badge. Every member is signed out of CloudRepo and signs in again through your identity provider.
Wait one minute, then run your builds.

Expected: they pass. A build that fails with sso_enforced is using a password or an older token: move a pipeline to a service key, and a member creates a new token as in step 9.

If your identity provider is Microsoft Entra ID

With Microsoft Entra ID over OIDC, the first sign-in of a member you invited waits for you to allow their address. By default Entra’s ID token does not say the member’s address is verified, so CloudRepo refuses the sign-in with sso_link_required and the member sees Your organization has to make a change before you can sign in with SSO, so signing in again will not work yet. Contact your organization’s administrator. The invitation stays pending until you allow the member’s address, as in step 8.

To allow one address, on SSO Settings, under Member SSO sign-in, type the address under One member and click Allow SSO sign-in.

If you switch identity providers

Switching identity providers means pointing CloudRepo at another one: changing the protocol (OIDC or SAML), or the issuer or entity ID it trusts. Disconnecting SSO and setting it up again counts as a switch too, even with the same provider. A new signing certificate or a new list of verified domains does not.

While SSO is enforced you cannot switch. CloudRepo refuses a change to another protocol, or to another issuer or entity ID, with sso_enforced_same_idp_required (status 409), and saves nothing. To update a certificate or a client secret, keep the same protocol and exactly the same SAML entity ID or OIDC issuer URL. Disconnecting SSO is refused too while it is enforced, so there is no way round it. A switch can therefore happen only while SSO is not enforced, and the rest of this section describes what follows one.

After a switch, tokens that members created after signing in through the old provider stop working with idp_switched, and they stay refused if you enforce SSO afterwards. The one exception is a token created before CloudRepo began recording how each token’s creator signed in: while SSO is not enforced, a switch does not stop it, and it keeps working until it expires. Enforcing SSO stops it with sso_enforced. Allow SSO sign-in again for each member, as in step 8, and ask each member to create a new token after signing in through the new provider, as in step 9. A member who signs in through the new provider before you allow them again is refused with Your email address is linked to a different identity provider account, so this sign-in was refused. Subscriber keys and your organization’s service keys keep working.

When a member leaves

Delete them in CloudRepo, on the Users page. Their password and their tokens stop working. Removing someone only in your identity provider ends their sign-ins through it and nothing else: their tokens keep working until they expire, and a token can be set to never expire, so delete them in CloudRepo too. Subscriber keys they created, and your organization’s service keys, keep working.

If your organization uses Okta’s SCIM provisioning today, deactivate the old user in Okta before you give their address to someone new. If you reuse the old user instead, the new person gets the old user’s write and manage permissions, role bindings, groups and, at the same address, its tokens.

Refusals, and how to fix each one

These are the refusals the changes in this guide can cause. Each heading is the code in CloudRepo’s answer (for a sign-in, the code at the end of the sign-in page’s address), so you can search this page for it. Docker’s MFA refusal is the one exception: it carries the registry code UNAUTHORIZED.

You see	Where	Go to
`Password authentication is disabled because MFA is required for this organization.`	A build tool, with a password	`mfa_required`
`401 Unauthorized`, the same answer as a wrong password	A build tool, with the password of a member who has a second factor	A plain 401
`Password access is refused: SSO is enforced for this organization.`	Maven, npm or pip, with a password	`sso_enforced`
`This token was not created after a sign-in through this organization's current identity provider`	Maven, npm or pip, with a token	`sso_enforced`
`denied: Password access is refused: SSO is enforced for this organization.` or `denied: This token was not created after a sign-in through this organization's current identity provider`	Docker, with a member’s password or token	`sso_enforced`
This organization signs in with SSO.	The CloudRepo sign-in page	`sso_enforced`
Your organization has to make a change before you can sign in with SSO	The CloudRepo sign-in page, after your identity provider	`sso_link_required`
`This token was created after a sign-in through an identity provider this organization no longer uses.`	A build tool, with a token	`idp_switched`
Your email address is linked to a different identity provider account, so this sign-in was refused.	The CloudRepo sign-in page, after a switch	`idp_switched`
`SSO configuration is temporarily unavailable.`	A build tool	`sso_config_unavailable`
Set up two-factor authentication on your own account first	SSO Settings	`owner_mfa_required_before_sso_enforce`
Your organization requires multi-factor authentication, so it cannot be turned off for your account.	Your account security	`org_mfa_required`
Your organization enforces single sign-on, so the owner’s multi-factor authentication cannot be removed or reset.	Your account security, for the owner	`sso_enforced_owner_mfa_required`

Many build tools print only the status, such as 401 Unauthorized or 403 Forbidden, and not the sentence. To read the sentence, repeat the request with curl, and enter your password or token when it asks:

curl --include --user you@example.com https://your-org.mycloudrepo.io/repositories/your-repo/

`mfa_required`

What you see, from Maven, Gradle, npm or pip (status 401):

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

From Docker (status 401, error code UNAUTHORIZED):

Password authentication is disabled because MFA is required for this organization. Use an API token instead. Create one at https://admin.cloudrepo.io

Why: your organization requires MFA, and the build signed in with a member’s password.

Fix: move the build to a service key, as in Service keys for your pipelines. For a member’s own machine, the member creates a repository token, the credential the message calls an API token. Repository tokens shows where a token goes for each build tool.

A plain 401 after a member sets up a second factor

What you see (status 401): 401 Unauthorized, the same answer as for a wrong password. It names no cause. Docker’s is the registry error UNAUTHORIZED, “authentication required”. A wrong password gets this answer too, and so does the right one.

Why: the member’s account has a second factor, and build tools cannot use the password of an account that does. CloudRepo does not say so in its answer, so the answer tells nobody who has a second factor.

Fix: sign in to the build tool with a repository token instead of the password. The member creates one under Repository Tokens, and Repository tokens shows where it goes for each build tool. A repository token keeps working, and so do subscriber keys and your organization’s service keys.

`sso_enforced`

Your organization enforces SSO. What you see depends on what was refused:

Where	What you see (status 403)	Fix
Maven, npm or pip, with a password	`Password access is refused: SSO is enforced for this organization. Sign in with SSO and create a repository token.`	A pipeline moves to a service key. A member signs in through your identity provider and creates a repository token for their own machine.
Maven, npm or pip, with a token	`This token was not created after a sign-in through this organization's current identity provider, and SSO is enforced. Sign in with SSO and create a new repository token.`	The same: a service key for a pipeline, or a new token the member creates as in step 9.
Docker, with a member’s password	`denied: Password access is refused: SSO is enforced for this organization. Sign in with SSO and create a repository token.`	The same as for Maven, npm or pip with a password.
Docker, with a member’s token	`denied: This token was not created after a sign-in through this organization's current identity provider, and SSO is enforced. Sign in with SSO and create a new repository token.`	The same as for Maven, npm or pip with a token.
`docker pull` of a public repository without `docker login`	No error	A public repository still serves anonymous pulls when SSO is enforced; only private repositories need a credential.
The CloudRepo sign-in page, with a password	This organization signs in with SSO. and a Sign In via SSO button	Click Sign In via SSO. If the page asks you to contact your administrator instead, ask your organization owner.
Creating or rotating a repository token	This action is not available in SSO-enforced orgs for non-owners; contact your administrator. or `Repository token mint is unavailable; SSO is enforced for this organization. Non-owner identities must obtain tokens via SSO-authenticated workflows.`	Sign out, sign in again through your identity provider, and create the token from that session.
Creating a user	Your organization signs members in through its identity provider, so users cannot be created here.	Add the person through your identity provider instead.

`sso_link_required`

What you see, on the CloudRepo sign-in page after signing in through your identity provider:

Your organization has to make a change before you can sign in with SSO, so signing in again will not work yet. Contact your organization’s administrator.

Why: CloudRepo already holds something at this member’s address, such as their CloudRepo account, an invitation, or a record your identity provider added through SCIM, and the owner has not allowed SSO sign-in for it. An allowance also lapses when the member does not sign in within 7 days. With OIDC, a member you invited is refused too when the ID token does not say your identity provider verified their address. Microsoft Entra ID’s ID token does not say so by default.

Fix: the owner allows SSO sign-in for this member on SSO Settings, under Member SSO sign-in, as in step 8, and the member signs in through your identity provider within 7 days.

`idp_switched`

What you see (status 403):

This token was created after a sign-in through an identity provider this organization no longer uses. Sign in again and create a new token.

Why: your organization switched identity providers, and this token was created after a sign-in through the old one. This happens whether or not SSO is enforced.

Fix: the member who owns the token signs in through your current identity provider and creates a new token, as in step 9. If their sign-in is refused with Your email address is linked to a different identity provider account, so this sign-in was refused. (code subject_id_mismatch), the owner allows SSO sign-in for them again, as in step 8, and they sign in again.

`sso_config_unavailable`

What you see (status 503):

SSO configuration is temporarily unavailable. Please retry shortly.

A build tool may show only the status, 503, and no sentence.

Why: CloudRepo could not read your organization’s MFA and SSO settings for this request.

Fix: run the build again. If it keeps failing, contact support@cloudrepo.io.

`owner_mfa_required_before_sso_enforce`

What you see, on SSO Settings:

When you click Enforce SSO: Set up two-factor authentication on your own account first: SSO can be enforced only once the owner has a second factor.
Under Member SSO sign-in: Set up two-factor authentication on your own account first: allowing SSO sign-in needs a code from your authenticator app.

Why: enforcing SSO and allowing SSO sign-in both need the owner to have a second factor.

Fix: set up a second factor on your own account, as in step 2, then try again.

`org_mfa_required`

What you see, when you try to turn off MFA for your own account:

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

Why: while the organization requires MFA, nobody can remove their own second factor, the owner included.

Fix: keep your second factor. If you lost your authenticator, sign in with one of your backup codes. An owner who wants MFA off for their own account first turns off Require MFA for password logins.

`sso_enforced_owner_mfa_required`

What you see, when the owner tries to remove or reset their own second factor:

Your organization enforces single sign-on, so the owner’s multi-factor authentication cannot be removed or reset.

Why: once SSO is enforced, the owner’s password and second factor are how the owner signs in, so CloudRepo keeps the second factor in place.

Fix: keep your second factor and your backup codes safe. If you lose your authenticator and have no backup codes left, the way back is below.

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.

While your organization enforces single sign-on, there is no other administrator who can confirm: your other administrators sign in through your identity provider.