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

# Single Sign-On (SSO)

> Configure SAML or OIDC SSO with Google Workspace, Azure AD, AWS IAM Identity Center, Okta, and more

Single Sign-On lets your team authenticate to CloudThinker using your existing identity provider — no separate passwords, automatic user provisioning, and centralized deprovisioning when someone leaves.

<Note>
  SSO is available on **Business** and **Enterprise** plans. To get started, navigate to **Organization Settings → Security → SSO** and click **Add Connection**.
</Note>

***

## How the Setup Wizard Works

The SSO wizard has three steps: **Protocol → SP Metadata → IdP Configuration**.

1. **Protocol** — Choose SAML 2.0 or OIDC
2. **SP Metadata** — Copy CloudThinker's values into your IdP when creating the SAML app
3. **IdP Configuration** — Paste your IdP's values back into CloudThinker

Use the tabs below to follow the exact steps for your identity provider.

***

## SAML Setup

<Tabs>
  <Tab title="Google Workspace">
    ### Google Workspace — SAML Setup

    <Steps>
      <Step title="Open the Google Admin Console">
        Go to [admin.google.com](https://admin.google.com) → **Apps → Web and mobile apps → Add app → Add custom SAML app**.
      </Step>

      <Step title="Name the App">
        Give it a name like **CloudThinker** and click **Continue**.
      </Step>

      <Step title="Download IdP Metadata">
        On the **Google IdP information** screen, download the **IdP metadata XML** or note:

        * **SSO URL** (Single Sign-On URL)
        * **Entity ID** (`https://accounts.google.com/o/saml2?idpid=...`)
        * **Certificate** (download the X.509 certificate)

        Click **Continue**.
      </Step>

      <Step title="Enter CloudThinker SP Details">
        Copy the values from **CloudThinker → Settings → Security → SSO → SP Metadata**:

        | Google Field       | CloudThinker Value                           |
        | ------------------ | -------------------------------------------- |
        | **ACS URL**        | Paste the **ACS URL** from CloudThinker      |
        | **Entity ID**      | Paste the **SP Entity ID** from CloudThinker |
        | **Name ID format** | `EMAIL`                                      |
        | **Name ID**        | `Basic Information > Primary email`          |

        Click **Continue**.
      </Step>

      <Step title="Configure Attribute Mapping">
        Add the following attribute mappings:

        | Google Directory Attribute | App Attribute |
        | -------------------------- | ------------- |
        | Primary email              | `email`       |
        | First name                 | `firstName`   |
        | Last name                  | `lastName`    |

        Click **Finish**.
      </Step>

      <Step title="Enable the App">
        In the app settings, set access to **On for everyone** (or target specific organizational units).
      </Step>

      <Step title="Complete Setup in CloudThinker">
        Back in CloudThinker's SSO wizard, paste in:

        * **Entity ID** from Google
        * **SSO URL** from Google
        * **Certificate** (paste the X.509 certificate content)

        Click **Create Connection** and then **Test** to verify.
      </Step>
    </Steps>

    <Tip>
      Use the **Import** field in CloudThinker to paste your Google IdP metadata URL — this auto-fills Entity ID, SSO URL, and Certificate in one step.
    </Tip>
  </Tab>

  <Tab title="Azure AD / Entra ID">
    ### Microsoft Azure AD (Entra ID) — SAML Setup

    <Steps>
      <Step title="Create an Enterprise Application">
        In the [Azure Portal](https://portal.azure.com), go to **Microsoft Entra ID → Enterprise applications → New application → Create your own application**.

        Name it **CloudThinker**, select **Integrate any other application you don't find in the gallery**, and click **Create**.
      </Step>

      <Step title="Set Up Single Sign-On">
        Open the new application → **Single sign-on → SAML**.
      </Step>

      <Step title="Enter Basic SAML Configuration">
        Click **Edit** on **Basic SAML Configuration** and fill in from CloudThinker's SP Metadata:

        | Azure Field                | CloudThinker Value         |
        | -------------------------- | -------------------------- |
        | **Identifier (Entity ID)** | Paste the **SP Entity ID** |
        | **Reply URL (ACS URL)**    | Paste the **ACS URL**      |
        | **Sign on URL**            | Same as ACS URL            |

        Save.
      </Step>

      <Step title="Configure Attributes & Claims">
        In **Attributes & Claims**, confirm the `emailaddress` claim maps to `user.mail`. Optionally add:

        * `firstName` → `user.givenname`
        * `lastName` → `user.surname`
      </Step>

      <Step title="Download the Federation Metadata">
        In **SAML Signing Certificate**, download the **Federation Metadata XML** or copy:

        * **App Federation Metadata URL** (recommended — use this to auto-import into CloudThinker)
        * **Certificate (Base64)**
        * **Login URL** (SSO URL)
        * **Azure AD Identifier** (Entity ID)
      </Step>

      <Step title="Assign Users and Groups">
        Go to **Users and groups → Add user/group** and assign who should have access to CloudThinker.
      </Step>

      <Step title="Complete Setup in CloudThinker">
        In CloudThinker's IdP Configuration step, use the **Import** field to paste the **App Federation Metadata URL** — this auto-fills all fields. Or enter manually:

        * **Entity ID**: Azure AD Identifier
        * **SSO URL**: Login URL
        * **Certificate**: Certificate (Base64)

        Click **Create Connection** and **Test**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="AWS IAM Identity Center">
    ### AWS IAM Identity Center (AWS SSO) — SAML Setup

    <Steps>
      <Step title="Open IAM Identity Center">
        In the [AWS Console](https://console.aws.amazon.com), navigate to **IAM Identity Center → Applications → Add application → Add custom SAML 2.0 application**.
      </Step>

      <Step title="Configure the Application">
        Give it a display name like **CloudThinker** and optionally add a description.
      </Step>

      <Step title="Download IAM Identity Center Metadata">
        In the **IAM Identity Center metadata** section, copy or download:

        * **IAM Identity Center SAML metadata file** (or the metadata URL)
        * **IAM Identity Center issuer URL**
        * **IAM Identity Center sign-in URL**
        * **Certificate**
      </Step>

      <Step title="Enter Application SAML Metadata">
        In the **Application metadata** section, paste values from CloudThinker's SP Metadata:

        | IAM Identity Center Field     | CloudThinker Value         |
        | ----------------------------- | -------------------------- |
        | **Application ACS URL**       | Paste the **ACS URL**      |
        | **Application SAML audience** | Paste the **SP Entity ID** |
      </Step>

      <Step title="Assign Users">
        Go to **Assigned users and groups** → **Assign users and groups** and select who should access CloudThinker.
      </Step>

      <Step title="Configure Attribute Mappings">
        In **Attribute mappings**, add:

        | User attribute in the application | Maps to this string value or user attribute in IAM Identity Center |
        | --------------------------------- | ------------------------------------------------------------------ |
        | `Subject`                         | `${user:email}` — Format: `emailAddress`                           |
        | `email`                           | `${user:email}`                                                    |
        | `firstName`                       | `${user:givenName}`                                                |
        | `lastName`                        | `${user:familyName}`                                               |
      </Step>

      <Step title="Complete Setup in CloudThinker">
        Back in CloudThinker, use **Import** to paste the IAM Identity Center metadata URL, or enter manually:

        * **Entity ID**: IAM Identity Center issuer URL
        * **SSO URL**: IAM Identity Center sign-in URL
        * **Certificate**: from the metadata file

        Click **Create Connection** and **Test**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Okta">
    ### Okta — SAML Setup

    <Steps>
      <Step title="Create a New App Integration">
        In the [Okta Admin Console](https://your-org.okta.com/admin), go to **Applications → Applications → Create App Integration → SAML 2.0**.
      </Step>

      <Step title="General Settings">
        Name the app **CloudThinker** and click **Next**.
      </Step>

      <Step title="Configure SAML Settings">
        Fill in from CloudThinker's SP Metadata:

        | Okta Field                      | CloudThinker Value         |
        | ------------------------------- | -------------------------- |
        | **Single sign-on URL**          | Paste the **ACS URL**      |
        | **Audience URI (SP Entity ID)** | Paste the **SP Entity ID** |
        | **Name ID format**              | `EmailAddress`             |
        | **Application username**        | `Email`                    |
      </Step>

      <Step title="Add Attribute Statements">
        In **Attribute Statements**, add:

        | Name        | Value            |
        | ----------- | ---------------- |
        | `email`     | `user.email`     |
        | `firstName` | `user.firstName` |
        | `lastName`  | `user.lastName`  |
      </Step>

      <Step title="Get IdP Metadata">
        After saving, go to the app's **Sign On** tab → **SAML Signing Certificates** section → click **Actions → View IdP metadata** to get the metadata XML URL.

        Or copy directly:

        * **Identity Provider Single Sign-On URL**
        * **Identity Provider Issuer**
        * **X.509 Certificate**
      </Step>

      <Step title="Assign People or Groups">
        Go to the **Assignments** tab and assign users or groups who should have access.
      </Step>

      <Step title="Complete Setup in CloudThinker">
        In CloudThinker's IdP Configuration step, paste the **Okta metadata URL** into the **Import** field, or enter manually:

        * **Entity ID**: Identity Provider Issuer
        * **SSO URL**: Identity Provider Single Sign-On URL
        * **Certificate**: X.509 Certificate

        Click **Create Connection** and **Test**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="OneLogin">
    ### OneLogin — SAML Setup

    <Steps>
      <Step title="Create a New App">
        In the [OneLogin Admin Portal](https://app.onelogin.com/admin), go to **Applications → Applications → Add App → Search for "SAML Custom Connector (Advanced)"** and click it.
      </Step>

      <Step title="Name and Save">
        Set the display name to **CloudThinker** and click **Save**.
      </Step>

      <Step title="Configure the Configuration Tab">
        Go to the **Configuration** tab and paste in from CloudThinker's SP Metadata:

        | OneLogin Field                   | CloudThinker Value                     |
        | -------------------------------- | -------------------------------------- |
        | **Audience (EntityID)**          | Paste the **SP Entity ID**             |
        | **ACS (Consumer) URL**           | Paste the **ACS URL**                  |
        | **ACS (Consumer) URL Validator** | `.*` (or the exact ACS URL as a regex) |
        | **Login URL**                    | Same as ACS URL                        |

        Save.
      </Step>

      <Step title="Add Parameter Mappings">
        Go to the **Parameters** tab and add:

        | Field name  | Value      |
        | ----------- | ---------- |
        | `email`     | Email      |
        | `firstName` | First Name |
        | `lastName`  | Last Name  |
      </Step>

      <Step title="Get IdP Details">
        Go to the **SSO** tab and copy:

        * **Issuer URL** (Entity ID)
        * **SAML 2.0 Endpoint (HTTP)**
        * **X.509 Certificate** (View Details → copy the certificate)
      </Step>

      <Step title="Assign Users">
        Go to **Users** tab and add users or roles that should have access.
      </Step>

      <Step title="Complete Setup in CloudThinker">
        In CloudThinker, enter:

        * **Entity ID**: Issuer URL
        * **SSO URL**: SAML 2.0 Endpoint (HTTP)
        * **Certificate**: X.509 Certificate

        Click **Create Connection** and **Test**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Generic SAML">
    ### Generic SAML 2.0

    Use this for any SAML-compliant identity provider not listed above.

    #### Step 1 — Get CloudThinker's SP Metadata

    Navigate to **Organization Settings → Security → SSO → Add Connection → SAML**. On the **SP Metadata** screen, copy:

    | Field               | What to do with it                                                |
    | ------------------- | ----------------------------------------------------------------- |
    | **ACS URL**         | Paste into your IdP's "Reply URL" or "ACS URL" field              |
    | **SP Entity ID**    | Paste into your IdP's "Audience" or "Entity ID" field             |
    | **SP Metadata URL** | Some IdPs let you import this URL to auto-fill all fields at once |

    #### Step 2 — Create a SAML App in Your IdP

    Create a new SAML application in your identity provider and enter the SP values above. Configure user attribute mappings:

    | CloudThinker Attribute | IdP Attribute           |
    | ---------------------- | ----------------------- |
    | `email` (NameID)       | User's primary email    |
    | `firstName`            | Given name / first name |
    | `lastName`             | Family name / last name |

    #### Step 3 — Configure IdP Details in CloudThinker

    After creating the SAML app in your IdP, return to CloudThinker and complete the **IdP Configuration** step:

    | Field             | Where to find it                                                                                                             |
    | ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
    | **Display Name**  | Choose any label (e.g., "Okta SAML")                                                                                         |
    | **Entity ID**     | Your IdP's entity identifier (sometimes called "Issuer")                                                                     |
    | **SSO URL**       | Your IdP's single sign-on endpoint URL                                                                                       |
    | **Certificate**   | The X.509 signing certificate from your IdP (base64-encoded)                                                                 |
    | **SLO URL**       | *(Optional)* Single logout endpoint — only needed if you want users logged out of the IdP when they sign out of CloudThinker |
    | **NameID Format** | Leave as "Email Address" unless your IdP requires a different format                                                         |

    <Tip>
      If your IdP provides a metadata URL or XML file, use the **Import** field at the top to auto-fill Entity ID, SSO URL, and Certificate — this saves time and avoids copy-paste errors.
    </Tip>

    Click **Create Connection**.
  </Tab>
</Tabs>

***

## OIDC Setup

<Tabs>
  <Tab title="Google Workspace">
    ### Google Workspace — OIDC Setup

    <Steps>
      <Step title="Create an OAuth Client">
        Go to [console.cloud.google.com](https://console.cloud.google.com) → **APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID**.

        Application type: **Web application**.
      </Step>

      <Step title="Add Authorized Redirect URI">
        Add the **Redirect URI** from CloudThinker's OIDC SP Metadata. Click **Create**.
      </Step>

      <Step title="Copy Credentials">
        Copy the **Client ID** and **Client Secret**.
      </Step>

      <Step title="Complete Setup in CloudThinker">
        In CloudThinker's OIDC configuration:

        * **Discovery URL**: `https://accounts.google.com/.well-known/openid-configuration`
        * **Client ID**: paste from Google
        * **Client Secret**: paste from Google

        Click **Create Connection** and **Test**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Azure AD / Entra ID">
    ### Azure AD (Entra ID) — OIDC Setup

    <Steps>
      <Step title="Register an Application">
        In [Azure Portal](https://portal.azure.com) → **Microsoft Entra ID → App registrations → New registration**.

        Name it **CloudThinker**. Under **Redirect URI**, select **Web** and paste the redirect URI from CloudThinker's OIDC SP Metadata.
      </Step>

      <Step title="Create a Client Secret">
        Go to **Certificates & secrets → New client secret**. Copy the **Value** immediately — it won't be shown again.
      </Step>

      <Step title="Complete Setup in CloudThinker">
        In CloudThinker's OIDC configuration:

        * **Discovery URL**: `https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration`
        * **Client ID**: **Application (client) ID** from the app registration overview
        * **Client Secret**: the secret value you copied

        Click **Create Connection** and **Test**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Okta">
    ### Okta — OIDC Setup

    <Steps>
      <Step title="Create an OIDC App">
        In Okta Admin → **Applications → Create App Integration → OIDC - OpenID Connect → Web Application**.
      </Step>

      <Step title="Configure Redirect URIs">
        Under **Sign-in redirect URIs**, paste the redirect URI from CloudThinker's OIDC SP Metadata. Click **Save**.
      </Step>

      <Step title="Complete Setup in CloudThinker">
        In CloudThinker's OIDC configuration:

        * **Discovery URL**: `https://your-org.okta.com/.well-known/openid-configuration`
        * **Client ID**: from the Okta app's **General** tab
        * **Client Secret**: from the Okta app's **General** tab

        Click **Create Connection** and **Test**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Generic OIDC">
    ### Generic OIDC

    Use this for any OpenID Connect-compliant provider.

    <Steps>
      <Step title="Register CloudThinker as an OAuth Client">
        In your IdP, create a new OAuth 2.0 / OIDC application. Add the **Redirect URI** shown in CloudThinker's OIDC SP Metadata screen.
      </Step>

      <Step title="Configure in CloudThinker">
        Enter the following in CloudThinker's OIDC configuration:

        | Field             | Description                                            |
        | ----------------- | ------------------------------------------------------ |
        | **Discovery URL** | Your IdP's `.well-known/openid-configuration` endpoint |
        | **Client ID**     | The client ID issued by your IdP                       |
        | **Client Secret** | The client secret issued by your IdP                   |

        Click **Create Connection** and **Test**.
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## After Setup

### Test the Connection

Always test before enforcing SSO:

1. Click **Test** in the SSO connection settings
2. A new browser tab opens and attempts authentication
3. Confirm you are redirected back to CloudThinker successfully
4. Check that your user attributes (name, email) were received correctly

### Enforce SSO (Optional)

Once verified, you can require all users to authenticate via SSO:

1. Go to **Organization Settings → Security → SSO**
2. Toggle **Enforce SSO** on
3. Users will be redirected to your IdP on next login — email/password login is disabled

<Warning>
  Make sure at least one Owner account works with SSO before enforcing it. If SSO breaks after enforcement, an Owner with a backup access method can disable it.
</Warning>

### User Provisioning

CloudThinker auto-provisions users on first SSO login using the `email`, `firstName`, and `lastName` attributes from your IdP. New users are assigned the **Developer** role by default — you can change this in SSO settings.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="'Invalid ACS URL' error from my IdP">
    Double-check that the ACS URL you entered in your IdP exactly matches what CloudThinker shows — including protocol (`https://`) and no trailing slash.
  </Accordion>

  <Accordion title="Attributes not mapping (name shows as email)">
    Confirm your IdP is sending `firstName` and `lastName` attributes. See the attribute mapping table for your provider above.
  </Accordion>

  <Accordion title="Certificate validation error">
    Make sure you copied the full X.509 certificate including the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` headers. If your IdP rotated its certificate, update it in CloudThinker's SSO settings.
  </Accordion>

  <Accordion title="Users can't log in after SSO enforcement">
    An Owner can disable SSO enforcement at **Organization Settings → Security → SSO** using their backup credentials. Check the IdP app is assigned to all affected users.
  </Accordion>

  <Accordion title="'Audience mismatch' or 'Entity ID mismatch'">
    The SP Entity ID in your IdP must exactly match the SP Entity ID shown in CloudThinker's SP Metadata — they are case-sensitive.
  </Accordion>
</AccordionGroup>

***

## What's Next

<CardGroup cols={2}>
  <Card title="MFA Setup" icon="mobile-screen" href="/guide/security/overview#multi-factor-authentication-mfa">
    Add TOTP-based MFA for an extra layer of authentication
  </Card>

  <Card title="Role-Based Access Control" icon="users-gear" href="/guide/security/overview#role-based-access-control-rbac">
    Configure granular permissions for your team members
  </Card>

  <Card title="Organization Settings" icon="building-columns" href="/guide/organization">
    Manage members, workspaces, and organization-level configuration
  </Card>

  <Card title="BYOK" icon="key" href="/guide/byok">
    Use your own AWS Bedrock credentials for data residency and cost control
  </Card>
</CardGroup>