Skip to content

Single sign-on with 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.

  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 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.

  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.

  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.

  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.

  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. 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.
  • 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 shows.

Every other refusal, and how to fix it, is in Refusals, and how to fix each one.

To have Okta add and remove your members for you, connect SCIM as SCIM provisioning with Okta or Entra ID shows. Members still sign in through the app you made here.

View as Markdown