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

# Identity Providers

> Configure per-tenant SSO with Microsoft Entra ID, Google Workspace, or Okta.

# Identity Providers

Swarmd supports per-tenant SSO so your team can authenticate via your organisation's existing identity provider. Once configured, users with a matching email domain are offered SSO as a login option alongside password authentication.

The flow works in three stages:

1. **Configure an identity provider** — register your provider and associate it with one or more email domains.
2. **Login discovery** — the frontend calls the discover endpoint with the user's email. If the domain matches a configured provider, the user is redirected to SSO.
3. **Callback** — after authenticating with the identity provider, the authorization code is exchanged for a Swarmd session. New users are automatically provisioned into the correct tenant.

<Info>
  You need the **IDENTITY\_PROVIDERS** permission to manage identity providers. Users in the **Tenant Administrator** group have this by default. See [User Management](/tutorials/user-management) for details on permissions.
</Info>

***

## Supported Providers

| Provider           | Config Fields                          | What You Need                |
| ------------------ | -------------------------------------- | ---------------------------- |
| Microsoft Entra ID | `tenantId`, `clientId`, `clientSecret` | An Entra app registration    |
| Google Workspace   | `clientId`, `clientSecret`             | A Google Cloud OAuth client  |
| Okta               | `domain`, `clientId`, `clientSecret`   | An Okta OIDC app integration |

All providers use OIDC under the hood. Swarmd derives all endpoint URLs automatically from the config you provide.

***

## Microsoft Entra ID

### Step 1: Register an Application in Entra ID

