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

# SSO and authentication

> Configure how users authenticate to Hadiq.io, from basic email/password to enterprise SSO and automated SCIM provisioning.

Hadiq.io supports several authentication methods. You can use a single method or combine them depending on your organization's requirements. Authentication settings are managed in **Admin** > **Settings** > **Authentication**.

## Authentication methods

<AccordionGroup>
  <Accordion title="Basic auth (email and password)">
    The default method. Users sign up with an email address and password. Hadiq.io stores a hashed password and issues a session token on login.

    Basic auth is available on all plans. No additional configuration is needed.
  </Accordion>

  <Accordion title="Google OAuth">
    Allow users to sign in with their Google account. This removes the need for passwords and relies on Google to verify identity.

    Google OAuth is available on all plans.
  </Accordion>

  <Accordion title="OIDC SSO">
    Connect any OIDC-compliant identity provider (Okta, Azure AD, Auth0, Keycloak, and others). Users are redirected to your IdP to authenticate and returned to Hadiq.io on success.

    <Note>
      OIDC SSO requires the **Enterprise** plan.
    </Note>
  </Accordion>

  <Accordion title="SAML SSO">
    Connect SAML 2.0 identity providers. Like OIDC, users authenticate with your IdP and are returned to Hadiq.io.

    <Note>
      SAML SSO requires the **Enterprise** plan.
    </Note>
  </Accordion>
</AccordionGroup>

## Setting up Google OAuth

<Steps>
  <Step title="Create an OAuth app in Google Cloud">
    In the [Google Cloud Console](https://console.cloud.google.com), create an OAuth 2.0 client ID for a **Web application**. Add your Hadiq.io instance's callback URL as an authorized redirect URI.
  </Step>

  <Step title="Copy the client credentials">
    Copy the **Client ID** and **Client secret** from the OAuth client you created.
  </Step>

  <Step title="Enter credentials in Hadiq.io">
    In **Admin** > **Settings** > **Authentication**, select **Google OAuth** and paste your Client ID and Client secret.
  </Step>

  <Step title="Save and test">
    Save the configuration. Sign out and verify you can sign in using the **Continue with Google** button.
  </Step>
</Steps>

## Setting up OIDC SSO

<Note>
  OIDC SSO is an **Enterprise** feature.
</Note>

<Steps>
  <Step title="Register Hadiq.io in your identity provider">
    In your IdP (Okta, Azure AD, Auth0, or another OIDC provider), create a new OIDC application. Set the **redirect URI** to your Hadiq.io callback URL (typically `https://your-Hadiq.io-domain/auth/oidc/callback`).
  </Step>

  <Step title="Collect the required values">
    You will need:

    * **Client ID**
    * **Client secret**
    * **OIDC discovery URL** (also called the well-known configuration URL, usually ending in `/.well-known/openid-configuration`)
  </Step>

  <Step title="Configure OIDC in Hadiq.io">
    Go to **Admin** > **Settings** > **Authentication** and select **OIDC**. Enter:

    | Field              | Value                            |
    | ------------------ | -------------------------------- |
    | Client ID          | The client ID from your IdP      |
    | Client secret      | The client secret from your IdP  |
    | OIDC discovery URL | The well-known configuration URL |
  </Step>

  <Step title="Configure group sync (optional)">
    If your IdP sends group claims in the ID token, you can map those claims to Hadiq.io groups. Enter the claim name that contains group information. Hadiq.io will automatically add and remove users from the matching groups on each login.
  </Step>

  <Step title="Save and test">
    Save the configuration and test by signing out and signing back in via SSO.
  </Step>
</Steps>

## Setting up SAML SSO

<Note>
  SAML SSO is an **Enterprise** feature.
</Note>

<Steps>
  <Step title="Create a SAML app in your identity provider">
    In your IdP, create a new SAML 2.0 application. Configure:

    * **ACS URL (Assertion Consumer Service URL)**: `https://your-Hadiq.io-domain/auth/saml/acs`
    * **Entity ID / Audience URI**: Your Hadiq.io instance URL
    * **Name ID format**: Email address
  </Step>

  <Step title="Download the IdP metadata or collect values">
    Most IdPs provide an XML metadata file or individual values:

    * **IdP SSO URL**: The SAML sign-in endpoint on your IdP
    * **IdP Entity ID**: Your IdP's entity identifier
    * **X.509 certificate**: The public certificate used to verify SAML assertions
  </Step>

  <Step title="Configure SAML in Hadiq.io">
    Go to **Admin** > **Settings** > **Authentication** and select **SAML**. Enter the values collected from your IdP, or upload the XML metadata file if your IdP provides one.
  </Step>

  <Step title="Configure attribute mapping">
    Map the SAML attributes your IdP sends to Hadiq.io fields:

    * **Email**: The attribute containing the user's email address (commonly `NameID` or `email`)
    * **Groups** (optional): The attribute containing group membership, for automatic group sync
  </Step>

  <Step title="Save and test">
    Save the configuration and test the SAML flow by signing out and signing in through your IdP.
  </Step>
</Steps>

## SCIM provisioning

SCIM (System for Cross-domain Identity Management) lets your identity provider automatically provision and deprovision users and groups in Hadiq.io. When SCIM is enabled, you do not need to manually invite users — your IdP handles it.

<Note>
  SCIM provisioning requires the **Enterprise** plan.
</Note>

Hadiq.io's SCIM implementation follows RFC 7644 and is compatible with Okta, Azure AD / Entra ID, and other standard SCIM 2.0 identity providers.

### Enabling SCIM

<Steps>
  <Step title="Go to SCIM settings">
    Navigate to **Admin** > **SCIM**.
  </Step>

  <Step title="Generate a SCIM token">
    Click **Generate Token**. Copy the token — it is shown only once.
  </Step>

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

    * **SCIM base URL**: `https://your-Hadiq.io-domain/scim/v2`
    * **Authentication token**: The token you generated
  </Step>

  <Step title="Enable user and group provisioning">
    In your IdP, enable provisioning for:

    * **Create users** — provisions new Hadiq.io accounts when users are assigned to the app
    * **Deactivate users** — disables Hadiq.io accounts when users are removed from the app
    * **Push groups** — syncs IdP groups to Hadiq.io user groups
  </Step>

  <Step title="Run an initial sync">
    Trigger a sync from your IdP. Hadiq.io will create accounts for all assigned users and groups.
  </Step>
</Steps>

### How SCIM provisioning works

When your IdP sends a SCIM request, Hadiq.io:

* **Creates** a new user account if the email does not exist yet.
* **Adopts** an existing Hadiq.io user if the email already exists and is not yet SCIM-managed, linking it to the IdP identity without creating a duplicate.
* **Deactivates** a user when the IdP sends `active: false` (Okta's preferred deprovisioning method) or a DELETE request.
* **Creates or updates groups** when the IdP pushes group assignments.

<Note>
  SCIM-managed users are marked with a sync indicator in **Admin** > **Users**. Their role assignments and group memberships can still be adjusted manually within Hadiq.io, but group membership changes from the IdP will override manual changes on the next sync.
</Note>

<Warning>
  The reserved groups **Admin** and **Basic** cannot be managed via SCIM. If your IdP attempts to rename or delete these groups, Hadiq.io returns a 409 error.
</Warning>