# SSO, SAML, and SCIM
URL: https://docs.clearly-ai.com/docs/sso-saml-scim
Description: Connect Clearly AI to your identity provider.
Clearly AI uses PropelAuth for enterprise SSO and SCIM.

Use SSO when users sign in through your identity provider. Use SCIM when your identity provider creates, updates, and deactivates Clearly AI users automatically.

## Supported identity providers [#supported-identity-providers]

Clearly AI supports SAML SSO through PropelAuth. PropelAuth provides guided setup for Okta, Microsoft Entra ID, Google, OneLogin, JumpCloud, Duo, Rippling, and generic SAML providers.

SCIM is available through PropelAuth for Okta, Microsoft Entra ID, OneLogin, and JumpCloud.

## Who should be involved [#who-should-be-involved]

Enterprise SSO setup usually needs both product and identity owners:

* Your Clearly AI tenant URL.
* A Clearly AI Owner or Admin.
* An identity provider or IAM admin who can configure the SAML application.
* The email domains allowed into your organization.
* The default role or role mapping you want Clearly AI users to receive.

Large organizations often have a separate SSO or IAM team that owns the final IdP configuration. Include them early if your app owner cannot change SAML certificates, assertion signing, user assignment, or role/group mappings.

## Information exchanged during SAML setup [#information-exchanged-during-saml-setup]

Clearly AI and PropelAuth provide the setup link and SAML service provider values, including the ACS URL and SP Entity ID. Some IdPs ask for service provider metadata XML or an SP certificate. If your IdP requires either one, ask Clearly AI before your IdP admin finishes the setup so we can confirm the exact field and format.

Your IdP admin provides the identity provider values back through the PropelAuth setup flow:

* IdP SSO URL.
* IdP Entity ID or Issuer.
* IdP signing certificate.
* User attribute mappings, usually email, first name, and last name.
* Role or group mappings, if your IdP should manage Clearly AI roles.

## Set up SAML SSO [#set-up-saml-sso]

<Steps>
  <Step>
    ### Request enterprise SSO [#request-enterprise-sso]

    Ask Clearly AI to enable Enterprise SSO for your organization and generate a SAML setup link. The link is time-limited and can be shared with the identity provider admin who will complete the setup.
  </Step>

  <Step>
    ### Open the PropelAuth setup guide [#open-the-propelauth-setup-guide]

    Choose your identity provider in the setup guide. If your provider is not listed, use the generic SAML guide.
  </Step>

  <Step>
    ### Configure Clearly AI as the service provider [#configure-clearly-ai-as-the-service-provider]

    In your IdP, enter the ACS URL and SP Entity ID from the PropelAuth guide. If your IdP asks for service provider metadata XML or an SP certificate instead of direct URL entry, pause and ask Clearly AI for the right value.
  </Step>

  <Step>
    ### Map user attributes [#map-user-attributes]

    Map email, first name, and last name. If your IdP asks for a NameID format, use `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` unless your Clearly AI contact gives different guidance for your provider.
  </Step>

  <Step>
    ### Enter IdP values in PropelAuth [#enter-idp-values-in-propelauth]

    In the PropelAuth setup guide, enter the IdP SSO URL, IdP Entity ID or Issuer, and IdP signing certificate. These values must match what the IdP sends in the SAML assertion.
  </Step>

  <Step>
    ### Test with an assigned user [#test-with-an-assigned-user]

    Assign one test user to the SAML app in your IdP, then test login from your Clearly AI tenant URL. If your IdP has separate QA and production apps, test the same configuration path in each environment before broad rollout.
  </Step>
</Steps>

After SSO is enabled, users in the organization sign in through the configured identity provider.

## Map roles from your IdP [#map-roles-from-your-idp]

Decide role behavior before broad rollout. If the IdP does not send a role, new users may receive the default member role and need manual reassignment after first login.

PropelAuth supports SAML role mapping through provider-specific guides. Common patterns are:

* Send a role attribute with a Clearly AI role value, such as `Owner`, `Admin`, or `Member`.
* Send a group named for the role, such as `role_Owner`, when your IdP uses group-based role mapping.

If you want a limited role such as chat-only access for new users, configure that mapping in your IdP before inviting a large group. This avoids a window where users sign in with broader access than intended.

