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

> Let your team sign in to Collabase with their existing company accounts. Configure OAuth, SAML SSO, LDAP, and SCIM under Admin → Identity Providers.

# Identity providers

Collabase supports several sign-in methods. You can mix and match — for example, enable Microsoft Entra ID for most users while keeping email/password available as a fallback.

Configure identity providers under **Admin → Identity Providers**.

<Warning>
  The Identity Providers admin panel requires an enterprise license — including the OAuth section. Without a license, only email and password sign-in is available.
</Warning>

<CardGroup cols={3}>
  <Card title="Email & Password" icon="lock">
    Always available. Users sign in with an email address and password set by an admin or chosen during registration.
  </Card>

  <Card title="OAuth 2.0" icon="key">
    Sign in with Google, GitHub, Microsoft Entra ID, Okta, or Keycloak using an existing account. Users click a button on the login page.
  </Card>

  <Card title="SAML 2.0" icon="shield">
    Enterprise SSO with Okta, Microsoft Entra, or any SAML 2.0-compatible identity provider.
  </Card>

  <Card title="LDAP / Active Directory" icon="server">
    Authenticate against your on-premises directory. Users sign in with their company credentials.
  </Card>

  <Card title="SCIM 2.0" icon="users">
    Automated user and group provisioning from your identity provider. Accounts are created and deactivated automatically.
  </Card>
</CardGroup>

***

## Email and password (always on)

Email and password authentication is always enabled and cannot be turned off. It is available at `/auth/login` even when other sign-in methods are active.

<Note>
  Keep at least one admin account using email and password. If your identity provider goes down or is misconfigured, this is how you recover access.
</Note>

***

## OAuth 2.0

OAuth lets users sign in with an existing account from another service — Google, GitHub, Microsoft Entra ID, Okta, or Keycloak. No passwords are stored in Collabase for OAuth users.

### Setting up Google OAuth

<Steps>
  <Step title="Create an OAuth application in Google Cloud Console">
    Go to **APIs & Services → Credentials → Create Credentials → OAuth client ID**. Choose **Web application** as the application type.
  </Step>

  <Step title="Add the redirect URI">
    Under **Authorized redirect URIs**, add:

    ```
    https://your-collabase-domain/api/auth/callback/google
    ```
  </Step>

  <Step title="Copy the Client ID and Client Secret">
    Google shows these after you save the OAuth client.
  </Step>

  <Step title="Open Admin → Identity Providers → Google">
    Paste the Client ID and Client Secret into the corresponding fields.
  </Step>

  <Step title="Set the default role for new users">
    Choose **User** (recommended) or **Admin**. This role is assigned when a user signs in via Google for the first time and a new Collabase account is created.
  </Step>

  <Step title="Enable and save">
    Toggle the provider to **Enabled**. The **Sign in with Google** button appears on the login page immediately.
  </Step>
</Steps>

### Setting up GitHub OAuth

<Steps>
  <Step title="Create an OAuth App on GitHub">
    Go to GitHub → **Settings → Developer settings → OAuth Apps → New OAuth App**.
  </Step>

  <Step title="Set the authorization callback URL">
    ```
    https://your-collabase-domain/api/auth/callback/github
    ```
  </Step>

  <Step title="Copy the Client ID and generate a Client Secret">
    After saving, generate a client secret and copy both values.
  </Step>

  <Step title="Open Admin → Identity Providers → GitHub">
    Paste the Client ID and Client Secret.
  </Step>

  <Step title="Set the default role and enable">
    Choose the role for new users and toggle the provider to **Enabled**.
  </Step>
</Steps>

### Setting up Microsoft Entra ID

<Steps>
  <Step title="Register an application in the Microsoft Entra admin center">
    Go to **Identity → Applications → App registrations → New registration**. Give it a name (e.g. "Collabase").
  </Step>

  <Step title="Add the redirect URI">
    Under **Authentication → Add a platform → Web**, add:

    ```
    https://your-collabase-domain/api/auth/callback/microsoft
    ```
  </Step>

  <Step title="Create a client secret">
    Go to **Certificates & secrets → New client secret**. Copy the secret value immediately — it is not shown again.
  </Step>

  <Step title="Copy the Application (client) ID and Directory (tenant) ID">
    Both are shown on the app registration's **Overview** page.
  </Step>

  <Step title="Open Admin → Identity Providers → Microsoft">
    Enter the Client ID, Client Secret, and **Tenant ID (Directory ID)**.
  </Step>

  <Step title="Set the default role and enable">
    Choose the role for new users and toggle the provider to **Enabled**.
  </Step>
</Steps>

