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

# SSO Support

> Configure Single Sign-On using OIDC or SAML 2.0 with your identity provider

## Introduction

Bland supports both OIDC (OpenID Connect) and SAML 2.0 based Single Sign-On (SSO) for enterprise workspaces. This enables your users to authenticate with their existing identity provider (IdP) — such as Okta, Azure Active Directory, Google Workspace, Auth0, or any SAML 2.0 compatible provider — instead of managing separate Bland credentials.

Once connected, users from your domain can log in with **Sign in with SSO**, and new users will be provisioned automatically into your workspace.

<Info>
  **New:** Bland now supports both OIDC and SAML protocols. Choose OIDC for simpler setup and modern authentication, or SAML for enterprise compliance and legacy system compatibility.
</Info>

***

## Prerequisites

Before configuring SSO, ensure you have:

* Admin access to your Bland organization
* Admin access to your identity provider (IdP)
* Your organization's verified email domain (e.g., `company.com`)
* For SAML: Understanding of X.509 certificates and metadata
* For OIDC: Ability to create OAuth 2.0 applications

***

## Quick Start

<Steps>
  <Step title="Open SSO Setup Wizard">
    Navigate to **Settings → SSO** in Bland and click **Add Provider**. The setup wizard will guide you through the process.
  </Step>

  <Step title="Choose Your Identity Provider">
    Select your IdP (Google Workspace, Okta, Azure AD, or other). The wizard will recommend the best protocol:

    **OIDC** - Recommended for: Google Workspace, Okta, Azure AD, Auth0, and most modern IdPs

    **SAML** - Use when: Required by security policy, Microsoft ADFS, or when your IdP only supports SAML
  </Step>

  <Step title="Configure Your IdP">
    The wizard shows the callback URLs you need to configure in your identity provider. Copy them and create an application in your IdP.
  </Step>

  <Step title="Enter Credentials">
    Paste the Client ID, Client Secret (OIDC) or certificate/metadata (SAML) from your IdP into the wizard.
  </Step>

  <Step title="Test Connection">
    Use the **Test** button in Bland to verify the configuration works.
  </Step>
</Steps>

***

## Okta Configuration

### Okta OIDC Setup

