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

# SAML SSO Setup

> Connect Google Workspace, Microsoft Entra ID, AWS IAM Identity Center, Okta, OneLogin, or any SAML 2.0 identity provider

Set up SAML 2.0 single sign-on between your identity provider and CloudThinker. Start the wizard at **Admin Settings → Identity and access → Setup SSO** and choose **SAML 2.0**; the **SP Metadata** step shows the **ACS URL**, **SP Entity ID**, and **SP Metadata URL** you paste into your provider.

## Prerequisites

* A verified email domain and an eligible plan — see [Single Sign-On](/guide/security/sso)
* Admin access to your identity provider

<Tip>
  On the wizard's **IdP Config** step, paste your provider's metadata URL into the **Import** field to auto-fill **IdP Entity ID**, **SSO URL**, and **IdP Certificate** in one step.
</Tip>

## Provider setup

<Tabs>
  <Tab title="Google Workspace">
    <Steps>
      <Step title="Create a custom SAML app">
        Go to [admin.google.com](https://admin.google.com) → **Apps → Web and mobile apps → Add app → Add custom SAML app**. Name it **CloudThinker** and click **Continue**.
      </Step>

      <Step title="Download the IdP metadata">
        On the **Google IdP information** screen, download the **IdP metadata XML** or note the **SSO URL**, **Entity ID**, and the X.509 **Certificate**. Click **Continue**.
      </Step>

      <Step title="Enter CloudThinker's SP details">
        Copy the values from CloudThinker's **SP Metadata** step:

        | Google field       | CloudThinker value                  |
        | ------------------ | ----------------------------------- |
        | **ACS URL**        | The **ACS URL**                     |
        | **Entity ID**      | The **SP Entity ID**                |
        | **Name ID format** | `EMAIL`                             |
        | **Name ID**        | `Basic Information > Primary email` |

        Click **Continue**.
      </Step>

      <Step title="Configure attribute mapping">
        | Google directory attribute | App attribute |
        | -------------------------- | ------------- |
        | Primary email              | `email`       |
        | First name                 | `firstName`   |
        | Last name                  | `lastName`    |

        Click **Finish**, then set the app's access to **On for everyone** (or target specific organizational units).
      </Step>

      <Step title="Finish in CloudThinker">
        On the **IdP Config** step, enter the **Entity ID**, **SSO URL**, and **Certificate** from Google (or use **Import** with the metadata URL). Click **Create Connection**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Microsoft Entra ID">
    <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 application → **Single sign-on → SAML**, then click **Edit** on **Basic SAML Configuration**:

        | Azure field                | CloudThinker value   |
        | -------------------------- | -------------------- |
        | **Identifier (Entity ID)** | The **SP Entity ID** |
        | **Reply URL (ACS URL)**    | The **ACS URL**      |
        | **Sign on URL**            | Same as ACS URL      |

        Save.
      </Step>

      <Step title="Configure attributes and claims">
        In **Attributes & Claims**, confirm the `emailaddress` claim maps to `user.mail`. Optionally add `firstName` → `user.givenname` and `lastName` → `user.surname`.
      </Step>

      <Step title="Copy the federation metadata">
        In **SAML Signing Certificate**, copy the **App Federation Metadata URL** (recommended), or download the **Certificate (Base64)** with the **Login URL** and **Azure AD Identifier**.
      </Step>

      <Step title="Assign users and finish in CloudThinker">
        Assign users under **Users and groups**. In CloudThinker's **IdP Config** step, paste the metadata URL into **Import** — or enter the Azure AD Identifier as **IdP Entity ID**, the Login URL as **SSO URL**, and the Base64 certificate as **IdP Certificate**. Click **Create Connection**.
      </Step>
    </Steps>
  </Tab>

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

      <Step title="Copy the IAM Identity Center metadata">
        In the **IAM Identity Center metadata** section, copy the metadata URL (or the issuer URL, sign-in URL, and certificate).
      </Step>

      <Step title="Enter the application metadata">
        | IAM Identity Center field     | CloudThinker value   |
        | ----------------------------- | -------------------- |
        | **Application ACS URL**       | The **ACS URL**      |
        | **Application SAML audience** | The **SP Entity ID** |
      </Step>

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

        | Application attribute | IAM Identity Center value               |
        | --------------------- | --------------------------------------- |
        | `Subject`             | `${user:email}` — format `emailAddress` |
        | `email`               | `${user:email}`                         |
        | `firstName`           | `${user:givenName}`                     |
        | `lastName`            | `${user:familyName}`                    |
      </Step>

      <Step title="Assign users and finish in CloudThinker">
        Assign users under **Assigned users and groups**. In CloudThinker, use **Import** with the metadata URL, or enter the issuer URL as **IdP Entity ID**, the sign-in URL as **SSO URL**, and the certificate. Click **Create Connection**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Okta">
    <Steps>
      <Step title="Create a SAML app integration">
        In the Okta Admin Console, go to **Applications → Applications → Create App Integration → SAML 2.0**. Name it **CloudThinker**.
      </Step>

      <Step title="Configure SAML settings">
        | Okta field                      | CloudThinker value   |
        | ------------------------------- | -------------------- |
        | **Single sign-on URL**          | The **ACS URL**      |
        | **Audience URI (SP Entity ID)** | The **SP Entity ID** |
        | **Name ID format**              | `EmailAddress`       |
        | **Application username**        | `Email`              |
      </Step>

      <Step title="Add attribute statements">
        | Name        | Value            |
        | ----------- | ---------------- |
        | `email`     | `user.email`     |
        | `firstName` | `user.firstName` |
        | `lastName`  | `user.lastName`  |
      </Step>

      <Step title="Copy the IdP metadata">
        After saving, open the app's **Sign On** tab → **SAML Signing Certificates** → **Actions → View IdP metadata**, and copy the metadata URL — or copy the Identity Provider Single Sign-On URL, Issuer, and X.509 certificate directly.
      </Step>

      <Step title="Assign people and finish in CloudThinker">
        Assign users or groups on the **Assignments** tab. In CloudThinker, paste the metadata URL into **Import**, or enter the Issuer as **IdP Entity ID**, the Single Sign-On URL as **SSO URL**, and the certificate. Click **Create Connection**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="OneLogin">
    <Steps>
      <Step title="Add a SAML custom connector">
        In the OneLogin Admin Portal, go to **Applications → Applications → Add App**, search for **SAML Custom Connector (Advanced)**, name it **CloudThinker**, and save.
      </Step>

      <Step title="Configure the connector">
        On the **Configuration** tab:

        | OneLogin field                   | CloudThinker value           |
        | -------------------------------- | ---------------------------- |
        | **Audience (EntityID)**          | The **SP Entity ID**         |
        | **ACS (Consumer) URL**           | The **ACS URL**              |
        | **ACS (Consumer) URL Validator** | The exact ACS URL as a regex |
        | **Login URL**                    | Same as ACS URL              |
      </Step>

      <Step title="Add parameter mappings">
        On the **Parameters** tab, map `email` → Email, `firstName` → First Name, `lastName` → Last Name.
      </Step>

      <Step title="Copy the IdP details">
        On the **SSO** tab, copy the **Issuer URL**, **SAML 2.0 Endpoint (HTTP)**, and the X.509 certificate.
      </Step>

      <Step title="Assign users and finish in CloudThinker">
        Add users on the **Users** tab. In CloudThinker, enter the Issuer URL as **IdP Entity ID**, the SAML 2.0 Endpoint as **SSO URL**, and the certificate. Click **Create Connection**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Generic SAML">
    Use this for any SAML 2.0-compliant identity provider.

    Create a SAML app in your provider using CloudThinker's **SP Metadata** values — the **ACS URL** goes in your provider's "Reply URL"/"ACS URL" field and the **SP Entity ID** in its "Audience"/"Entity ID" field; some providers can import the **SP Metadata URL** directly. Map user attributes so the assertion sends the user's primary email as `email` (NameID), plus `firstName` and `lastName`.

    Then complete CloudThinker's **IdP Config** step:

    | Field               | Where to find it                                                             |
    | ------------------- | ---------------------------------------------------------------------------- |
    | **Display Name**    | Any label, for example "Okta SSO"                                            |
    | **IdP Entity ID**   | Your provider's entity identifier (sometimes called "Issuer")                |
    | **SSO URL**         | Your provider's single sign-on endpoint                                      |
    | **IdP Certificate** | The X.509 signing certificate, including the `BEGIN`/`END CERTIFICATE` lines |
    | **SLO URL**         | Optional single-logout endpoint                                              |
    | **Name ID Format**  | Leave as **Email Address** unless your provider requires another format      |

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

## Troubleshooting

<AccordionGroup>
  <Accordion title="'Invalid ACS URL' error from the identity provider">
    The ACS URL in your provider must exactly match CloudThinker's **ACS URL** — including `https://` and no trailing slash.
  </Accordion>

  <Accordion title="Names show as email addresses">
    Your provider isn't sending `firstName` and `lastName`. Add them in the attribute mapping table for your provider above.
  </Accordion>

  <Accordion title="Certificate validation error">
    Paste the full X.509 certificate, including the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines. If your provider rotated its certificate, update **IdP Certificate** on the connection.
  </Accordion>

  <Accordion title="'Audience mismatch' or 'Entity ID mismatch'">
    The SP Entity ID configured in your provider must exactly match CloudThinker's **SP Entity ID** — the comparison is case-sensitive.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Test and Enforce SSO" icon="key" href="/guide/security/sso">
    Test the connection, turn on Require SSO, and choose a provisioning mode
  </Card>

  <Card title="SCIM Provisioning" icon="users-gear" href="/guide/security/scim">
    Sync users and groups automatically from your identity provider
  </Card>
</CardGroup>