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

# SSO & User Sync

With Single Sign-On (SSO), you sign your team in to nuwacom through your identity provider. In addition, you can automatically sync roles, groups, and user groups through user synchronization.

You'll find these settings under **Workspace Settings > SSO & User Sync.**

<Info>
  **Note:** SSO & User Sync is currently only available in multi-tenant environments, i.e. at app.nuwacom.ai or app-de.nuwacom.ai. This feature is not currently available in single-tenant environments.<br /><br />For single-tenant environments, integration is currently handled through a custom SSO setup. If you'd like to set up SSO for your environment, please contact us at [support@nuwacom.ai](mailto:support@nuwacom.ai). Our team will review your requirements and support you with the next steps.
</Info>

#### Prerequisites

To set this up, you need admin rights in nuwacom and access to your identity provider.

***

## Enable Single Sign-On

First, enable SSO and specify which email domains should sign in through your identity provider.

1. Open the workspace settings.
2. Go to SSO & User Sync.
3. Turn on the **Enable SSO** toggle.
4. Under **Email Domains**, enter the domain for which SSO should apply.

**Example:**

```text theme={null}
firma.de
```

Team members with this email domain will then be automatically redirected to your identity provider.

5. Then select the appropriate provider type to connect your identity provider to nuwacom via **OpenID Connect (OIDC)** or **SAML 2.0**.

### OpenID Connect (OIDC)

If you select **OpenID Connect (OIDC)**, enter your identity provider's connection details.

Enter the following values:

| **Field**     | **Description**                                                   |
| :------------ | :---------------------------------------------------------------- |
| Discovery URL | The discovery URL of your identity provider.                      |
| Client ID     | The client ID of the application from your identity provider.     |
| Client Secret | The client secret of the application from your identity provider. |

**Example of a discovery URL:**

```text theme={null}
https://login.example.com/.well-known/openid-configuration
```

Then copy the **Redirect URI** shown in nuwacom and enter it when registering the application in your identity provider.

Then click **Save Configuration**.

### SAML 2.0

If you select **SAML 2.0**, enter your identity provider's metadata.

You can enter the metadata in two ways:

| **Option** | **Description**                                      |
| :--------- | :--------------------------------------------------- |
| URL        | Enter the metadata URL of your identity provider.    |
| XML        | Paste the metadata XML directly into the text field. |

Then copy the values shown in nuwacom and enter them in your identity provider:

| **Value**    | **Description**                                                  |
| :----------- | :--------------------------------------------------------------- |
| ACS URL      | The URL to which your identity provider sends the SAML response. |
| SP Entity ID | The unique identifier of nuwacom as the service provider.        |

Then click **Save Configuration**.

### Advanced Settings

Here you define how external attributes from your identity provider are mapped to user attributes in nuwacom.

Open this section and review the attribute mapping. By default, the following mappings are set, for example:

| Claim from IdP | User Attribute |
| :------------- | :------------- |
| email          | email          |
| given\_name    | firstName      |
| family\_name   | lastName       |

Click **Add Mapping** if you want to transfer additional attributes. Enter the external claim from your identity provider and map it to the appropriate user attribute in nuwacom.

Then select the appropriate sync mode:

| **Sync Mode** | **Description**                                  |
| :------------ | :----------------------------------------------- |
| Force         | Attributes are overwritten on every login.       |
| Import        | Attributes are only imported on the first login. |
| Legacy        | Existing sync mode for older configurations.     |

Then click **Save Configuration**.

***

## Enable SCIM User Sync

With SCIM, you automatically sync users from your identity provider to nuwacom.

1. Turn on the **Enable SCIM User Sync** toggle.
2. Copy the displayed **SCIM Endpoint URL** and enter it in your identity provider.
3. Click **Generate Token** to create a bearer token.
4. Copy the bearer token and enter it in your identity provider for the SCIM connection.

<Note>
  **Important:** Treat the bearer token like a password. Do not share it publicly and store it only in secure locations.
</Note>

### Role Mapping

Here you define which IdP roles or IdP groups correspond to which workspace roles in nuwacom.

1. In the **Role Mapping** section, click **Add Rule**.
2. Enter the name of the role or group from your identity provider.

**Example:**

```text theme={null}
marketing-team
```

Then select which workspace role users with this IdP role or group should receive:

| **Role**      | **Description**                                    |
| :------------ | :------------------------------------------------- |
| Administrator | Has full access to the workspace and its settings. |
| Editor        | Can create and edit content.                       |
| Reader        | Can read shared content.                           |

If needed, click **Add Fallback Rule** to set a default role for all other users. Then click **Save Rules**.

<Note>
  **Note:** The first matching rule is applied. Users without a matching rule will not get access to the workspace if no fallback rule is defined.
</Note>

### Sync User Groups

If you'd also like to use SCIM groups as user groups in nuwacom, enable **Synchronize SCIM Groups as User Groups**. nuwacom will then automatically create and update user groups based on SCIM group memberships.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="SSO login isn't working. What should you check?">
    Make sure the email domain is entered correctly and that SSO is enabled for this domain. Also check that the required values are configured exactly in your identity provider:

    * For OIDC: Redirect URI
    * For SAML: ACS URL and SP Entity ID
  </Accordion>

  <Accordion title="Users aren't being redirected to the identity provider. What could be causing this?">
    Check whether the user's email domain is set up in nuwacom. Automatic redirection only works for users whose email domain matches a domain configured for SSO.
  </Accordion>

  <Accordion title="A user doesn't have access to the workspace. What should you check?">
    Check whether there is a matching role mapping for the user. If no mapping rule applies and no fallback rule is defined, the user will not get access to the workspace.
  </Accordion>

  <Accordion title="Users aren't being synced via SCIM. What should you check?">
    Make sure SCIM user sync is enabled. Also check whether the SCIM endpoint URL is entered correctly in your identity provider and whether the bearer token is still valid.
  </Accordion>

  <Accordion title="Groups aren't being imported as user groups in nuwacom. What should you check?">
    Check whether **Synchronize SCIM Groups as User Groups** is enabled. Also make sure that group memberships are correctly maintained in your identity provider and transferred via SCIM.
  </Accordion>

  <Accordion title="Changes from the identity provider don't appear in nuwacom. What should you check?">
    Synchronization is triggered by your identity provider. Check there whether the change was successfully sent to nuwacom. Also make sure that SCIM is active and the connection to nuwacom is working.
  </Accordion>

  <Accordion title="Attributes such as first name, last name, or email aren't imported correctly. What should you check?">
    Open **Advanced Settings** and review the attribute mapping. Make sure the claims from your identity provider are mapped to the correct user attributes in nuwacom.
  </Accordion>
</AccordionGroup>