> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudcapital.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Single sign-on (SSO)

> Set up OIDC-based single sign-on for your Cloud Capital organization.

Single sign-on (SSO) allows your team to authenticate with Cloud Capital using your organization's identity provider via OpenID Connect (OIDC). You can enable SSO through self-service in **Organization Settings**.

<Tip>
  For a broader overview of how Cloud Capital handles authentication, data access, and security controls, see the [Security](/security) page.
</Tip>

## Prerequisites

* You must be an organization admin in Cloud Capital.
* You need access to your identity provider's admin console to create an OIDC application and retrieve its configuration values.
* You need access to your domain's DNS settings to add a verification record.

<Tip>
  Before configuring your identity provider, navigate to **Organization Settings → SSO** to find Cloud Capital's **Redirect URI**. You will need the following values when creating the OIDC application in your IdP:

  | Field                     | Value                                                  |
  | ------------------------- | ------------------------------------------------------ |
  | Redirect / Callback URI   | `https://app.cloudcapital.co/api/v1/auth/sso/callback` |
  | Initiate Login URI (Okta) | `https://app.cloudcapital.co/v1/auth/sso/initiate`     |
</Tip>

## Set up SSO

<Steps>
  <Step title="Open SSO settings">
    Navigate to **Organization Settings** and select the **SSO** tab.
  </Step>

  <Step title="Configure your OIDC provider">
    Enter the following values from your identity provider:

    * **Issuer URL** — the OIDC issuer URL from your identity provider (e.g., `https://accounts.google.com` or `https://login.microsoftonline.com/{tenant}/v2.0`).
    * **Client ID** — the client identifier assigned to Cloud Capital in your identity provider.
    * **Client Secret** — the client secret generated for the Cloud Capital application.
    * **Email Domain** — the email domain for users who should sign in via SSO (e.g., `yourcompany.com`).

    <Warning>
      Cloud Capital validates that the issuer URL belongs to a recognized identity provider domain. If your organization uses a **custom or vanity domain** for your IdP (for example, a company-branded Okta URL like `https://login.yourcompany.io/` instead of `https://yourcompany.okta.com/`), you may see an "Untrusted origin" error. Contact [Cloud Capital support](mailto:support@cloudcapital.co) to have your domain added to the allowlist.
    </Warning>

    The SSO settings page displays Cloud Capital's **Redirect URI** (`https://app.cloudcapital.co/api/v1/auth/sso/callback`). Make sure this value is added as an allowed redirect/callback URI in your identity provider's OIDC application settings.
  </Step>

  <Step title="Verify your domain">
    Add the DNS record displayed in the SSO settings to your domain's DNS configuration. This verifies that you own the domain and allows Cloud Capital to associate SSO logins with your organization.

    <Note>
      DNS propagation can take up to 48 hours, though it typically completes within a few minutes.
    </Note>
  </Step>

  <Step title="Choose an enforcement mode">
    Select how SSO is enforced for your organization:

    * **Optional** — members can sign in with SSO or with their existing email and password. Use this while rolling out SSO or if some users need non-SSO access.
    * **Required** — all members must sign in through SSO. Email and password login is disabled for your organization.
  </Step>

  <Step title="Save your configuration">
    Click **Save** to enable SSO. Members matching your verified domain will be able to sign in using your identity provider on their next login.
  </Step>
</Steps>

## User provisioning

When a user signs in via SSO for the first time, Cloud Capital automatically creates an account for them using their identity provider profile. New SSO-provisioned users are granted **member** permissions by default.

If a user requires **admin** access, an existing organization admin must update their role manually after their first sign-in. To do this, navigate to **Organization Settings → Members**, find the user, and update their role.

<Note>
  Cloud Capital uses SP-initiated OIDC. Users can sign in from the Cloud Capital login page, or from an Okta app tile using the Initiate Login URI above — Okta redirects to Cloud Capital, which then starts the authorization flow. True IdP-initiated SAML (where the IdP sends an assertion without a prior request) is not supported.
</Note>

## Common identity providers

Most OIDC-compliant identity providers work with Cloud Capital SSO, including:

* Google Workspace
* Microsoft Entra ID (Azure AD)
* Okta
* Auth0
* OneLogin

Refer to your identity provider's documentation for instructions on creating an OIDC application and retrieving the issuer URL, client ID, and client secret.

## Okta configuration

Okta OIDC apps require two URLs to be configured — one for the OAuth callback, and one for the Okta app tile launch. Missing the second URL means SSO works from the Cloud Capital login page but fails when users click the app icon in their Okta dashboard.

In your Okta OIDC application settings, set the following:

| Okta field               | Value                                                  |
| ------------------------ | ------------------------------------------------------ |
| **Sign-in redirect URI** | `https://app.cloudcapital.co/api/v1/auth/sso/callback` |
| **Initiate Login URI**   | `https://app.cloudcapital.co/v1/auth/sso/initiate`     |
| **Login flow**           | Redirect to app to initiate login (OIDC Compliant)     |

The Initiate Login URI is the entry point for Okta-dashboard-launched sign-ins. Okta appends an `iss` query parameter identifying your Okta org, and Cloud Capital uses this to resolve your SSO configuration and start the authorization flow — ending at the same sign-in outcome as if the user had started from the Cloud Capital login page.

<Note>
  The **Sign-out redirect URI** and **Callback URI** fields in Okta are different things. Only the Sign-in redirect URI listed above needs to be set for Cloud Capital SSO to function.
</Note>

## Troubleshooting

| Issue                                    | Solution                                                                                                                                                                                        |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Domain verification pending              | Confirm the DNS record matches the value shown in SSO settings. Allow time for DNS propagation.                                                                                                 |
| Login fails after enabling SSO           | Verify the issuer URL, client ID, and client secret are correct. Check that `https://app.cloudcapital.co/api/v1/auth/sso/callback` is set as an allowed redirect URI in your identity provider. |
| Users not prompted for SSO               | Ensure enforcement is set to **Required**, or confirm the user's email domain matches the verified domain.                                                                                      |
| "Untrusted origin" error on issuer URL   | Your IdP uses a custom or vanity domain that isn't on Cloud Capital's allowlist. Contact [support](mailto:support@cloudcapital.co) to have it added.                                            |
| Okta app tile doesn't redirect correctly | Set the **Initiate Login URI** in your Okta OIDC app to `https://app.cloudcapital.co/v1/auth/sso/initiate` and set **Login flow** to "Redirect to app to initiate login (OIDC Compliant)".      |