<Warning>
  **Tenant ID is required for Microsoft Entra ID.** Collabase will not save a Microsoft provider without one. This deliberately prevents sign-in from Microsoft accounts outside your organization — leaving the tenant unset would allow any Microsoft account in the world to sign in.
</Warning>

### Setting up Okta or Keycloak

<Steps>
  <Step title="Register Collabase as an application">
    In Okta or Keycloak, create a new OIDC application. Use:

    ```
    https://your-collabase-domain/api/auth/callback/okta
    ```

    or

    ```
    https://your-collabase-domain/api/auth/callback/keycloak
    ```

    as the redirect URI, depending on the provider.
  </Step>

  <Step title="Copy the Client ID and Client Secret">
    Your provider shows these after the application is created.
  </Step>

  <Step title="Open Admin → Identity Providers → Okta or Keycloak">
    Enter the Client ID and Client Secret, plus:

    * **Okta:** your organization URL (e.g. `https://mycompany.okta.com`)
    * **Keycloak:** your realm issuer URL (e.g. `https://keycloak.example.com/realms/myapp`)
  </Step>

  <Step title="Set the default role and enable">
    Choose the role for new users and toggle the provider to **Enabled**.
  </Step>
</Steps>

### Restricting sign-in by email domain

Every OAuth provider has an **Allowed email domains** field and an **Auto-create new users** toggle.

| Setting                   | What it does                                                                                                                                                                                            |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Allowed email domains** | A comma-separated list (e.g. `example.com, corp.example.com`). Only accounts with an email in one of these domains can sign in with this provider. Leave blank to allow any domain.                     |
| **Auto-create new users** | When on (default), a new Collabase account is created automatically the first time someone signs in with this provider. When off, only people who already have a Collabase account can sign in with it. |

<Warning>
  Set **Allowed email domains** for every provider except perhaps GitHub. Without it, anyone with an account at that provider can sign in — and if a Collabase account with a matching email already exists, they sign in to that existing account. This is especially important for Microsoft, Okta, and Keycloak, where organizations are often shared across companies.
</Warning>

<Note>
  Credentials are stored encrypted and cannot be viewed again after saving. To update a credential, enter the new value and save — the old value is replaced.
</Note>

***

## SAML 2.0

SAML 2.0 lets users sign in with Okta, Microsoft Entra, or any SAML 2.0-compatible identity provider. Once set up, users click **Sign in with SSO** on the login page and are redirected to your identity provider.

### What to give your identity provider

Your identity provider needs these two values to register Collabase as a service provider:

| Value                                    | Format                                                 |
| ---------------------------------------- | ------------------------------------------------------ |
| **Assertion Consumer Service (ACS) URL** | `https://your-collabase-domain/api/auth/saml/callback` |
| **Entity ID / Metadata URL**             | `https://your-collabase-domain/api/auth/saml/metadata` |

Most providers can import the full configuration by fetching the metadata URL automatically.

### What you need from your identity provider

| Field               | Where to find it                                        |
| ------------------- | ------------------------------------------------------- |
| **IdP SSO URL**     | The sign-on URL in your IdP's SAML application settings |
| **IdP Certificate** | The signing certificate (PEM format)                    |
| **Entity ID**       | The IdP's identifier string                             |

### Configuring SAML

<Steps>
  <Step title="Open Admin → Identity Providers → SAML">
    The panel shows the ACS URL and Entity ID you need to give your IdP.
  </Step>

  <Step title="Register Collabase in your identity provider">
    Use the ACS URL and Entity ID from step 1. Configure your IdP to send the user's **email** and **display name** in the SAML assertion attributes.
  </Step>

  <Step title="Enter the IdP SSO URL, certificate, and Entity ID in Collabase">
    Paste the values from your identity provider into the corresponding fields.
  </Step>

  <Step title="Set allowed email domains (recommended) and default role">
    Restrict sign-in to your organization's email domains and choose the role assigned to new accounts.
  </Step>

  <Step title="Enable and save">
    Toggle SAML to **Enabled**. Users see a **Sign in with SSO** button on the login page.
  </Step>
</Steps>

***

## LDAP / Active Directory

LDAP connects Collabase to your on-premises directory (Active Directory, OpenLDAP, FreeIPA, etc.) for authentication and user provisioning. Users sign in with their existing company username and password.

Navigate to **Admin → Identity Providers → LDAP**.

### Configuration fields

