Skip to main content

Set up single sign-on (SSO)

Single sign-on (SSO) lets users in your organization sign in to the Crusoe Cloud Console with your company identity provider instead of a separate Crusoe Cloud password. When you require SSO for a user, Crusoe Cloud blocks password sign-in and other sign-in methods for that user. Their access then follows your identity provider's policies, such as multi-factor authentication and offboarding.

Crusoe Cloud supports Okta and Google Workspace as identity providers.

Prerequisites​

To set up SSO, you need:

  • The org-admin role in your Crusoe Cloud organization
  • SSO enabled for your organization—contact your Crusoe Cloud account team or Crusoe support, and tell them whether your organization uses Okta or Google Workspace
  • For Okta: administrator access to your Okta tenant
  • For Google Workspace: a Google Workspace account for each user who signs in

Connect Okta​

Okta SSO uses an OIDC app in your Okta tenant. Setup requires a handoff with Crusoe Customer Success. Crusoe stores your app's client secret and then provides your sign-in redirect URI.

Use your organization's own email domains. Public email providers, such as gmail.com or outlook.com, aren't supported.

To connect Okta:

  1. To start Okta setup, contact your Crusoe Customer Success representative.
  2. In the Okta Admin Console, create an app integration. Set Sign-in method to OIDC - OpenID Connect and Application type to Web Application, leave the Sign-in redirect URIs default, and save the app. You'll add the Crusoe Cloud redirect URI at the end of setup.
  3. Assign the users or groups that need access to Crusoe Cloud.
  4. Copy the app's Client ID, Client secret, and issuer URI. The issuer URI is your Okta domain—for example, https://example.okta.com.
  5. In the Crusoe Cloud Console, go to IAM > User Authentication.
  6. Click Add identity provider.
  7. For Provider type, select Okta.
  8. Enter the Client ID and Issuer URI.
  9. In Add email domains, enter each email domain your users sign in with, such as example.com. Separate multiple domains with commas.
  10. Click Save.
  11. Share the client secret with Crusoe Customer Success securely, such as in a 1Password secure note.
  12. After Crusoe configures the connection, Customer Success sends you the sign-in redirect URI. In your Okta app, add it to Sign-in redirect URIs and save.

Connect Google Workspace​

To connect Google Workspace:

  1. In the Crusoe Cloud Console, go to IAM > User Authentication.
  2. Click Add identity provider.
  3. For Provider type, select Google Workspace.
  4. Click Save.

Google Workspace SSO doesn't support just-in-time (JIT) provisioning, so Crusoe Cloud doesn't create accounts when users first sign in. Invite each user with their Google Workspace email address and set their Login method to SSO. Access is limited to the email addresses you invite. If a user signs in before you invite them, they get a separate personal account that isn't part of your organization. To fix this, see Users with an existing account.

Require SSO for users​

After you connect an identity provider, require SSO for each user who must sign in through it. The requirement applies per user, so you can keep one admin account with password sign-in for emergency access while everyone else uses SSO.

warning

Test SSO before you require it for everyone. Require SSO for one account, and confirm that it can sign in through your identity provider.

To require SSO for an existing user:

  1. In the Crusoe Cloud Console, go to IAM > Team.
  2. Open the actions menu for the user and click Edit Auth.
  3. For Login method, select SSO.
  4. To confirm the change, enter your organization name and click Save.

To require SSO for a new user, select SSO for Login method when you invite the user.

The change applies the next time the user signs in. After you require SSO, sign-in works as follows:

  • Okta: The Crusoe Cloud sign-in page sends the user to Okta. Crusoe Cloud blocks password sign-in and social sign-in.
  • Google Workspace: The user signs in with their Google Workspace account. Crusoe Cloud blocks password sign-in and other sign-in methods.

To remove the requirement, set Login method to Password/Social. If the user has no password, Crusoe Cloud emails them a link to create one.

How users sign in with SSO​

On the Crusoe Cloud sign-in page, a user enters their email address. If you require SSO for the user, Crusoe Cloud sends them to your identity provider. After they authenticate, they return to the Console.

With Okta, Crusoe Cloud uses JIT provisioning to create an account when a user assigned to your Okta app first signs in. New accounts have No org role. To give users access, assign organization or project roles. If you use SCIM provisioning, Okta creates accounts instead.

Users with an existing account​

A user who signed up for Crusoe Cloud with a password or social sign-in before you connected SSO has a separate account under the same email address. That account blocks them from joining your organization through SSO.

To move the user into your organization:

  1. Ask the user to shut down any resources in their existing account.
  2. Contact support to delete the existing account. Deletion removes the account's API keys and SSH keys.
  3. Make sure the user can join your organization:
    • Okta: Assign the user to your Okta app. Their email address must use one of the email domains you added for SSO.
    • Okta with SCIM: Assign the user to your SCIM app so Okta provisions them.
    • Google Workspace: Invite the user.
  4. Have the user sign in through SSO.

Update or remove an identity provider​

To change your identity provider's settings, switch providers, or remove SSO—contact support.

If you rotate the client secret for your Okta app, share the new secret with Crusoe Customer Success. SSO sign-in fails until Crusoe updates it.

Limitations​

  • SSO controls sign-in only. To sync roles from your identity provider, use SCIM provisioning with Okta.
  • Without SCIM, removing a user from your identity provider doesn't remove them from Crusoe Cloud. To remove their access, delete the user in IAM > Team.
  • Your organization can connect one identity provider at a time, either Okta or Google Workspace.

Troubleshooting​

The sign-in page shows these errors when SSO sign-in fails:

Error messageCause and resolution
Login failed: Your account requires SSO login. Social login is not permitted.The user's account requires SSO, but the user signed in with a social provider that isn't your organization's identity provider. The user must sign in with your organization's identity provider.
Login failed: Your account is not associated with this organization's SSO provider.The user's account belongs to a different organization than the identity provider they used. Verify that the user is a member of your organization.
Login failed: You are not authorized to access this application. Please contact your IT administrator.Your identity provider rejected the sign-in, usually because the user isn't assigned to the Crusoe Cloud app in Okta. Assign the user to the app.
Login failed: Your session could not be established. Please try again.The sign-in didn't complete. Try again in a private browser window. If every user sees this error, your Okta client secret might have changed. Contact support.
Login failed: The authentication request was invalid. Please try again.The sign-in redirect was interrupted, often by a browser extension. Try again in a private browser window.
Login failed: Your organization requires users to be provisioned via SCIM. Please contact your IT administrator.Your organization uses SCIM, and Okta hasn't provisioned the user. Assign the user to the Crusoe Cloud app in Okta.
Login failed: Your organization has reached its maximum number of users. Please contact your organization administrator.Your organization has reached its user limit. Remove unused accounts or contact support.

The Console shows these errors when you add an identity provider:

Error messageCause and resolution
org must have user with email domainCrusoe Cloud couldn't verify the domain for your organization. Check the domain for typos. If it's correct, contact support.
cannot create provider using common email domainThe domain is a public email provider. Use your company domain.
provider with these credentials already existsAn identity provider with this client ID already exists. To change it, contact support.
invalid issuer uri: must start with https://The issuer URI doesn't start with https://. Enter the full issuer URI, including https://.

For any other issue, including locked-out accounts, contact support.