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.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
Choose Your Protocol
OIDC - Recommended for: Okta, Azure AD, Auth0, modern IdPsSAML - Required for: Google Workspace, legacy systems, or when mandated by security policy
2
Configure Your IdP
Create an application in your identity provider with placeholder URLs (you’ll update these after creating the provider in Bland)
3
Create Provider in Bland
Navigate to Settings → SSO in Bland and add your provider configuration
4
Update URLs
Copy the generated Provider ID and update the redirect/callback URLs in your IdP
5
Test Connection
Use the Test button in Bland to verify the configuration works
Okta Configuration
Okta OIDC Setup
Step 1: Create OIDC Application
Step 1: Create OIDC Application
- Sign in to Okta Admin Console
- Go to Applications → Applications
- Click Create App Integration
- Select OIDC - OpenID Connect as the Sign-in method
- Select Web Application as the Application type
- Click Next
Step 2: Configure Application
Step 2: Configure Application
General Settings:Sign-out redirect URIs: (Optional)Controlled access:
- App integration name:
Bland SSO - Logo: (Optional) Upload your company logo
- ✅ Authorization Code
- ✅ Refresh Token (recommended)
- ❌ Implicit (not recommended)
You’ll get the exact provider-id after creating the provider in Bland
- Allow everyone in your organization to access (recommended for company-wide SSO)
- Limit access to selected groups (if you want to control access)
Step 3: Configure Claims (Optional)
Step 3: Configure Claims (Optional)
For role mapping:
- Go to Sign On tab → OpenID Connect ID Token → Edit
- Click Add Claim
- Configure:
- Name:
groups - Include in: ID Token, Access Token
- Value type: Groups
- Filter:
.*(for all groups) - Include in: Any scope
- Name:
- Click Create
Step 4: Get Configuration Details
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
Step 5: Configure in Bland
Step 5: Configure in Bland
- Go to Settings → SSO → Add Provider
- Select OIDC as Provider Type
- Enter:
- Email Domain:
company.com - Issuer URL: From Okta
- Client ID: From Okta
- Client Secret: From Okta
- Email Domain:
- Click Add Provider
- Copy the generated Provider ID
- Return to Okta and update the redirect URI with the actual ID
Okta SAML Setup
Step 1: Create SAML Application
Step 1: Create SAML Application
- In Okta Admin, go to Applications → Applications
- Click Create App Integration
- Select SAML 2.0 as the Sign-in method
- Click Next
- Enter App name:
Bland SSO - Click Next
Step 2: Configure SAML
Step 2: Configure SAML
General:
- Single sign-on URL:
- ✅ Use this for Recipient URL and Destination URL
- Audience URI (SP Entity ID):
- Name ID format:
EmailAddress - Application username:
Email
Step 3: Configure Attributes
Step 3: Configure Attributes
Add these attribute statements:
For role mapping, add Group Attribute:
| Name | Name Format | Value |
|---|---|---|
| Unspecified | user.email | |
| firstName | Unspecified | user.firstName |
| lastName | Unspecified | user.lastName |
| name | Unspecified | user.displayName |
| Name | Name Format | Filter |
|---|---|---|
| roles | Unspecified | .* |
Step 4: Get SAML Configuration
Step 4: Get SAML Configuration
- Go to Sign On tab → View SAML setup instructions
- Copy:
- Identity Provider Issuer
- Identity Provider Single Sign-On URL
- X.509 Certificate (entire content)
- Or download the metadata XML
Step 5: Configure in Bland
Step 5: Configure in Bland
- Go to Settings → SSO → Add Provider
- Select SAML as Provider Type
- Enter domain and issuer
- Either:
- Paste the X.509 Certificate and Entry Point URL, or
- Provide the Metadata URL or Metadata XML
- Save and update Okta with the generated Provider ID
Azure AD (Microsoft Entra ID)
Azure AD OIDC Setup
Step 1: Register Application
Step 1: Register Application
- Sign in to Azure Portal
- Go to Azure Active Directory → App registrations
- Click New registration
- 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]
- Name:
- Click Register
- Copy the Application (client) ID and Directory (tenant) ID
Step 2: Create Client Secret
Step 2: Create Client Secret
- Go to Certificates & secrets → Client secrets
- Click New client secret
- Description:
Bland SSO Secret - Choose expiration (12-24 months recommended)
- Click Add
- IMMEDIATELY copy the secret value (won’t be shown again)
Step 3: Configure Permissions
Step 3: Configure Permissions
- Go to API permissions
- Click Add a permission → Microsoft Graph → Delegated permissions
- Add:
openidprofileemailUser.Read
- Click Grant admin consent for [Organization]
Step 4: Configure Token Claims
Step 4: Configure Token Claims
- Go to Token configuration
- Click Add optional claim → ID
- Select:
email,family_name,given_name,preferred_username - For role mapping, click Add groups claim:
- Select Security groups
- Under ID, select Group ID
Step 5: Configure in Bland
Step 5: Configure in Bland
- In Bland, go to Settings → SSO → Add Provider
- Select OIDC
- Enter:
- Issuer URL:
https://login.microsoftonline.com/[tenant-id]/v2.0 - Client ID: Application (client) ID from Azure
- Client Secret: Secret value from Azure
- Issuer URL:
- Save and update Azure with the generated Provider ID
Azure AD SAML Setup
Step 1: Create Enterprise Application
Step 1: Create Enterprise Application
- In Azure AD, go to Enterprise applications
- Click New application → Create your own application
- Name:
Bland SSO SAML - Select: Integrate any other application you don’t find in the gallery
- Click Create
Step 2: Configure SAML
Step 2: Configure SAML
- Go to Single sign-on → Select SAML
- Edit Basic SAML Configuration:
- Identifier (Entity ID):
https://api.bland.ai/sp/[provider-id] - Reply URL:
https://api.bland.ai/authorization/sso/saml2/callback/[provider-id] - Sign on URL:
https://app.bland.ai/login
- Identifier (Entity ID):
Step 3: Configure Attributes
Step 3: Configure Attributes
Edit User Attributes & Claims:
Simplify by editing each claim name to:
| Claim Name | Source Attribute |
|---|---|
| emailaddress | user.mail |
| givenname | user.givenname |
| surname | user.surname |
| name | user.displayname |
email, firstName, lastName, nameStep 4: Download Certificate
Step 4: Download Certificate
- In SAML Certificates, download Certificate (Base64)
- Copy Login URL and Azure AD Identifier
Step 5: Configure in Bland
Step 5: Configure in Bland
- Add SAML provider with Azure configuration
- Update Azure URLs with generated Provider ID
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.)
- 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 only supports SAML for third-party applications. OIDC is reserved for Google’s own services.
1
Access Admin Console
Sign in to Google Admin Console with Super Admin account
2
Add Custom SAML App
- Go to Apps → Web and mobile apps
- Click Add app → Add custom SAML app
- Enter:
- App name:
Bland SSO - App description:
Single Sign-On for Bland AI
- App name:
- Click Continue
3
Download IdP Metadata
Download or copy:
- SSO URL
- Entity ID
- Certificate
- Or download the full metadata XML
4
Configure Service Provider
Enter:
- ACS URL:
https://api.bland.ai/authorization/sso/saml2/callback/[provider-id] - 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 | |
| First name | firstName |
| Last name | lastName |
| Full name | name |
6
Configure in Bland
- Add SAML provider using Google’s metadata
- Update Google app with generated Provider ID
- Enable app for organizational units
7
Test Configuration
From Google Admin Console:
- In the Bland SSO app, click Test SAML login
- This opens the SSO flow in a new tab
- Use the Test button in SSO settings
- Or test with an incognito browser window
Google Workspace 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
- 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
- Enable password alert for compromised passwords
- Configure strong password requirements
- Regular rotation policies
Other Identity Providers
Auth0
OIDC Configuration
OIDC Configuration
- Create new Application → Regular Web Application
- Settings:
- Allowed Callback URLs:
https://api.bland.ai/authorization/sso/callback/[provider-id] - Allowed Web Origins:
https://app.bland.ai
- Allowed Callback URLs:
- Use:
- Issuer:
https://[your-domain].auth0.com/ - Client ID and Client Secret from Auth0
- Issuer:
SAML Configuration
SAML Configuration
- Create new Application → Regular Web Application
- Enable SAML2 Web App addon
- Configure:
- Application Callback URL:
https://api.bland.ai/authorization/sso/saml2/callback/[provider-id] - Settings: Use provided JSON for attribute mapping
- Application Callback URL:
Ping Identity
Both OIDC and SAML supported. Use PingOne or PingFederate admin console to configure with Bland’s endpoints.OneLogin
Supports both protocols. Create app from catalog or custom connector using Bland’s metadata.URL Reference
OIDC Endpoints
| Endpoint | URL Format |
|---|---|
| Redirect URI | https://api.bland.ai/authorization/sso/callback/[provider-id] |
| Discovery | Auto-discovery from issuer URL |
SAML Endpoints
| Endpoint | URL Format |
|---|---|
| ACS URL | https://api.bland.ai/authorization/sso/saml2/callback/[provider-id] |
| SP Entity ID | https://api.bland.ai/sp/[provider-id] |
| SP Metadata | Available after provider creation |
Troubleshooting
Common OIDC Issues
Invalid redirect URI
Invalid redirect URI
Cause: Redirect URI mismatchSolution:
- Copy exact URI from Bland including provider ID
- Check for trailing slashes or spaces
- Ensure HTTPS is used
Invalid client credentials
Invalid client credentials
Cause: Wrong or expired credentialsSolution:
- Regenerate client secret in IdP
- Update immediately in Bland
- Verify no extra spaces when pasting
Invalid issuer
Invalid issuer
Cause: Incorrect issuer URL formatSolution:
- Remove trailing slashes
- For Azure: Use
/v2.0endpoint - For Okta: Use base domain without
/oauth2/default
Common SAML Issues
Invalid SAML Response
Invalid SAML Response
Cause: Incorrect attribute mappingSolution:
- Set NameID format to
emailAddress - Use “Unspecified” for attribute name format
- Ensure email attribute is mapped
Signature validation failed
Signature validation failed
Cause: Certificate mismatchSolution:
- Re-download certificate from IdP
- Include full certificate with BEGIN/END lines
- Check certificate expiration
Audience validation failed
Audience validation failed
Cause: SP Entity ID mismatchSolution:
- Update Entity ID with exact provider ID
- Format:
https://api.bland.ai/sp/[provider-id] - Check for typos or extra spaces
account_not_found
account_not_found
Cause: Missing user attributesSolution:
- Verify attribute mappings in IdP
- Ensure user has email in IdP profile
- Check attributes are being sent in response
Testing Your Configuration
- Use Test Button: In Bland SSO settings, click Test next to your provider
- Check Browser Console: Open Developer Tools (F12) → Network tab for detailed errors
- Verify in IdP: Check IdP audit logs for authentication attempts
- Test with Different User: Try a non-admin account to verify permissions
- Test in Incognito Mode: Always test in incognito/private browsing mode to avoid cached sessions
Advanced Debugging Tools
For SAML:- SAML Chrome Panel - Chrome extension
- SAML-tracer - Firefox addon
- Capture and decode SAML responses to verify attributes
- Use jwt.io to decode ID tokens
- Verify
iss(issuer),aud(audience), and claims
- 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
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
- Use Groups: Manage access via IdP groups rather than individual assignments
- Regular Audits: Review SSO access quarterly
- Immediate Revocation: Remove departing employees promptly
- 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
- Use Conditional Access for location/device restrictions
- Enable risk-based authentication policies
- Implement Privileged Identity Management (PIM)
- Enable Context-Aware Access levels
- Use Security Keys for admin accounts
- Configure data residency requirements
Role Mapping
Users with IdP groups/roles containing these keywords receive admin role in Bland:adminadministratorownermanagersuper
Contact support for custom role mapping requirements.
Important Notes
- Users signing in via SSO still need to verify their phone number during first-time setup
- SSO users are automatically added to your organization
- Each email domain can only be configured for one organization
- Existing users are automatically converted to SSO on first SSO login
Frequently Asked Questions
Which protocol should I choose: OIDC or SAML?
Which protocol should I choose: OIDC or SAML?
Choose OIDC if:
- You’re using modern IdPs (Okta, Auth0, Azure AD)
- You want simpler configuration
- You need refresh tokens
- You’re building mobile apps
- Starting fresh with SSO
- Want better mobile app support
- Required by your IdP (Google Workspace)
- Mandated by security policy
- You need encrypted assertions
- Integrating with legacy systems
- Your organization already uses SAML for other applications
- You require specific SAML features like encrypted assertions
Can I have multiple SSO providers?
Can I have multiple SSO providers?
Yes! You can configure multiple providers for:
- Different domains
- Different protocols (OIDC and SAML)
- Different identity providers
What happens to existing users?
What happens to existing users?
Existing users are automatically linked when they first sign in with SSO. Their data, settings, and permissions remain intact.
Can I test without affecting production users?
Can I test without affecting production users?
Yes! We recommend:
- Create a test provider with a subdomain
- Test with a small group first
- Roll out to entire organization
How do I migrate from OIDC to SAML or vice versa?
How do I migrate from OIDC to SAML or vice versa?
- Create new provider with same domain
- Test with select users
- Delete old provider
- Users will seamlessly use new protocol
What if my domain is already registered?
What if my domain is already registered?
Contact hello@bland.ai to transfer or reset domain ownership.
Do you support SCIM for user provisioning?
Do you support SCIM for user provisioning?
SCIM support is on our roadmap. Currently, users are provisioned on first login (Just-in-Time provisioning).
Can I skip phone verification for SSO users?
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.
How do I handle certificate expiration?
How do I handle certificate expiration?
For SAML:
- Get new certificate from IdP
- Update in Bland before old expires
- Test with Test button
- No downtime if done before expiration
What data is shared between IdP and Bland?
What data is shared between IdP and Bland?
Getting Support
When contacting support, provide:- Organization ID and Provider ID
- Error message and screenshots
- Time of error (with timezone)
- IdP type (OIDC/SAML) and vendor
- Browser console errors (F12 → Console)
- For SAML: Sanitized SAML response (remove sensitive data)
Contact Information
- Email: hello@bland.ai
- Documentation: This guide
- Status Page: status.bland.ai
IdP Vendor Support
- Okta: support.okta.com
- Microsoft: support.microsoft.com
- Google: support.google.com/a
- Auth0: 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 |