| Field                  | Description                                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Host**               | Your LDAP server address                                                                                     |
| **Port**               | `389` for standard LDAP, `636` for LDAP over TLS                                                             |
| **Use TLS**            | Strongly recommended for production                                                                          |
| **Bind DN**            | The service account used to connect to the directory (e.g. `cn=svc-collabase,ou=services,dc=example,dc=com`) |
| **Bind Password**      | Password for the service account                                                                             |
| **Base DN**            | The directory path to search for users (e.g. `ou=users,dc=example,dc=com`)                                   |
| **User Search Filter** | Which objects to treat as users — default: `(objectClass=person)`                                            |
| **Email Attribute**    | Directory attribute that holds the user's email address                                                      |
| **Name Attribute**     | Directory attribute for the user's display name                                                              |
| **Default Role**       | Role assigned to users signing in — or synced in — for the first time                                        |

The panel includes preset configurations for **Active Directory** (`(objectClass=user)`, `userPrincipalName`, `displayName`) and **OpenLDAP** (`(objectClass=inetOrgPerson)`, `mail`, `cn`) that fill in the common attribute mappings automatically.

Click **Test Connection** to verify that Collabase can reach your directory before saving.

<Note>
  A **Groups Attribute** field is available for future use. Group membership is not yet synchronized from your directory — group membership must currently be managed in Collabase directly.
</Note>

### Directory sync

When **Enable auto sync** is on and a **Sync Interval** is set, Collabase automatically imports users from your directory on that schedule:

* New users in the directory are created in Collabase.
* Existing users have their name updated on each sync.
* Users removed from the directory are disabled in Collabase — their content is not deleted.

Click **Sync Now** to trigger a manual sync at any time, in addition to the schedule.

<Warning>
  **If a sync would disable an unusually large number of users, Collabase stops and asks you to confirm.** This protects you if the directory connection is misconfigured or briefly unreachable — for example, a broken search filter that only matches a fraction of your real users. Review the warning message carefully before choosing **Sync anyway**; only proceed if you expect that many users to have genuinely left the directory.
</Warning>

<Note>
  A sync that finds zero users in your directory is always stopped automatically and cannot be forced through — this is treated as a configuration problem, not a real empty directory.
</Note>

***

## SCIM 2.0 automated provisioning

SCIM (System for Cross-domain Identity Management) connects your identity provider to Collabase so user accounts — and their group memberships — are created, updated, and deactivated automatically.

### Enabling SCIM

<Steps>
  <Step title="Open Admin → Identity Providers">
    Scroll to the **SCIM Provisioning** section.
  </Step>

  <Step title="Toggle Enable SCIM provisioning">
    SCIM requests are rejected until this is on, even with a valid token.
  </Step>

  <Step title="Click Generate token">
    Copy the token immediately — it is shown only once.
  </Step>

  <Step title="Configure your identity provider">
    In your IdP's SCIM settings, enter:

    * **SCIM base URL:** `https://your-collabase-domain/api/scim/v2`
    * **Authentication method:** Bearer token
    * **Bearer token:** the token you just copied
  </Step>

  <Step title="Assign the Collabase application to your users and groups">
    In your IdP, assign the Collabase SCIM application to the users or groups that should have access. The IdP pushes those users and groups to Collabase automatically.
  </Step>

  <Step title="Verify provisioning">
    Check **Admin → Users** to confirm the expected users were created. The **Identity** column on each user row shows the account's origin.
  </Step>
</Steps>

<Warning>
  The SCIM token is shown only once. If you lose it, revoke it in **Admin → Identity Providers → SCIM Provisioning** and generate a new one. A revoked token stops working immediately.
</Warning>

### What SCIM syncs automatically

| Event in your IdP                         | What happens in Collabase                         |
| ----------------------------------------- | ------------------------------------------------- |
| User is assigned to the Collabase app     | A new Collabase account is created                |
| User's name, title, or department changes | The Collabase profile is updated                  |
| User is removed from the Collabase app    | The Collabase account is deactivated              |
| User is re-assigned to the app            | The account is re-activated                       |
| User is added to or removed from a group  | Group membership in Collabase is updated to match |

SCIM does not delete accounts — it only deactivates them. Content created by the user is preserved.

<Note>
  Email address changes are not synced through SCIM. This is deliberate — email is how Collabase matches an incoming SCIM user to the correct account, so changing it through the sync could point a profile at the wrong person. To change a user's email, update it directly in **Admin → Users**.
</Note>

***

## Emergency admin access

Always keep at least one admin account that can sign in with email and password — in case your identity provider is unavailable.

The email/password login page is always accessible at `/auth/login`, even when SSO is the default sign-in method for all other users.

<Warning>
  If every admin account relies exclusively on an external provider (Google, Microsoft, SAML, LDAP) and that provider goes down or is misconfigured, you will be locked out of the admin panel. Maintain one local admin account as a recovery option.
</Warning>