# Turn on MFA and SSO without breaking your builds > Require MFA or enforce single sign-on for your CloudRepo organization while your Maven, Gradle, npm, pip and Docker builds keep working. 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](#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. > **Note:** Offboarding with SSO alone: when you remove someone from your identity provider, they can no longer sign in to CloudRepo through it. Sessions and tokens they already hold keep working until you also delete them in CloudRepo: Users, then the member, then Delete User. SCIM, coming soon, will do this for you. ## 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](/docs/authenticate/repository-tokens.html#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](#a-plain-401-after-a-member-sets-up-a-second-factor) | Works | Works | Works | Works | | You require MFA | Stops: [`mfa_required`](#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`](#sso_enforced) | Stops: [`sso_enforced`](#sso_enforced) | Works | Works | Works | | You switch identity providers | No change | No change | Stops if made through the old one: [`idp_switched`](#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](#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 1. 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](/docs/authenticate/repository-tokens.html#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. 2) 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. 3. In the sidebar, click **Security**, then click the **Organization MFA policy** card. Expected: the **MFA Enforcement** card, with a **Disabled** badge. 4. 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.** 5. 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. 6. 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`](#mfa_required). ### Turn on SSO, then enforce it 7. 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](#if-you-switch-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`](#sso_link_required), until you allow it in step 8. 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. 9. 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`](#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). 10) 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`](#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.** 11) 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. 12) Wait one minute, then run your builds. Expected: they pass. A build that fails with [`sso_enforced`](#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. > **Enforcing SSO is one way:** Once SSO is enforced, SSO Settings shows this notice: *SSO is enforced. Members sign in only through your identity provider, and this cannot be turned off from this page. If your identity provider is gone, or you need members to sign in with passwords again, contact from the owner’s address. We verify the request out of band before removing enforcement.* ### 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`](#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`](#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`](#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`](#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](#a-plain-401-after-a-member-sets-up-a-second-factor) | | `Password access is refused: SSO is enforced for this organization.` | Maven, npm or pip, with a password | [`sso_enforced`](#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`](#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`](#sso_enforced) | | *This organization signs in with SSO.* | The CloudRepo sign-in page | [`sso_enforced`](#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`](#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`](#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`](#idp_switched) | | `SSO configuration is temporarily unavailable.` | A build tool | [`sso_config_unavailable`](#sso_config_unavailable) | | *Set up two-factor authentication on your own account first* | SSO Settings | [`owner_mfa_required_before_sso_enforce`](#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`](#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`](#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: ```sh 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): ```text Password authentication is disabled because MFA is required for this organization. Use an API token instead. ``` From Docker (status 401, error code `UNAUTHORIZED`): ```text 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](/docs/authenticate/repository-tokens.html#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](/docs/quick-start/repository-tokens.html) 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](/docs/quick-start/repository-tokens.html) 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): ```text 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](#if-you-switch-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): ```text 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 . ### `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 : 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. --- The page: https://www.cloudrepo.io/docs/authenticate/mfa-and-sso.html