## Set up SCIM [#set-up-scim]

Set up SCIM after SSO works. PropelAuth requires Enterprise SSO to be enabled before SCIM can be enabled.

<Steps>
  <Step>
    ### Ask Clearly AI to enable SCIM [#ask-clearly-ai-to-enable-scim]

    Clearly AI enables SCIM for your organization after SSO is configured.
  </Step>

  <Step>
    ### Open the PropelAuth SCIM guide [#open-the-propelauth-scim-guide]

    Open the SCIM setup guide from your organization settings. PropelAuth provides provider-specific instructions for supported IdPs.
  </Step>

  <Step>
    ### Configure provisioning in your IdP [#configure-provisioning-in-your-idp]

    Enter the SCIM connection details in your IdP and assign one test user to the Clearly AI application.
  </Step>

  <Step>
    ### Test the user lifecycle [#test-the-user-lifecycle]

    Provision the test user, confirm the user appears in Clearly AI, update any mapped profile or role fields, then deactivate or unassign the user in your IdP and confirm access is removed.
  </Step>
</Steps>

SCIM controls provisioning. Users still sign in through SSO.

## FAQs [#faqs]

<Accordions>
  <Accordion title="What should I do if the setup link expired?">
    Ask Clearly AI for a new setup link.
  </Accordion>

  <Accordion title="What if my IdP asks for service provider metadata XML?">
    Complete the SAML setup guide far enough to generate the SAML login URL, then ask Clearly AI for help deriving or confirming the metadata URL. In PropelAuth, metadata is generated from the SAML login URL by changing `/login` to `/metadata`.
  </Accordion>

  <Accordion title="What if my IdP asks for an SP certificate?">
    Tell Clearly AI which IdP field requires the certificate and whether it is for encrypted assertions or signed SAML requests. The IdP signing certificate is different: it is the certificate PropelAuth uses to verify assertions from your IdP.
  </Accordion>

  <Accordion title="Why does SAML show as configured but login still fails?">
    Confirm the test user is assigned to the SAML app, the user's email domain matches the organization domain, and the IdP SSO URL, Entity ID or Issuer, and signing certificate match the values entered in PropelAuth. If the error appears on the IdP page before returning to Clearly AI, your IdP admin should check user assignment and app policy first.
  </Accordion>

  <Accordion title="Why do we see a signature or certificate error?">
    Confirm the IdP signing certificate in PropelAuth is the certificate used to sign the assertion. Also confirm your IdP is signing the assertion. An SP certificate is used for encrypted assertions or signed SAML requests; it is not the certificate used to verify the IdP's assertion signature.
  </Accordion>

  <Accordion title="Why do we see an issuer or Entity ID mismatch?">
    Check the exact Entity ID or Issuer value sent by the IdP and make sure it matches the value entered in PropelAuth. Some IdPs use one URL for the SSO endpoint and a different URL for the issuer.
  </Accordion>

  <Accordion title="Why did QA work but production fail?">
    Compare the production IdP SSO URL, Entity ID or Issuer, signing certificate, user assignment, assertion signing policy, encryption policy, and attribute mappings. Production IdP apps often have different certificates or issuer values from QA.
  </Accordion>

  <Accordion title="Why does login fail after sending attributes or groups?">
    Send only the attributes Clearly AI needs: email, first name, last name, and any role or group mapping you intentionally use. Avoid sending every group for the user unless your Clearly AI contact asks for it.
  </Accordion>

  <Accordion title="Why is the wrong role assigned?">
    Check the role attribute or role group mapping in your identity provider, then have the user sign in again. If no role is sent, the user may receive the default member role and require manual reassignment.
  </Accordion>

  <Accordion title="Why can't a user sign in after SCIM setup?">
    Confirm the user is assigned to the app in your identity provider, their email domain matches the organization domain, and their account is not stuck in an unconfirmed state from before SCIM was enabled.
  </Accordion>
</Accordions>

## References [#references]

* [PropelAuth Enterprise SSO](https://docs.propelauth.com/features/saml)
* [PropelAuth SCIM](https://docs.propelauth.com/overview/authentication/scim)
* [PropelAuth organizations](https://docs.propelauth.com/overview/basics/organizations)