# Move from legacy Okta to Okta SSO and SCIM

> Move your organization off the legacy Okta integration onto single sign-on with Okta, keeping the same SCIM connection and your builds running.

This guide moves an organization from CloudRepo’s legacy Okta integration to single sign-on (SSO) with Okta. Okta’s SCIM connection stays as it is, and the steps run in an order that keeps your builds working. It names who does each step, what stops and what keeps working at each change, and what each refusal means.

## Is this page for you

It is if, in the admin portal, the **SCIM Provisioning** page shows a card headed **Legacy Okta SCIM**. On that integration, Okta provisions your members, and each member signs in to CloudRepo with the password Okta set for them, if it set one.

Nothing changes until your organization’s owner chooses to move. An organization that stays on the legacy integration goes on working as it does today.

Before you give a departed person’s address to someone new, deactivate the old user in your identity provider first. Then assign the address again, and CloudRepo adds them as a new member. If you reuse the old user instead, CloudRepo can’t tell that apart from the same person editing their profile: the new person gets everything the old user held, and the old user’s tokens and sessions keep working.

## The short version

- The move is one click by the owner, after a plan that names what it keeps and what it ends. It is one way: there is no going back to the legacy integration.
- At the move, each member who has a password from Okta keeps it, for signing in to CloudRepo and for Maven, npm and pip. Members keep their permissions, write and manage included.
- At the move, every repository token a member made before it stops working, members are signed out of CloudRepo once, and old CloudRepo accounts end: those at addresses Okta does not hold as active members, and those at another spelling of a member’s address. The plan lists both.
- The move does not change your organization’s service keys, its subscriber keys, Okta’s SCIM connection (the same base URL and the same key), or you, the owner.
- Until you turn on SSO, nobody Okta adds or reactivates after the move can sign in or build, and you cannot rotate the SCIM key. So have the Okta app ready before you move, and turn on SSO right after.
- Once SSO is on, you allow each member to sign in through Okta, which ends their CloudRepo password, and members create new repository tokens after signing in through Okta.

## Who does what

| Who                                             | What they do                                                                                                                                                                   |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| The organization owner                          | Reads the plan, moves the organization, sets up and turns on SSO, allows each member to sign in through Okta, and decides whether to enforce SSO. Only the owner can do these. |
| Your Okta administrator                         | Creates the OIDC app in Okta and assigns it the people who use CloudRepo. Keeps the Okta app that provisions CloudRepo today, and later turns off its password sync.           |
| Each member who builds with their Okta password | After the move, moves those builds to a repository token. After signing in through Okta, creates new tokens.                                                                   |
| Whoever owns your pipelines                     | Before the move, and once the owner has a second factor, moves every shared pipeline that signs in with a member’s Okta password to an organization service key.               |

## Before you move

