# Single sign-on with Okta

> Connect Okta to CloudRepo with OIDC, step by step, so the people in your Okta organization sign in to CloudRepo through Okta.

Connect your Okta organization to CloudRepo with OpenID Connect (OIDC) so your team signs in through Okta. Each step shows what you should see before you go on.

## Before you start

1. Sign in to CloudRepo as your organization’s owner, with a second factor set up. If you have not set one up yet, do the steps in [Before you change anything](/docs/authenticate/mfa-and-sso.html#before-you-change-anything) first: they keep your builds working.

   Expected: your sign-in asks for a code from your authenticator app.

2. Check that you can sign in to the Okta Admin Console as an administrator who can create app integrations.

   Expected: you can open the *Applications* page in the Okta Admin Console.

## Copy the redirect URI from CloudRepo

1. In the sidebar, click **Security**, then **Single sign-on**. Under **Which identity provider do you use?**, choose Okta.

   Expected: a box headed **For your identity provider** shows a **Redirect URI** and the line **In Okta, add this under Sign-in redirect URIs.** Below it is the form you fill in later.

2. Copy the **Redirect URI**. Leave this page open.

   Expected: you have an address that ends in a long ID. That address belongs to your organization alone, so paste it exactly, with nothing added.

## Create the app in Okta

1. In the Okta Admin Console, open the *Applications* page and click *Create App Integration*. Choose *OIDC* (OpenID Connect) as the sign-in method and *Web Application* as the type, then click *Next*.

   Expected: Okta shows the settings for a new web app integration.

2. Set *App integration name* to `CloudRepo`. Under *Grant type*, keep *Authorization code* checked. In *Sign-in redirect URIs*, replace the example with the **Redirect URI** you copied.

   Expected: *Sign-in redirect URIs* holds one address, the same as the **Redirect URI** in CloudRepo, character for character.

3. Under *Assignments*, choose who can use CloudRepo: everyone in your Okta organization, or the groups you pick. Click *Save*.

   Expected: the app’s *General* tab, with a *Client ID* under *Client Credentials*.

4. Copy the *Client ID*. Under *Client authentication*, choose *Client secret* if it is not chosen already, and copy the secret. If Okta shows no secret yet, click *Save* to make one.

   Expected: you have the client ID and the client secret.

## Connect CloudRepo to Okta

1. Back on **SSO Settings** in CloudRepo, fill in the form:

   - **Issuer URL**: your Okta organization’s address, such as `https://your-okta-org.okta.com`. Do not add `/oauth2/default`.
   - **Client ID** and **Client Secret**: the two values you copied from Okta.
   - **Verified Domains**: the email domains your people sign in with, such as `example.com`. Only addresses at these exact domains can sign in with SSO.
   - **Scopes**: leave it empty.

   Click **Save**. In **Confirm Your Identity**, enter the code from your authenticator app under **Authenticator Code** and click **Confirm**.

   Expected: the **Identity Provider** card shows your settings and the **Disabled** badge. Saving does not turn SSO on.

2. Click **Enable SSO**, and confirm your identity the same way.

   Expected: a banner reads **SSO enabled.**, and the badge reads **Enabled**.

## Sign in as one person first

1. Pick one person who can use the app in Okta, whose address is at one of your verified domains, and who has no CloudRepo account or invitation yet. Ask them to go to `https://admin.cloudrepo.io/login`, enter your organization ID, click **Continue**, and sign in at Okta.

   Expected: they land in the admin portal, signed in as themselves. CloudRepo made their account at this first sign-in.

Then finish the rollout in the SSO guide:

- For people who already have a CloudRepo account, or an invitation: allow SSO sign-in for the person first, before their first sign-in through Okta, as in [step 10](/docs/authenticate/mfa-and-sso.html#turn-on-sso-then-enforce-it). Read that step before you click: it says what changes for them.
- Each member then creates new repository tokens after signing in through Okta, as in step 11.
- When you are ready to enforce SSO, steps 12 to 14 say what to check first.

## If a sign-in does not finish

- Okta shows its own error page instead of sending you back to CloudRepo: open the app’s *General* tab in Okta and compare *Sign-in redirect URIs* with the **Redirect URI** on **SSO Settings**. They must match character for character. Fix the Okta side: you do not need to change anything in CloudRepo.
- CloudRepo says *Your organization has to make a change before you can sign in with SSO*: that person already has a CloudRepo account or an invitation. Allow SSO sign-in for them, as [`sso_link_required`](/docs/authenticate/mfa-and-sso.html#sso_link_required) shows.

Every other refusal, and how to fix it, is in [Refusals, and how to fix each one](/docs/authenticate/mfa-and-sso.html#refusals-and-how-to-fix-each-one).

## Provision members with SCIM

To have Okta add and remove your members for you, connect SCIM as [SCIM provisioning with Okta or Entra ID](/docs/authenticate/scim.html#okta) shows. Members still sign in through the app you made here.

---

The page: https://www.cloudrepo.io/docs/authenticate/sso/okta.html