<AccordionGroup>
  <Accordion title="Step 1: Create OIDC Application">
    1. Sign in to [Okta Admin Console](https://admin.okta.com)
    2. Go to **Applications** → **Applications**
    3. Click **Create App Integration**
    4. Select **OIDC - OpenID Connect** as the Sign-in method
    5. Select **Web Application** as the Application type
    6. Click **Next**
  </Accordion>

  <Accordion title="Step 2: Configure Application">
    **General Settings:**

    * **App integration name**: `Bland SSO`
    * **Logo**: (Optional) Upload your company logo

    **Grant Type:**

    * ✅ Authorization Code
    * ✅ Refresh Token (recommended)
    * ❌ Implicit (not recommended)

    **Sign-in redirect URIs:**

    ```
    https://api.bland.ai/authorization/sso/callback/[provider-id]
    ```

    <Info>Replace `[provider-id]` with your chosen Provider ID (e.g., `company-okta`)</Info>

    **Sign-out redirect URIs:** (Optional)

    ```
    https://app.bland.ai/logout
    ```

    **Controlled access:**

    * **Allow everyone in your organization to access** (recommended for company-wide SSO)
    * **Limit access to selected groups** (if you want to control access)

    Click **Save**
  </Accordion>

  <Accordion title="Step 3: Configure Claims (Optional)">
    For role mapping:

    1. Go to **Sign On** tab → **OpenID Connect ID Token** → **Edit**
    2. Click **Add Claim**
    3. Configure:
       * **Name**: `groups`
       * **Include in**: ID Token, Access Token
       * **Value type**: Groups
       * **Filter**: `.*` (for all groups)
       * **Include in**: Any scope
    4. Click **Create**
  </Accordion>

  <Accordion title="Step 4: Get Configuration Details">
    From the **Sign On** tab, copy:

    * **Issuer**: `https://[your-okta-domain].okta.com`
    * **Client ID**: The long alphanumeric string
    * **Client Secret**: Click the eye icon to reveal

    Okta provides automatic discovery at:

    ```
    https://[your-okta-domain].okta.com/.well-known/openid-configuration
    ```
  </Accordion>

  <Accordion title="Step 5: Configure in Bland">
    1. Go to **Settings** → **SSO** → **Add Provider**
    2. Select **OIDC (OpenID Connect)** as Provider Type
    3. Enter:
       * **Provider ID**: Your chosen ID (e.g., `company-okta`) or leave blank to auto-generate
       * **Email Domain**: `company.com`
       * **Issuer URL**: From Okta (e.g., `https://dev-12345.okta.com`)
       * **Client ID**: From Okta
       * **Client Secret**: From Okta
    4. Optional: Configure scopes (defaults to `openid email profile`)
    5. Optional: Enable PKCE for enhanced security (recommended)
    6. Click **Add Provider**

    <Note>Bland will automatically discover OIDC endpoints from the issuer URL. If auto-discovery fails, you can manually specify endpoints in the Optional Endpoints section.</Note>
  </Accordion>
</AccordionGroup>

### Okta SAML Setup

<AccordionGroup>
  <Accordion title="Step 1: Create SAML Application">
    1. In Okta Admin, go to **Applications** → **Applications**
    2. Click **Create App Integration**
    3. Select **SAML 2.0** as the Sign-in method
    4. Click **Next**
    5. Enter **App name**: `Bland SSO`
    6. Click **Next**
  </Accordion>

  <Accordion title="Step 2: Configure SAML">
    **General:**

    * **Single sign-on URL**:
      ```
      https://api.bland.ai/authorization/sso/saml2/callback/[provider-id]
      ```
    * ✅ **Use this for Recipient URL and Destination URL**
    * **Audience URI (SP Entity ID)**:
      ```
      https://api.bland.ai/sp/[provider-id]
      ```
    * **Name ID format**: `EmailAddress`
    * **Application username**: `Email`
  </Accordion>

  <Accordion title="Step 3: Configure Attributes">
    Add these attribute statements:

    | Name      | Name Format | Value            |
    | --------- | ----------- | ---------------- |
    | email     | Unspecified | user.email       |
    | firstName | Unspecified | user.firstName   |
    | lastName  | Unspecified | user.lastName    |
    | name      | Unspecified | user.displayName |

    For role mapping, add Group Attribute:

    | Name  | Name Format | Filter |
    | ----- | ----------- | ------ |
    | roles | Unspecified | .\*    |
  </Accordion>

  <Accordion title="Step 4: Get SAML Configuration">
    1. Go to **Sign On** tab → **View SAML setup instructions**
    2. Copy:
       * **Identity Provider Issuer**
       * **Identity Provider Single Sign-On URL**
       * **X.509 Certificate** (entire content)
    3. Or download the metadata XML
  </Accordion>

  <Accordion title="Step 5: Configure in Bland">
    1. Go to **Settings** → **SSO** → **Add Provider**
    2. Select **SAML 2.0** as Provider Type
    3. Enter basic configuration:
       * **Provider ID**: Your chosen ID (e.g., `company-okta-saml`) or leave blank to auto-generate
       * **Email Domain**: `company.com`
       * **Issuer URL**: Identity Provider Issuer from Okta
    4. Choose configuration method:

       **Option 1: Metadata Import (Recommended)**

       * Paste the metadata XML from Okta, or
       * Provide the metadata URL (may have CORS issues locally)

       **Option 2: Manual Configuration**

       * **Entry Point**: Identity Provider Single Sign-On URL from Okta
       * **X.509 Certificate**: Paste the entire certificate including BEGIN/END lines
    5. Click **Add Provider**
    6. Download SP metadata using the "Metadata" button and upload to Okta if needed
  </Accordion>
</AccordionGroup>

***

## Azure AD (Microsoft Entra ID)

### Azure AD OIDC Setup

<AccordionGroup>
  <Accordion title="Step 1: Register Application">
    1. Sign in to [Azure Portal](https://portal.azure.com)
    2. Go to **Azure Active Directory** → **App registrations**
    3. Click **New registration**
    4. Configure:
       * **Name**: `Bland SSO`
       * **Supported account types**: Accounts in this organizational directory only
       * **Redirect URI**: Web → `https://api.bland.ai/authorization/sso/callback/[provider-id]`
         (Replace `[provider-id]` with your chosen ID, e.g., `company-azure`)
    5. Click **Register**
    6. Copy the **Application (client) ID** and **Directory (tenant) ID**
  </Accordion>

  <Accordion title="Step 2: Create Client Secret">
    1. Go to **Certificates & secrets** → **Client secrets**
    2. Click **New client secret**
    3. Description: `Bland SSO Secret`
    4. Choose expiration (12-24 months recommended)
    5. Click **Add**
    6. **IMMEDIATELY copy the secret value** (won't be shown again)
  </Accordion>

  <Accordion title="Step 3: Configure Permissions">
    1. Go to **API permissions**
    2. Click **Add a permission** → **Microsoft Graph** → **Delegated permissions**
    3. Add:
       * `openid`
       * `profile`
       * `email`
       * `User.Read`
    4. Click **Grant admin consent for \[Organization]**
  </Accordion>

  <Accordion title="Step 4: Configure Token Claims">
    1. Go to **Token configuration**
    2. Click **Add optional claim** → **ID**
    3. Select: `email`, `family_name`, `given_name`, `preferred_username`
    4. For role mapping, click **Add groups claim**:
       * Select **Security groups**
       * Under **ID**, select **Group ID**
  </Accordion>

  <Accordion title="Step 5: Configure in Bland">
    1. In Bland, go to **Settings** → **SSO** → **Add Provider**
    2. Select **OIDC (OpenID Connect)**
    3. Enter:
       * **Provider ID**: Your chosen ID (e.g., `company-azure`) or leave blank to auto-generate
       * **Email Domain**: `company.com`
       * **Issuer URL**: `https://login.microsoftonline.com/[tenant-id]/v2.0`
         (Replace `[tenant-id]` with your Directory (tenant) ID)
       * **Client ID**: Application (client) ID from Azure
       * **Client Secret**: Secret value from Azure
    4. Optional: Configure scopes (defaults to `openid email profile`)
    5. Click **Add Provider**

    <Note>Azure AD endpoints will be automatically discovered. The issuer URL must include `/v2.0` for the v2.0 endpoint.</Note>
  </Accordion>
</AccordionGroup>

### Azure AD SAML Setup

<AccordionGroup>
  <Accordion title="Step 1: Create Enterprise Application">
    1. In Azure AD, go to **Enterprise applications**
    2. Click **New application** → **Create your own application**
    3. Name: `Bland SSO SAML`
    4. Select: **Integrate any other application you don't find in the gallery**
    5. Click **Create**
  </Accordion>

  <Accordion title="Step 2: Configure SAML">
    1. Go to **Single sign-on** → Select **SAML**
    2. Edit **Basic SAML Configuration**:
       * **Identifier (Entity ID)**: `https://api.bland.ai/sp/[provider-id]`
         (Replace `[provider-id]` with your chosen ID, e.g., `company-azure-saml`)
       * **Reply URL**: `https://api.bland.ai/authorization/sso/saml2/callback/[provider-id]`
       * **Sign on URL**: `https://app.bland.ai/login`
  </Accordion>

  <Accordion title="Step 3: Configure Attributes">
    Edit **User Attributes & Claims**:

    | Claim Name   | Source Attribute |
    | ------------ | ---------------- |
    | emailaddress | user.mail        |
    | givenname    | user.givenname   |
    | surname      | user.surname     |
    | name         | user.displayname |

    Simplify by editing each claim name to: `email`, `firstName`, `lastName`, `name`
  </Accordion>

  <Accordion title="Step 4: Download Certificate">
    1. In **SAML Certificates**, download **Certificate (Base64)**
    2. Copy **Login URL** and **Azure AD Identifier**
  </Accordion>

  <Accordion title="Step 5: Configure in Bland">
    1. Go to **Settings** → **SSO** → **Add Provider**
    2. Select **SAML 2.0** as Provider Type
    3. Enter basic configuration:
       * **Provider ID**: Your chosen ID (e.g., `company-azure-saml`) or leave blank to auto-generate
       * **Email Domain**: `company.com`
       * **Issuer URL**: Azure AD Identifier from Step 4
    4. Choose configuration method:

       **Option 1: Manual Configuration**

       * **Entry Point**: Login URL from Azure
       * **X.509 Certificate**: Paste the downloaded certificate (Base64)

       **Option 2: Metadata Import**

       * Download Federation Metadata XML from Azure
       * Paste the entire XML in the IdP Metadata XML field
    5. Click **Add Provider**
    6. Download SP metadata using the "Metadata" button if needed by Azure
  </Accordion>
</AccordionGroup>

### Azure AD Compliance & Advanced Features

**Compliance Considerations:**

* Azure AD provides detailed audit logs with configurable retention
* Use **Privileged Identity Management (PIM)** for just-in-time admin access
* Enable **Identity Protection** for risk-based conditional access
* Configure log retention per compliance requirements (GDPR, HIPAA, etc.)

**Advanced Security:**

* **Conditional Access Policies**: Require MFA, restrict by location/device
* **Risk-Based Policies**: Block or challenge risky sign-ins
* **Device Compliance**: Require managed/compliant devices

***

## Google Workspace

### Google Workspace OIDC Setup (Recommended)

<Info>
  OIDC is the recommended approach for Google Workspace. It's simpler to configure and uses standard OAuth 2.0.
</Info>

<AccordionGroup>
  <Accordion title="Step 1: Create OAuth 2.0 Credentials">
    1. Go to [Google Cloud Console](https://console.cloud.google.com)
    2. Select or create a project for your organization
    3. Navigate to **APIs & Services** > **Credentials**
    4. Click **Create Credentials** > **OAuth client ID**
    5. If prompted, configure the **OAuth consent screen** first:
       * Select **Internal** (restricts to your organization)
       * Fill in app name: `Bland SSO`
       * Add scopes: `openid`, `email`, `profile`
       * Save
    6. Back in Credentials, select Application type: **Web application**
    7. Name: `Bland SSO`
    8. Under **Authorized redirect URIs**, add:
       ```
       https://api.bland.ai/authorization/sso/callback/[provider-id]
       ```
       <Info>Replace `[provider-id]` with your chosen Provider ID (e.g., `company-google`). If you don't know it yet, you can update this after creating the provider in Bland.</Info>
    9. Click **Create**
    10. Copy the **Client ID** and **Client Secret**
  </Accordion>

  <Accordion title="Step 2: Configure in Bland">
    1. Go to **Settings** > **SSO** > **Add Provider**
    2. Select **Google Workspace** (the wizard will use OIDC automatically)
    3. Enter:
       * **Email Domain**: `company.com`
       * **Client ID**: From Google Cloud Console
       * **Client Secret**: From Google Cloud Console
       * Issuer is pre-filled as `https://accounts.google.com`
    4. Click **Create**
    5. If you auto-generated the Provider ID, copy it and update the redirect URI in Google Cloud Console

    <Note>OIDC endpoints are automatically discovered from Google's well-known configuration. No manual endpoint setup is needed.</Note>
  </Accordion>

  <Accordion title="Step 3: Configure Group Claims (Optional)">
    For role mapping based on Google Groups:

    1. In Google Cloud Console, enable the **Google Workspace Admin SDK**
    2. Configure your OAuth app to request the `groups` scope
    3. Create Google Groups matching Bland's role patterns:
       * `bland-admin@company.com` for Admin role
       * `bland-operator@company.com` for Operator role
       * `bland-viewer@company.com` for Viewer role
  </Accordion>
</AccordionGroup>

### Google Workspace SAML Setup

<Info>
  Google Workspace also supports SAML 2.0 via the Admin Console. Use this if your organization requires SAML for compliance reasons.
</Info>

<Steps>
  <Step title="Access Admin Console">
    Sign in to [Google Admin Console](https://admin.google.com) with Super Admin account
  </Step>

  <Step title="Add Custom SAML App">
    1. Go to **Apps** > **Web and mobile apps**
    2. Click **Add app** > **Add custom SAML app**
    3. Enter:
       * **App name**: `Bland SSO`
       * **App description**: `Single Sign-On for Bland AI`
    4. Click **Continue**
  </Step>

  <Step title="Download IdP Metadata">
    Download or copy:

    * **SSO URL**
    * **Entity ID**
    * **Certificate**
    * Or download the full metadata XML

    Click **Continue**
  </Step>

  <Step title="Configure Service Provider">
    Enter:

    * **ACS URL**: `https://api.bland.ai/authorization/sso/saml2/callback/[provider-id]`
      (Replace `[provider-id]` with your chosen ID, e.g., `company-google`)
    * **Entity ID**: `https://api.bland.ai/sp/[provider-id]`
    * **Start URL**: `https://app.bland.ai/login` (optional)
    * **Signed response**: Checked
    * **Name ID format**: `EMAIL`
    * **Name ID**: `Basic Information > Primary email`
  </Step>

  <Step title="Configure Attributes">
    Map these attributes:

    | Google Directory | App Attribute |
    | ---------------- | ------------- |
    | Primary email    | email         |
    | First name       | firstName     |
    | Last name        | lastName      |
    | Full name        | name          |
  </Step>

  <Step title="Configure in Bland">
    1. Go to **Settings** > **SSO** > **Add Provider**
    2. Select **Other (SAML)** as Provider Type
    3. Enter:
       * **Email Domain**: `company.com`
       * **Issuer URL**: Entity ID from Google
    4. Provide your SAML configuration:
       * **Option 1: Metadata Import** — Paste the metadata XML from Google
       * **Option 2: Manual** — Enter the SSO URL and Certificate
    5. Click **Create**
    6. Enable the app for desired organizational units in Google Admin Console
  </Step>
</Steps>

<Warning>
  Google Workspace SAML changes can take up to 24 hours to propagate, though typically activate within 15 minutes.
</Warning>

### Google Workspace Security Features

**Context-Aware Access:**

* Configure access levels based on device trust status, IP location, and user/group membership

**Compliance and Logging:**

* **Access Transparency**: Logs of admin actions (Enterprise editions)
* **Data Regions**: Configure data residency requirements
* **Audit Logs**: Export SAML events to BigQuery for analysis
* **SIEM Integration**: Connect logs to security monitoring tools

**Password Security:**

* Enable password alert for compromised passwords
* Configure strong password requirements
* Regular rotation policies

***

## Other Identity Providers

### Auth0

<AccordionGroup>
  <Accordion title="OIDC Configuration">
    1. Create new Application → Regular Web Application
    2. Settings:
       * **Allowed Callback URLs**: `https://api.bland.ai/authorization/sso/callback/[provider-id]`
         (Replace `[provider-id]` with your chosen ID, e.g., `company-auth0`)
       * **Allowed Web Origins**: `https://app.bland.ai`
    3. In Bland, configure with:
       * **Provider ID**: Your chosen ID or leave blank to auto-generate
       * **Email Domain**: Your organization's email domain
       * **Issuer**: `https://[your-domain].auth0.com/`
       * **Client ID** and **Client Secret** from Auth0
    4. Auth0 endpoints will be auto-discovered from the issuer URL
  </Accordion>

  <Accordion title="SAML Configuration">
    1. Create new Application → Regular Web Application
    2. Enable SAML2 Web App addon
    3. Configure:
       * **Application Callback URL**: `https://api.bland.ai/authorization/sso/saml2/callback/[provider-id]`
         (Replace `[provider-id]` with your chosen ID)
       * **Settings**: Configure attribute mappings for email, firstName, lastName
    4. In Bland, add SAML provider with:
       * **Provider ID**: Your chosen ID or leave blank to auto-generate
       * Auth0's metadata or manual configuration
  </Accordion>
</AccordionGroup>

### Ping Identity

Both OIDC and SAML supported:

* **OIDC**: Configure redirect URI with your chosen provider ID
* **SAML**: Use SP Entity ID format `https://api.bland.ai/sp/[provider-id]`
* Provider ID can be specified or auto-generated in Bland

### OneLogin

Supports both protocols:

* Create app from catalog or custom connector
* Configure with your chosen provider ID in all endpoints
* Download SP metadata from Bland after provider creation for SAML

***

## URL Reference

### OIDC Endpoints

| Endpoint     | URL Format                                                      | Notes                                       |
| ------------ | --------------------------------------------------------------- | ------------------------------------------- |
| Redirect URI | `https://api.bland.ai/authorization/sso/callback/[provider-id]` | Replace `[provider-id]` with your chosen ID |
| Discovery    | Auto-discovery from issuer URL                                  | Endpoints fetched automatically             |

### SAML Endpoints

| Endpoint     | URL Format                                                            | Notes                          |
| ------------ | --------------------------------------------------------------------- | ------------------------------ |
| ACS URL      | `https://api.bland.ai/authorization/sso/saml2/callback/[provider-id]` | Assertion Consumer Service URL |
| SP Entity ID | `https://api.bland.ai/sp/[provider-id]`                               | Service Provider identifier    |
| SP Metadata  | Generated after provider creation                                     | Download from SSO settings     |

<Note>
  **Provider ID**: You can specify your own provider ID (e.g., `company-okta`, `acme-azure`) or leave it blank to auto-generate. Once created, the provider ID cannot be changed.
</Note>

***

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Authentication fails with redirect/callback error">
    **Cause**: URL mismatch between Bland and your IdP

    **Solution**:

    * **OIDC**: Verify redirect URI matches exactly: `https://api.bland.ai/authorization/sso/callback/[provider-id]`
    * **SAML**: Verify ACS URL matches: `https://api.bland.ai/authorization/sso/saml2/callback/[provider-id]`
    * Check for trailing slashes, extra spaces, or HTTP vs HTTPS
    * Ensure the provider ID is identical in both Bland and your IdP
  </Accordion>

  <Accordion title="Invalid credentials or signature errors">
    **Cause**: Wrong, expired, or mismatched credentials

    **Solution for OIDC**:

    * Regenerate client secret in your IdP and update in Bland immediately
    * Verify no extra spaces when pasting credentials
    * Check the issuer URL format (Azure needs `/v2.0`, Okta may need `/oauth2/default`)

    **Solution for SAML**:

    * Re-download the certificate from your IdP
    * Include the full certificate with `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines
    * Check certificate expiration date
  </Accordion>

  <Accordion title="Audience/Entity ID validation failed (SAML)">
    **Cause**: SP Entity ID mismatch

    **Solution**:

    * Ensure Entity ID matches exactly: `https://api.bland.ai/sp/[provider-id]`
    * Use the same provider ID in both Bland and your IdP
    * If you auto-generated the ID in Bland, copy it to your IdP configuration
  </Accordion>

  <Accordion title="User not being provisioned or account_not_found">
    **Cause**: Missing or incorrect user attributes

    **Solution**:

    * Verify attribute mappings in your IdP (email is required)
    * Ensure the user has an email address in their IdP profile
    * For SAML: Set NameID format to `emailAddress` and use "Unspecified" for attribute name format
    * Check that attributes are actually being sent in the authentication response
  </Accordion>

  <Accordion title="User gets wrong role or default role">
    **Cause**: Groups not being sent in token/assertion, or group names don't match expected patterns

    **Solution**:

    * Verify groups claim is configured in your IdP
    * Check that the user is a member of the expected groups
    * For OIDC: Ensure the `groups` scope is requested
    * For Okta: Ensure groups are assigned to the application, not just users
    * Use browser DevTools or SAML tracer to inspect the actual groups being sent
    * Users without matching groups default to the `viewer` role
  </Accordion>
</AccordionGroup>

### Testing Your Configuration

1. **Use Test Button**: In Bland SSO settings, click Test next to your provider
2. **Check Browser Console**: Open Developer Tools (F12) → Network tab for detailed errors
3. **Verify in IdP**: Check IdP audit logs for authentication attempts
4. **Test with Different User**: Try a non-admin account to verify permissions
5. **Test in Incognito Mode**: Always test in incognito/private browsing mode to avoid cached sessions

### Advanced Debugging Tools

**For SAML:**

* [SAML Chrome Panel](https://chrome.google.com/webstore/detail/saml-chrome-panel) - Chrome extension
* [SAML-tracer](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/) - Firefox addon
* Capture and decode SAML responses to verify attributes

**For OIDC:**

* Use [jwt.io](https://jwt.io) to decode ID tokens
* Verify `iss` (issuer), `aud` (audience), and claims

**Network Analysis:**

* Export HAR file from browser Network tab for support

### Debug Checklist

* [ ] Email domain matches exactly (no www, no subdomains)
* [ ] Provider is active in Bland settings
* [ ] User is assigned to application in IdP
* [ ] URLs updated with actual provider ID
* [ ] Certificates valid and not expired (SAML)
* [ ] Client secrets valid and not expired (OIDC)
* [ ] Attributes properly mapped
* [ ] Test button works successfully

***

## Security Best Practices

### Certificate & Secret Management

<Warning>
  **Critical**: Set calendar reminders 30 days before certificate and secret expiration!
</Warning>

* **SAML Certificates**:
  * Monitor expiration dates (typically 1-3 years)
  * Rotate during low-usage periods
  * Keep backup of current working certificates
* **OIDC Secrets**:
  * Rotate every 6-12 months
  * Regenerate in IdP first, then update in Bland immediately
  * Never share secrets via email or chat
* **Document rotation procedures** for your team
* **Test immediately** after rotation with non-admin account

### Access Control

1. **Use Groups**: Manage access via IdP groups rather than individual assignments
2. **Regular Audits**: Review SSO access quarterly
3. **Immediate Revocation**: Remove departing employees promptly
4. **MFA Enforcement**: Require multi-factor authentication in your IdP

### Monitoring

* Enable SSO audit logging in your IdP
* Monitor failed authentication attempts
* Set up alerts for unusual patterns
* Review logs during security incidents
* **Regular Reviews:**
  * Audit user access monthly
  * Review IdP logs weekly
  * Check for deprecated features quarterly

### Platform-Specific Security Recommendations

**Okta:**

* Don't assign to "Everyone" unless intended
* Use Okta Verify or hardware tokens for higher security
* Review system logs for suspicious activity regularly

**Azure AD:**

* Use Conditional Access for location/device restrictions
* Enable risk-based authentication policies
* Implement Privileged Identity Management (PIM)

**Google Workspace:**

* Enable Context-Aware Access levels
* Use Security Keys for admin accounts
* Configure data residency requirements

***

## Role Mapping & Group Inheritance

Bland automatically maps IdP groups and roles to organization permissions, enabling seamless role inheritance from your existing identity provider.

### How It Works

When users sign in via SSO, Bland reads their group memberships from the IdP and automatically assigns the appropriate role in your organization.

### Supported Group Mappings

Groups are mapped based on their names. The following patterns are recognized:

**Admin Role:**

* `Bland AI - Static - Admin`
* `bland-admin`
* Groups containing: `admin`, `administrator`, `owner`, `manager`, `super`
* Example: `IT-Admin`, `Super-Users`, `Organization-Administrators`

**Operator Role:**

* `Bland AI - Static - Operator`
* `bland-operator`
* Groups containing: `operator`, `support`
* Example: `Support-Team`, `Call-Operators`

**Prompter Role:**

* `Bland AI - Static - Prompter`
* `bland-prompter`
* Groups containing: `prompt`, `editor`
* Example: `Content-Editors`, `Prompt-Engineers`

**Viewer Role (Read-Only):**

* `Bland AI - Static - Viewer`
* `bland-viewer`
* Groups containing: `viewer`, `read-only`, `readonly`
* Example: `Read-Only-Users`, `Audit-Viewers`

**Default:** Users without matching groups receive the `viewer` role.

### IdP-Specific Configuration

<AccordionGroup>
  <Accordion title="Okta Configuration">
    1. **Create Groups** in Okta Directory → Groups:
       * `Bland AI - Static - Admin`
       * `Bland AI - Static - Operator`
       * `Bland AI - Static - Viewer`

    2. **Assign Groups to Application:**
       * Go to your Bland SSO app → Assignments
       * Assign the groups (not just users)

    3. **Configure Groups Claim:**
       * Go to Security → API → Authorization Servers → Your Server
       * Claims tab → Add Claim
       * Name: `groups`
       * Include in: ID Token
       * Value type: Groups
       * Filter: Matches regex `.*`

    4. **Add Groups Scope** (if needed):
       * Scopes tab → Add Scope
       * Name: `groups`
       * Display: Access to user groups
  </Accordion>

  <Accordion title="Azure AD Configuration">
    1. **Create Security Groups:**
       * Azure AD → Groups → New Group
       * Type: Security
       * Names: `Bland AI - Static - Admin`, etc.

    2. **Configure Groups Claim:**
       * App Registration → Token configuration
       * Add groups claim → Security groups
       * Select: Group ID

    3. **Map Group Names (Optional):**
       * Enterprise App → Single sign-on → Attributes & Claims
       * Add group claim with transformation to send group names instead of IDs
  </Accordion>

  <Accordion title="Google Workspace Configuration">
    For SAML with Google Workspace:

    1. **Create Groups** in Google Admin:
       * Groups → Create Group
       * Names: `bland-admin@company.com`, etc.

    2. **Configure Group Attribute:**
       * In SAML app configuration
       * Add attribute: `groups`
       * Google Directory attribute: `Groups`
       * Filter: Can specify specific groups or all
  </Accordion>

  <Accordion title="ADFS Configuration">
    1. **Configure Group Claims:**
       * Edit Claim Rules → Add Rule
       * Send LDAP Attributes as Claims
       * Attribute: Token-Groups - Unqualified Names
       * Outgoing Claim Type: `groups`

    2. **Or use Role Claims:**
       * Send LDAP Attributes as Claims
       * Attribute: Token-Groups - Unqualified Names
       * Outgoing Claim Type: `http://schemas.microsoft.com/ws/2008/06/identity/claims/role`
  </Accordion>
</AccordionGroup>

### Dynamic Role Updates

* **Automatic Sync:** Roles are checked and updated on each login
* **Immediate Effect:** Role changes in your IdP take effect on next user login
* **No Manual Updates:** Admins don't need to manually manage user roles in Bland

### Custom Role Mapping

For enterprise customers with specific requirements:

* **Custom Group Names:** Map your existing group structure
* **Complex Rules:** Combine multiple groups or attributes
* **Department-Based:** Map based on department or other attributes

<Info>
  Contact [hello@bland.ai](mailto:hello@bland.ai) for custom role mapping configuration.
</Info>

### Testing Role Mapping

1. **Verify Groups in Token:**
   * Use browser DevTools during SSO login
   * Check Network tab for the callback request
   * For OIDC: Decode the ID token at [jwt.io](https://jwt.io)
   * For SAML: Use SAML Chrome Panel or SAML-tracer
   * Confirm `groups` claim contains expected values

2. **Check Role Assignment:**
   * After login, verify user role in Organization Settings → Members
   * Admin users see full settings access and can manage members
   * Operators have standard access to make and manage calls
   * Viewers have read-only access to view calls and analytics

3. **Test Different Scenarios:**
   * User with single group membership
   * User with multiple groups (highest privilege wins)
   * User with no groups (defaults to operator)
   * Group name changes in IdP

### Troubleshooting Group Inheritance

<AccordionGroup>
  <Accordion title="Groups not appearing in token">
    **Solution:**

    * Verify groups claim is configured in IdP
    * Check user is member of groups
    * Ensure groups are assigned to application (Okta)
    * Confirm groups scope is requested (OIDC)
  </Accordion>

  <Accordion title="Wrong role assigned">
    **Solution:**

    * Check exact group names in token
    * Verify group name matches mapping pattern
    * Look for typos or case sensitivity issues
    * Confirm no conflicting group memberships
  </Accordion>

  <Accordion title="Role not updating">
    **Solution:**

    * User must log out and log in again
    * Clear browser cookies/cache
    * Verify group membership changed in IdP
    * Check IdP audit logs for group changes
  </Accordion>
</AccordionGroup>

***

## Important Notes

<Note>
  * Users signing in via SSO still need to verify their phone number during first-time setup (unless "Skip phone verification" is enabled)
  * SSO users are automatically added to your organization with the `viewer` role by default (role can be upgraded via group mapping)
  * Each email domain can only be configured for one organization
  * Existing users are automatically converted to SSO on first SSO login
</Note>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Which protocol should I choose: OIDC or SAML?">
    **Choose OIDC if:**

    * You're using Google Workspace, Okta, Auth0, or Azure AD
    * You want simpler configuration
    * You need refresh tokens
    * Starting fresh with SSO

    **Choose SAML if:**

    * Mandated by your security policy
    * You need encrypted assertions
    * Integrating with legacy systems (ADFS, older IdPs)
    * Your organization already uses SAML for other applications
  </Accordion>

  <Accordion title="What's the easiest way to set up SSO with Google Workspace?">
    Use **OIDC** (OpenID Connect). Create an OAuth 2.0 client in [Google Cloud Console](https://console.cloud.google.com/apis/credentials), copy the Client ID and Secret into Bland's setup wizard, and you're done. The issuer URL (`https://accounts.google.com`) is pre-filled automatically. Google Workspace SAML is also supported if required by your organization's security policy.
  </Accordion>

  <Accordion title="Can I have multiple SSO providers?">
    Yes! You can configure multiple providers for:

    * Different domains
    * Different protocols (OIDC and SAML)
    * Different identity providers

    Each domain can only be assigned to one provider.
  </Accordion>

  <Accordion title="What happens to existing users?">
    Existing users are automatically linked when they first sign in with SSO. Their data, settings, and permissions remain intact.
  </Accordion>

  <Accordion title="Can I test without affecting production users?">
    Yes! We recommend:

    1. Create a test provider with a subdomain
    2. Test with a small group first
    3. Roll out to entire organization
  </Accordion>

  <Accordion title="How do I migrate from OIDC to SAML or vice versa?">
    1. Create new provider with same domain
    2. Test with select users
    3. Delete old provider
    4. Users will seamlessly use new protocol
  </Accordion>

  <Accordion title="What if my domain is already registered?">
    Contact [hello@bland.ai](mailto:hello@bland.ai) to transfer or reset domain ownership.
  </Accordion>

  <Accordion title="Do you support SCIM for user provisioning?">
    SCIM support is on our roadmap. Currently, users are provisioned on first login (Just-in-Time provisioning).
  </Accordion>

  <Accordion title="Can I skip phone verification for SSO users?">
    Yes, toggle "Skip phone verification" when creating the provider. This is useful for organizations with strong IdP authentication.
  </Accordion>

  <Accordion title="How do I handle certificate expiration?">
    For SAML:

    1. Get new certificate from IdP
    2. Update in Bland before old expires
    3. Test with Test button
    4. No downtime if done before expiration
  </Accordion>

  <Accordion title="What data is shared between IdP and Bland?">
    Minimal data is shared:

    * Email address (required)
    * Name (optional but recommended)
    * Groups/roles (optional, for role mapping)

    No passwords are ever shared or stored.
  </Accordion>
</AccordionGroup>

***

## Getting Support

When contacting support, provide:

1. **Organization ID** and **Provider ID**
2. **Error message** and screenshots
3. **Time of error** (with timezone)
4. **IdP type** (OIDC/SAML) and vendor
5. **Browser console errors** (F12 → Console)
6. For SAML: **Sanitized SAML response** (remove sensitive data)

### Contact Information

* **Email**: [hello@bland.ai](mailto:hello@bland.ai)
* **Documentation**: This guide
* **Status Page**: status.bland.ai

### IdP Vendor Support

* **Okta**: [support.okta.com](https://support.okta.com)
* **Microsoft**: [support.microsoft.com](https://support.microsoft.com)
* **Google**: [support.google.com/a](https://support.google.com/a)
* **Auth0**: [support.auth0.com](https://support.auth0.com)

***

## Appendix: Error Code Reference

| Error Code                    | Meaning                   | Solution                                |
| ----------------------------- | ------------------------- | --------------------------------------- |
| `INVALID_ISSUER`              | Issuer URL format invalid | Check URL format, remove trailing slash |
| `DOMAIN_CONFLICT`             | Domain already used       | Contact support to transfer domain      |
| `SSO_PROVIDER_NOT_FOUND`      | Provider doesn't exist    | Verify provider ID is correct           |
| `SIGNATURE_VALIDATION_FAILED` | SAML signature invalid    | Update certificate from IdP             |
| `INVALID_CLIENT_CREDENTIALS`  | OIDC auth failed          | Check client ID/secret                  |
| `ACCOUNT_LINKING_FAILED`      | Cannot link SSO account   | Contact support with details            |
| `METADATA_FETCH_FAILED`       | Cannot retrieve metadata  | Check metadata URL accessibility        |
| `USER_NOT_AUTHORIZED`         | User not assigned in IdP  | Add user to application in IdP          |

***

Docs for agents: [llms.txt](/llms.txt)