1. Go to the [Azure Portal](https://portal.azure.com) and navigate to **Microsoft Entra ID** > **App registrations** > **New registration**.
2. Set the **Name** to "Swarmd SSO".
3. Under **Redirect URIs**, select **Web** and leave it blank — you will get the exact URL from the Swarmd API response.
4. Click **Register**.
5. Go to **Certificates & secrets** > **Client secrets** > **New client secret**. Copy the **Value** immediately.
6. To include groups in the token: go to **Token configuration** > **Add groups claim** and select **Security groups**.

Note your **Application (client) ID** and **Directory (tenant) ID** from the app registration **Overview** page.

### Step 2: Create the Identity Provider in Swarmd

```bash theme={null}
curl -X POST https://api.swarmd.ai/tenant-auth/v1/identity-providers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "provider": "MICROSOFT_ENTRA",
    "emailDomains": ["acme.com"],
    "config": {
      "type": "microsoftEntra",
      "tenantId": "YOUR_ENTRA_DIRECTORY_TENANT_ID",
      "clientId": "YOUR_APPLICATION_CLIENT_ID",
      "clientSecret": "YOUR_CLIENT_SECRET_VALUE"
    },
    "groupMappings": {
      "engineering": "SWARMD_GROUP_UUID"
    }
  }'
```

### Step 3: Set the Redirect URI

Copy the `redirectUri` from the response and paste it into your Entra app registration under **Redirect URIs**.

***

## Google Workspace

### Step 1: Create OAuth Credentials

1. Go to the [Google Cloud Console](https://console.cloud.google.com) and select your project.
2. Navigate to **APIs & Services** > **Credentials** > **Create Credentials** > **OAuth client ID**.
3. Select **Web application**, set the name to "Swarmd SSO".
4. Leave **Authorized redirect URIs** blank — you will get the URL from the Swarmd API response.
5. Click **Create** and copy the **Client ID** and **Client Secret**.

### Step 2: Create the Identity Provider in Swarmd

```bash theme={null}
curl -X POST https://api.swarmd.ai/tenant-auth/v1/identity-providers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "provider": "GOOGLE_WORKSPACE",
    "emailDomains": ["acme.com"],
    "config": {
      "type": "googleWorkspace",
      "clientId": "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com",
      "clientSecret": "YOUR_GOOGLE_CLIENT_SECRET"
    },
    "groupMappings": {
      "engineering@acme.com": "SWARMD_GROUP_UUID"
    }
  }'
```

### Step 3: Set the Redirect URI

Copy the `redirectUri` from the response and paste it into the Google Cloud Console under **Authorized redirect URIs**.

<Tip>
  Google Workspace group names in the `groups` claim are typically the group email address (e.g. `engineering@acme.com`). Make sure your `groupMappings` keys match exactly.
</Tip>

***

## Okta

### Step 1: Create an OIDC App Integration

1. In the [Okta Admin Console](https://admin.okta.com), go to **Applications** > **Create App Integration**.
2. Select **OIDC - OpenID Connect** and **Web Application**, then click **Next**.
3. Set the **App name** to "Swarmd SSO".
4. Leave the **Sign-in redirect URIs** blank — you will get the URL from the Swarmd API response.
5. Under **Assignments**, assign the users or groups that should have access.

### Step 2: Create the Identity Provider in Swarmd

```bash theme={null}
curl -X POST https://api.swarmd.ai/tenant-auth/v1/identity-providers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "provider": "OKTA",
    "emailDomains": ["acme.com"],
    "config": {
      "type": "okta",
      "domain": "acme.okta.com",
      "clientId": "YOUR_OKTA_CLIENT_ID",
      "clientSecret": "YOUR_OKTA_CLIENT_SECRET"
    },
    "groupMappings": {
      "engineering": "SWARMD_GROUP_UUID"
    }
  }'
```

### Step 3: Set the Redirect URI

Copy the `redirectUri` from the response and paste it into Okta under **Sign-in redirect URIs**.

***

## API Reference

### Create Identity Provider

`POST /v1/identity-providers`

| Field           | Required | Description                                                              |
| --------------- | -------- | ------------------------------------------------------------------------ |
| `displayName`   | No       | A human-readable name shown during SSO login. Auto-generated if omitted. |
| `provider`      | Yes      | `MICROSOFT_ENTRA`, `GOOGLE_WORKSPACE`, or `OKTA`                         |
| `emailDomains`  | Yes      | One or more email domains to associate with this provider.               |
| `config`        | Yes      | Provider-specific configuration (see tables below).                      |
| `groupMappings` | No       | Maps external group names to internal Swarmd group UUIDs.                |

### Microsoft Entra Config

| Key            | Required | Description                                                  |
| -------------- | -------- | ------------------------------------------------------------ |
| `tenantId`     | Yes      | Your Azure / Entra directory (tenant) ID                     |
| `clientId`     | Yes      | The application (client) ID from your Entra app registration |
| `clientSecret` | Yes      | The client secret value                                      |

### Google Workspace Config

| Key            | Required | Description                                       |
| -------------- | -------- | ------------------------------------------------- |
| `clientId`     | Yes      | The OAuth 2.0 client ID from Google Cloud Console |
| `clientSecret` | Yes      | The OAuth 2.0 client secret                       |

### Okta Config

| Key            | Required | Description                             |
| -------------- | -------- | --------------------------------------- |
| `domain`       | Yes      | Your Okta domain (e.g. `acme.okta.com`) |
| `clientId`     | Yes      | The OIDC client ID                      |
| `clientSecret` | Yes      | The OIDC client secret                  |

<Warning>
  Sensitive config values (`clientSecret`) are redacted in API responses. Store them securely — you will not be able to retrieve them after creation.
</Warning>

***

## Required JWT Claims

Regardless of which provider you use, Swarmd expects the following claims in the JWT:

| Claim         | Required | Description                                                               |
| ------------- | -------- | ------------------------------------------------------------------------- |
| `sub`         | Yes      | The identity provider's unique user identifier                            |
| `email`       | Yes      | The user's email address. Must match one of the configured email domains. |
| `given_name`  | No       | First name. Used when auto-provisioning new users.                        |
| `family_name` | No       | Last name. Used when auto-provisioning new users.                         |
| `groups`      | No       | A JSON array of group name strings. Required for automatic group mapping. |

***

## Group Mappings

Group mappings let you automatically assign users to Swarmd groups based on their identity provider group membership. The `groupMappings` field maps external group names to Swarmd group UUIDs:

```json theme={null}
{
  "groupMappings": {
    "engineering": "550e8400-e29b-41d4-a716-446655440001",
    "finance": "550e8400-e29b-41d4-a716-446655440002"
  }
}
```

| Provider                            | Typical `groups` Claim Format | Example Key                              |
| ----------------------------------- | ----------------------------- | ---------------------------------------- |
| Microsoft Entra ID (default)        | Group object ID (UUID)        | `"b1c2d3e4-f5a6-7890-abcd-ef1234567890"` |
| Microsoft Entra ID (sAMAccountName) | Group display name            | `"Engineering"`                          |
| Google Workspace                    | Group email address           | `"engineering@acme.com"`                 |
| Okta                                | Group name                    | `"engineering"`                          |

<Info>
  Keys are **case-sensitive**. Group membership is synced **on every SSO login**. Manually assigned groups are never removed by SSO sync.
</Info>

***

## Email Domain Rules

* Each domain can only be associated with one identity provider across the entire platform.
* Domains are normalised to lowercase. Maximum length is 253 characters.
* If a domain is already claimed by another provider, the request is rejected with `409 Conflict`.

***

## Login Discovery

```bash theme={null}
curl "https://api.swarmd.ai/tenant-auth/v1/login/discover?email=user@acme.com"
```

Returns available login methods. When SSO is configured, redirect the user to `ssoRedirectUrl`.

***

## SSO Callback

```bash theme={null}
curl -X POST https://api.swarmd.ai/tenant-auth/v1/sso/callback \
  -H "Content-Type: application/json" \
  -d '{"code": "AUTHORIZATION_CODE", "redirectUri": "https://app.swarmd.ai/auth/callback"}'
```

* **New users** are auto-provisioned into the tenant that owns the matching email domain.
* **Existing password users** are linked by email — no duplicate is created.
* **Returning SSO users** have group membership synced.

***

## Managing Identity Providers

### Updating

Only the fields you include are changed:

```bash theme={null}
curl -X PUT https://api.swarmd.ai/tenant-auth/v1/identity-providers/PROVIDER_ID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{"enabled": false}'
```

### Deleting

```bash theme={null}
curl -X DELETE https://api.swarmd.ai/tenant-auth/v1/identity-providers/PROVIDER_ID \
  -H "Authorization: Bearer $SWARMD_TOKEN"
```

<Warning>
  Deleting an identity provider releases its email domains and removes it from Keycloak. SSO-provisioned users do not have passwords — send them password reset emails before deleting.
</Warning>

***

## Disabling and Recovery

Disabling an IdP (`"enabled": false`) immediately stops SSO login for that domain.

If your identity provider goes down:

1. The **Tenant Administrator** logs in via password
2. Disables the identity provider
3. All domain users can now log in via password (or request a password reset)
4. Fix the IdP configuration, then re-enable

<Warning>
  Make sure your Tenant Administrator always has a password set.
</Warning>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="User Management" icon="users" href="/tutorials/user-management">
    Create custom groups and manage permissions for SSO-provisioned users.
  </Card>

  <Card title="Monitoring & Audit" icon="chart-line" href="/tutorials/monitoring-and-audit">
    Track SSO login events and identity provider changes in the audit log.
  </Card>
</CardGroup>