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:

Configure an identity provider — register your provider and associate it with one or more email domains.
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.
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.

You need the IDENTITY_PROVIDERS permission to manage identity providers. Users in the Tenant Administrator group have this by default. See User Management for details on permissions.

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

Go to the Azure Portal and navigate to Microsoft Entra ID > App registrations > New registration.
Set the Name to “Swarmd SSO”.
Under Redirect URIs, select Web and leave it blank — you will get the exact URL from the Swarmd API response.
Click Register.
Go to Certificates & secrets > Client secrets > New client secret. Copy the Value immediately.
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

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

Go to the Google Cloud Console and select your project.
Navigate to APIs & Services > Credentials > Create Credentials > OAuth client ID.
Select Web application, set the name to “Swarmd SSO”.
Leave Authorized redirect URIs blank — you will get the URL from the Swarmd API response.
Click Create and copy the Client ID and Client Secret.

Step 2: Create the Identity Provider in Swarmd

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.

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.

Okta

Step 1: Create an OIDC App Integration

In the Okta Admin Console, go to Applications > Create App Integration.
Select OIDC - OpenID Connect and Web Application, then click Next.
Set the App name to “Swarmd SSO”.
Leave the Sign-in redirect URIs blank — you will get the URL from the Swarmd API response.
Under Assignments, assign the users or groups that should have access.

Step 2: Create the Identity Provider in Swarmd

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

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

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:

{
  "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"`

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

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.

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

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:

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

curl -X DELETE https://api.swarmd.ai/tenant-auth/v1/identity-providers/PROVIDER_ID \
  -H "Authorization: Bearer $SWARMD_TOKEN"

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.

Disabling and Recovery

Disabling an IdP ("enabled": false) immediately stops SSO login for that domain. If your identity provider goes down:

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

Make sure your Tenant Administrator always has a password set.

Next Steps

User Management

Create custom groups and manage permissions for SSO-provisioned users.

Monitoring & Audit

Track SSO login events and identity provider changes in the audit log.

Getting Started

Platform Management

Identity Providers

Identity Providers

Supported Providers

Microsoft Entra ID

Step 1: Register an Application in Entra ID

Step 2: Create the Identity Provider in Swarmd

Step 3: Set the Redirect URI

Google Workspace

Step 1: Create OAuth Credentials

Step 2: Create the Identity Provider in Swarmd

Step 3: Set the Redirect URI

Okta

Step 1: Create an OIDC App Integration

Step 2: Create the Identity Provider in Swarmd

Step 3: Set the Redirect URI

API Reference

Create Identity Provider

Microsoft Entra Config

Google Workspace Config

Okta Config

Required JWT Claims

Group Mappings

Email Domain Rules

SSO Callback

Managing Identity Providers

Updating

Deleting

Disabling and Recovery

Next Steps

User Management

Monitoring & Audit

Getting Started

Platform Management

​Identity Providers

​Supported Providers

​Microsoft Entra ID

​Step 1: Register an Application in Entra ID

​Step 2: Create the Identity Provider in Swarmd

​Step 3: Set the Redirect URI

​Google Workspace

​Step 1: Create OAuth Credentials

​Step 2: Create the Identity Provider in Swarmd

​Step 3: Set the Redirect URI

​Okta

​Step 1: Create an OIDC App Integration

​Step 2: Create the Identity Provider in Swarmd

​Step 3: Set the Redirect URI

​API Reference

​Create Identity Provider

​Microsoft Entra Config

​Google Workspace Config

​Okta Config

​Required JWT Claims

​Group Mappings

​Email Domain Rules

​Login Discovery

​SSO Callback

​Managing Identity Providers

​Updating

​Deleting

​Disabling and Recovery

​Next Steps

User Management

Monitoring & Audit

Identity Providers

Supported Providers

Microsoft Entra ID

Step 1: Register an Application in Entra ID

Step 2: Create the Identity Provider in Swarmd

Step 3: Set the Redirect URI

Google Workspace

Step 1: Create OAuth Credentials

Step 2: Create the Identity Provider in Swarmd

Step 3: Set the Redirect URI

Okta

Step 1: Create an OIDC App Integration

Step 2: Create the Identity Provider in Swarmd

Step 3: Set the Redirect URI

API Reference

Create Identity Provider

Microsoft Entra Config

Google Workspace Config

Okta Config

Required JWT Claims

Group Mappings

Email Domain Rules

Login Discovery

SSO Callback

Managing Identity Providers

Updating

Deleting

Disabling and Recovery

Next Steps