1. If any pipeline signs in to CloudRepo with your own password, first create a [repository token](/docs/authenticate/repository-tokens.html#create-a-token-in-the-admin-portal) and move those pipelines to it.

   Expected: no pipeline signs in to CloudRepo with your own password, and each pipeline you moved passes with your repository token.

2) Sign in as the owner and set up a second factor on your own account, as step 2 of [Turn on MFA and SSO without breaking your builds](/docs/authenticate/mfa-and-sso.html#before-you-change-anything) shows.

   Expected: your next sign-in asks for a code from your authenticator app. CloudRepo asks for that code before it lets you make an organization token on **Repository Tokens** in step 3, before it lets you allow members to sign in through Okta, and before it lets you enforce SSO.

3. Find every shared pipeline that signs in to CloudRepo with a member’s Okta password, and every pipeline you moved to your repository token in step 1 of this guide.

   Move each to an organization token, made by the owner or an Admin on **Repository Tokens** as [Service Keys for Your Pipelines](/docs/authenticate/repository-tokens.html#service-keys-for-your-pipelines) shows.

   Do not move a pipeline to a member’s own repository token yet: every token a member makes before the move stops working at the move.

   Expected: each pipeline passes with its service key, and no CI secret holds an Okta password. Service keys keep working through the move and through every later step in this guide.

4) Once every pipeline passes with its service key, revoke the repository token from step 1, if you made one, on the **Repository Tokens** page.

   Expected: each pipeline you moved in step 1 still passes, now with its service key.

5. In the sidebar, click **Security**, then click the **SCIM Provisioning** card. On the **Legacy Okta SCIM** card, click **Move to modern SSO**.

   Expected: a dialog headed **Move to modern SSO?** shows your organization’s own plan, under **What stops working**, **What keeps working** and **Who builds with an Okta password**. Opening it changes nothing. Note the members it names, then click **Cancel**.

   If the plan says Okta has not finished removing some members, the move is refused until it has: in Okta, deactivate or delete each of them again. If it lists members under **Inactive in Okta**, their accounts carry write or manage permissions; if Okta reactivates one after the move, they come back read-only until you grant more.

6) On **SSO Settings**, choose **Okta**: the page shows the values your identity provider’s app for CloudRepo needs, its redirect URI among them, as step 9 of [Turn on SSO, then enforce it](/docs/authenticate/mfa-and-sso.html#turn-on-sso-then-enforce-it) in the SSO guide shows. Give them to your Okta administrator, who creates an OIDC app for CloudRepo in Okta with them. They assign the new app the same people, or the same Okta group, as the Okta app that provisions CloudRepo today, and keep that app: the move reuses it.

   Expected: Okta lists the new OIDC app with your people assigned, and your administrator has the client ID, the client secret and the issuer for step 8. Nothing in CloudRepo has changed.

## Move to modern SSO

7. On the **Legacy Okta SCIM** card, click **Move to modern SSO** again, read the plan, and click **Move to modern SSO** in the dialog. In **Confirm Your Identity**, enter the code from your authenticator app under **Authenticator Code** and click **Confirm**.

   Expected: the **Legacy Okta SCIM** card is replaced by a card headed **SCIM Endpoint**, which says **SCIM is on: CloudRepo accepts your organization’s SCIM key at this base URL.** and **To rotate the SCIM key, turn on single sign-on first.** Okta goes on provisioning through the same base URL and the same key.

   The move ends exactly what the plan showed. If the accounts or tokens you reviewed changed before you confirmed, nothing moves and you are asked to review again.

What the move does:

- Members who are signed in to CloudRepo are signed out. They sign in again with the same password.
- Every repository token a member made before the move stops working. Members make new ones after it.
- Old CloudRepo accounts at addresses Okta does not hold as active members end, with their passwords. So do accounts at another spelling of your own address (the same address with different capital letters). The plan named each of these.
- Accounts at another spelling of a member’s address end too, with their passwords, and the plan names each of them. Anyone who signs in with such a spelling loses that account, so put any build that signs in with one on a service key before you move, as in step 3.
- A password change that Okta sends after the move no longer changes a member’s CloudRepo password.
- Members with no password from Okta still cannot sign in. They can once SSO is on and you allow them to sign in through Okta.

## After the move

### Turn on SSO

8. Set up and turn on SSO with OIDC, using the client ID, the client secret and the issuer from step 6, as step 9 of [Turn on SSO, then enforce it](/docs/authenticate/mfa-and-sso.html#turn-on-sso-then-enforce-it) in the SSO guide shows. Do not set up SCIM again: your existing SCIM app goes on provisioning as before.

   Expected: **SSO Settings** shows the **Enabled** badge. Your members’ passwords, and any tokens they made after the move, still work in build tools. On the **SCIM Provisioning** page, the SCIM key can now be rotated with **Regenerate Token**.

### Move each member to SSO

9. Each member who builds with their Okta password signs in to CloudRepo with that password, creates a repository token as [Create a token in the admin portal](/docs/authenticate/repository-tokens.html#create-a-token-in-the-admin-portal) shows, and puts the token where the password was. Start with the members the plan listed under **Who builds with an Okta password**. That list holds only the Maven, npm and pip builds CloudRepo saw after it began recording them, so ask every member, not only the ones it names.

   Expected: every build passes with a token, and none uses an Okta password. Do this for a member before step 10, which ends their password.

10) 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: every member with write or manage permissions is one of them. Each click opens its own dialog, headed **Allow SSO sign-in for this member?**, where you click **Allow SSO sign-in** and enter another code from your authenticator app, so expect one code for each of these members.

    Expected: the dialog says, before you confirm, that each member’s CloudRepo password and open sessions end and that the repository tokens they created keep working. So the tokens from step 9 go on working. A member you allow has 7 days to sign in through Okta for the first time.

11. Ask each member to sign in through Okta: they go to `https://admin.cloudrepo.io/login`, enter your organization ID and click **Continue**. If you plan to enforce SSO, each member then creates new repository tokens from that session, as step 11 of [Turn on MFA and SSO without breaking your builds](/docs/authenticate/mfa-and-sso.html#turn-on-sso-then-enforce-it) shows, and replaces the ones from step 9.

    Expected: members reach CloudRepo through Okta, with the permissions they had before the move. A member refused with *Your organization has to make a change before you can sign in with SSO* has not been allowed yet: repeat step 10 for them.

### Turn off password sync in Okta

12. Ask your Okta administrator to open the Okta app that provisions CloudRepo and, in its provisioning settings, turn off password sync (in Okta, *Sync Password*) if it is on.

    Expected: Okta shows password sync as off for that app. Nothing changes in CloudRepo: since the move, a password Okta sends does not change what any member signs in with.

### Enforce SSO (optional)

13. If every member signs in through Okta and every build uses a service key or a token made after an Okta sign-in, you can enforce SSO. Follow steps 12 to 14 of [Turn on MFA and SSO without breaking your builds](/docs/authenticate/mfa-and-sso.html#turn-on-sso-then-enforce-it), and read its warnings first: enforcing is one way.

    Expected: **SSO Settings** shows the **Enforced** badge. Builds that use a service key, a subscriber key, or a token made after an Okta sign-in keep working; a password or a token made from a password sign-in is refused.

## What keeps working

Each row is a change, in the order this guide makes them. Each column is a credential a build can use. *Works* means the credential works wherever it worked before the change.

- *Password*: a member’s password from Okta, at the CloudRepo sign-in page and in Maven, npm and pip.
- *Old token*: a repository token a member made before the move.
- *Token, password sign-in*: a repository token a member made after the move while signed in with a password.
- *Token, Okta sign-in*: a repository token a member made after signing in through Okta.
- *Keys*: your organization’s service keys and its subscriber keys.

| Change                                 | Password              | Old token           | Token, password sign-in | Token, Okta sign-in | Keys  |
| -------------------------------------- | --------------------- | ------------------- | ----------------------- | ------------------- | ----- |
| Move to modern SSO                     | Works                 | Stops               | None yet                | None yet            | Works |
| Turn on SSO                            | Works                 | Stopped at the move | Works                   | Works               | Works |
| Allow a member to sign in through Okta | Stops for that member | Stopped at the move | Works                   | Works               | Works |
| Enforce SSO                            | Stops                 | Stopped at the move | Stops                   | Works               | Works |

`docker login` always takes a repository token or a service key, never a password.

A member who sets up a second factor on their own account after the move can no longer use their password in build tools, as [A plain 401 after a member sets up a second factor](/docs/authenticate/mfa-and-sso.html#a-plain-401-after-a-member-sets-up-a-second-factor) explains. You, the owner, are not changed by any row: you sign in with your password and your second factor, never through Okta.

## Until SSO is on

Between the move and step 8, three things differ from the legacy integration:

- Anyone Okta adds or reactivates after the move cannot sign in to CloudRepo or build until SSO is on. Someone Okta adds after the move, or a member it held as inactive at the move and then reactivates, has read-only access once they can sign in, until you grant more.
- You cannot rotate the SCIM key. The **SCIM Endpoint** card says **To rotate the SCIM key, turn on single sign-on first.**
- Okta’s password changes no longer reach CloudRepo, as the move section says.

So keep this window short: have the Okta app ready before you move (step 6), and turn on SSO right after (step 8).

## People Okta adds after SSO is on

Once SSO is on, a person Okta adds after the move signs in through Okta with read-only access, and you grant them more if they need it. Whether they need your allowance first depends on how CloudRepo connects to Okta:

- With OIDC, as steps 6 and 8 set it up, they sign in through Okta without an allowance.
- With SAML, each of them needs your allowance first: on **SSO Settings**, under **One member**, enter their address and click **Allow SSO sign-in**, or click **Allow SSO sign-in for all members** again.

Members the move converted always need your allowance, as in step 10.

## Turning SCIM off

After the move you can turn SCIM off on the **SCIM Provisioning** page, before or after you turn on SSO, with **Turn SCIM off**. CloudRepo refuses while Okta has not finished removing a member, and names them: finish those removals in Okta first. Once SCIM is off, Okta’s SCIM app can no longer add, change or remove members in CloudRepo, so remove anyone who leaves on the **Users** page yourself. To turn SCIM on again, SSO must be on.

Before the move, SCIM cannot be turned off: the legacy integration could not be turned back on.

## If something is refused

| You see                                                                                                                                    | Where                                                           | What it means, and what to do                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *Your organization is still on legacy Okta, so modern SSO is refused.* (`legacy_okta_modern_sso_refused`)                                  | **SSO Settings**, when you configure, turn on or enforce SSO    | The organization has not moved yet. Move it first (step 7).                                                                                                                                   |
| *Your organization still signs members in through the legacy Okta integration, so single sign-on was refused.* (`legacy_okta_sso_refused`) | The CloudRepo sign-in page, after Okta                          | The organization has not moved yet. Until the owner moves it, sign in with the CloudRepo password Okta set for you, if it set one.                                                            |
| *Okta has not finished removing …* (`scim_deprovision_pending`)                                                                            | The plan, or the **SCIM Provisioning** page after you confirm   | Nothing was moved. In Okta, deactivate or delete each member it names again, then move. Turning SCIM off is refused for the same reason.                                                      |
| *This organization is too large to move in one step* (`legacy_okta_convert_too_large`)                                                     | The plan, or the **SCIM Provisioning** page                     | Nothing was moved. Contact support.                                                                                                                                                           |
| *Your identity could not be confirmed, so nothing was moved.* (`confirmation_required`)                                                    | The **SCIM Provisioning** page, after **Confirm Your Identity** | Move again, and confirm your identity again.                                                                                                                                                  |
| *Your organization changed after you reviewed the plan, so nothing was moved.* (`legacy_okta_plan_changed`)                                | The plan, which opens again on the **SCIM Provisioning** page   | Something in your organization changed after you read the plan, in Okta or in CloudRepo, so nothing was moved. Read the plan again, then move and confirm your identity again.                |
| *Okta changed a member while the move was being prepared* (`scim_changed_retry`)                                                           | The **SCIM Provisioning** page                                  | Your members did not move, and the organization is still on legacy Okta. Old accounts the plan named may already have ended. Open the plan again, read it, and move again.                    |
| *The move stopped before it finished* (`legacy_okta_convert_incomplete`)                                                                   | The **SCIM Provisioning** page                                  | The same as above: still on legacy Okta, and old accounts the plan named may already have ended. Move again.                                                                                  |
| *Your organization is no longer on legacy Okta, so there is nothing to move.* (`not_legacy_okta`)                                          | The **SCIM Provisioning** page                                  | The move already happened, perhaps in another tab. Reload the page.                                                                                                                           |
| *CloudRepo could not read your organization’s settings* (`sso_model_unavailable`)                                                          | The **SCIM Provisioning** page                                  | Nothing was moved. Try again in a moment.                                                                                                                                                     |
| *CloudRepo could not confirm the move.*                                                                                                    | The **SCIM Provisioning** page                                  | The answer was lost. Reload the page: a **SCIM Endpoint** card means the move happened, and the **Legacy Okta SCIM** card means it did not.                                                   |
| `legacy_okta_scim_off_refused`                                                                                                             | The CloudRepo API, when SCIM is turned off before the move      | The legacy integration cannot be turned off and back on, so SCIM stays on. Move first; then you can turn SCIM off.                                                                            |
| *Your organization has to make a change before you can sign in with SSO* (`sso_link_required`)                                             | The CloudRepo sign-in page, after Okta                          | The owner has not allowed this member yet, or the allowance lapsed after 7 days. The owner repeats step 10. See [`sso_link_required`](/docs/authenticate/mfa-and-sso.html#sso_link_required). |
| **The owner signs in with a password. Choose Sign in with a password.** (`owner_password_required`)                                        | The CloudRepo sign-in page, after Okta                          | The owner never signs in through Okta. Sign in with your password and second factor.                                                                                                          |
| `sso_enforced`                                                                                                                             | A build tool, after you enforce SSO                             | The build uses a password or a token made from a password sign-in. See [`sso_enforced`](/docs/authenticate/mfa-and-sso.html#sso_enforced).                                                    |

---

The page: https://www.cloudrepo.io/docs/authenticate/sso/move-from-legacy-okta.html
