> ## 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.

> [!NOTE]
>
> **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.

***

## 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

**1. Open SSO Setup Wizard**

Navigate to **Settings → SSO** in Bland and click **Add Provider**. The setup wizard will guide you through the process.

**2. 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

**3. 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.

**4. Enter Credentials**

Paste the Client ID, Client Secret (OIDC) or certificate/metadata (SAML) from your IdP into the wizard.

**5. Test Connection**

Use the **Test** button in Bland to verify the configuration works.

***

## Okta Configuration

### Okta OIDC Setup

> [accordion] 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] 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]
> ```
>
> > [!NOTE]
> >
> > Replace `[provider-id]` with your chosen Provider ID (e.g., `company-okta`)
>
> **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] 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] 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] 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.

### Okta SAML Setup

> [accordion] 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] Step 2: Configure SAML
>
> **General:**
>
> * **Single sign-on URL**:
>   ```
>   https://api.bland.ai/authorization/sso/saml2/sp/acs/[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] 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] 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] 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

***

## Azure AD (Microsoft Entra ID)

### Azure AD OIDC Setup

> [accordion] 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] 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] 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] 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] 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.

### Azure AD SAML Setup

> [accordion] 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] 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/sp/acs/[provider-id]`
>    * **Sign on URL**: `https://app.bland.ai/login`

> [accordion] 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] Step 4: Download Certificate
>
> 1. In **SAML Certificates**, download **Certificate (Base64)**
> 2. Copy **Login URL** and **Azure AD Identifier**

> [accordion] 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

### 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)

> [!NOTE]
>
> OIDC is the recommended approach for Google Workspace. It's simpler to configure and uses standard OAuth 2.0.

> [accordion] 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]
>    ```
>    > [!NOTE]
>    >
>    > 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.
> 9. Click **Create**
> 10. Copy the **Client ID** and **Client Secret**

> [accordion] 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.

> [accordion] 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

### Google Workspace SAML Setup

> [!NOTE]
>
> Google Workspace also supports SAML 2.0 via the Admin Console. Use this if your organization requires SAML for compliance reasons.

**1. Access Admin Console**

Sign in to [Google Admin Console](https://admin.google.com) with Super Admin account

**2. 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**

**3. Download IdP Metadata**

Download or copy:

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

Click **Continue**

**4. Configure Service Provider**

Enter:

* **ACS URL**: `https://api.bland.ai/authorization/sso/saml2/sp/acs/[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`

**5. Configure Attributes**

Map these attributes:

| Google Directory | App Attribute |
| - | - |
| Primary email | email |
| First name | firstName |
| Last name | lastName |
| Full name | name |

**6. 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

> [!WARNING]
>
> Google Workspace SAML changes can take up to 24 hours to propagate, though typically activate within 15 minutes.

### 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

> [accordion] 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] 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/sp/acs/[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

### 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/sp/acs/[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]
>
> **Existing connections**: SAML connections you set up earlier use the `/sso/saml2/callback/` ACS URL and keep working. The SSO settings in the Bland dashboard show the exact ACS URL for each connection. If you add the new `/sso/saml2/sp/acs/` URL to your identity provider, keep the old URL too.

> [!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.

***

## Troubleshooting

### Common Issues

> [accordion] 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 that the ACS URL in your IdP matches the ACS URL shown for your connection in the SSO settings in the Bland dashboard. New connections use `https://api.bland.ai/authorization/sso/saml2/sp/acs/[provider-id]`. Connections you set up earlier keep the ACS URL they already use.
> * Check for trailing slashes, extra spaces, or HTTP vs HTTPS
> * Ensure the provider ID is identical in both Bland and your IdP

> [accordion] 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] 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] 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] 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

### 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!

* **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

> [accordion] 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] 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] 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] 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`

### 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

> [!NOTE]
>
> Contact [support@bland.ai](mailto:support@bland.ai) for custom role mapping configuration.

### 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

> [accordion] 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] 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] 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

***

## 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

***

## Frequently Asked Questions

> [accordion] 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] 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] 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] 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] 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] 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] What if my domain is already registered?
>
> Contact [support@bland.ai](mailto:support@bland.ai) to transfer or reset domain ownership.

> [accordion] 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] 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] 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] 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.

***

## 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**: [support@bland.ai](mailto:support@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](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.