Implementation Standards for OIDC and SAML 2.0
It covers the technical architecture, protocol-specific requirements, and step-by-step integration for major Identity Providers (IdPs) including Microsoft Entra ID and JumpCloud.
1. Architecture Overview
Camb.AI utilizes a Service Provider-Initiated (SP-Initiated) SSO flow. This ensures a secure, centralized authentication experience tailored to your organization's domain.
1.1 The Authentication Workflow
Initiation: A user navigates to the Camb.AI login portal and selects "Login with SSO."
Domain Identification: The user enters their corporate email (e.g., [email protected]).
Redirection: Camb.AI identifies the SSO configuration associated with the @company.com domain and redirects the request to your configured Identity Provider (IdP).
Verification: Upon successful authentication at the IdP, the user is redirected back to Camb.AI with a secure token/assertion.
Provisioning: Camb.AI validates the response and grants access to the platform.
Critical Requirement: SSO is bound to specific email domains. The email address returned by your IdP must match the domain used to initiate the login.
2. Selecting a Protocol
Camb.AI supports two industry-standard protocols. Review the table below to determine the best fit for your infrastructure.
Feature | OpenID Connect (OIDC) | SAML 2.0 |
Recommendation | Preferred (Modern, simpler setup) | Legacy standard for Enterprise |
Data Format | JSON / JWT | XML |
Security | Secret-based or Private Key | Certificate-based (X.509) |
Complexity | Low (Auto-discovery available) | Moderate (Manual metadata exchange) |
3. Pre-Configuration Checklist
Before beginning the integration, ensure you have the following:
Administrative Access: You must have "Global Admin" or "Application Admin" privileges in your IdP (Entra ID, JumpCloud, Okta, etc.).
Camb.AI Enterprise Account: Ensure your subscription plan supports SSO.
Verified Domains: Access to the DNS settings or confirmation of the domains you wish to enable (e.g., camb.ai).
4. Platform Setup (General Steps)
Navigate to the Camb.AI Portal:
Go to Account Settings > Single Sign-On (SSO).
Select your preferred protocol (OIDC or SAML).
Note the Unique URLs: Camb.AI will generate unique endpoints (ACS URL or Callback URL) for your specific environment. Do not use generic URLs; always copy directly from your dashboard.
5. OIDC Configuration Detail
OIDC is the recommended method for its ease of maintenance and robust security.
5.1 Identity Provider Requirements
To complete the setup, you must provide the following to Camb.AI:
Issuer / Discovery URL: The HTTPS endpoint that hosts the IdP’s configuration (ending in .well-known/openid-configuration).
Client ID: The unique identifier generated by your IdP.
Client Secret: The secure string used for the code exchange.
Authorized Redirect URI: Enter the callback URL provided in the Camb.AI dashboard.
5.2 Claims and Scopes
Camb.AI requires the following scopes to be authorized:
openid (Required)
email (Required: must return the user's primary work email)
profile (Optional: used to sync first and last names)
6. SAML 2.0 Configuration Detail
For organizations standardizing on SAML, Camb.AI provides a robust implementation requiring signed assertions.
6.1 Identity Provider Requirements
IdP Entity ID (Issuer): The unique URI identifying your IdP.
SSO Endpoint (HTTP-Redirect): The URL where Camb.AI sends authentication requests.
Public X.509 Certificate: Must be in PEM format. Ensure you include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- tags.
6.2 Service Provider (Camb.AI) Settings
In your IdP setup, configure the following:
ACS (Assertion Consumer Service) URL: Obtained from Camb.AI settings.
Audience / Entity ID: Set this to the same value as the ACS URL provided by Camb.AI.
NameID Format: Must be set to EmailAddress.
7. Platform-Specific Implementation
7.1 Microsoft Entra ID (Formerly Azure AD)
Recommended: OIDC Flow
Register App: In Entra ID, go to App Registrations > New Registration.
Redirect URI: Set platform to "Web" and paste the Camb.AI Callback URL.
Secrets: Create a new Client Secret. Copy the Value (not the ID).
Metadata: Use the "OpenID Connect metadata document" URL found under the "Endpoints" tab.
7.2 JumpCloud
Recommended: SAML Flow
Create App: Select SSO > Add New Application > Custom SAML App.
Configuration:
IdP Entity ID: Define a unique name.
ACS URL: Paste the URL from Camb.AI.
Attributes: Map email to NameID.
Certificate: Download the JumpCloud Metadata or Certificate and upload the PEM version to Camb.AI.
8. Troubleshooting & Validation
Verification Checklist
[ ] Incognito Test: Always test the login in a private/incognito window to avoid cached session interference.
[ ] Certificate Expiry: For SAML, ensure the certificate uploaded to Camb.AI is current.
[ ] Domain Match: Verify the IdP is sending an email address that matches the domain configured in Camb.AI.
Common Error Resolutions
"SSO is not configured for this domain": Check for typos in the user's email or ensure the domain is active in the Camb.AI SSO dashboard.
"Failed to obtain email":
OIDC: Ensure the email scope is granted and the user's profile has a populated email field.
SAML: Ensure the NameID format is specifically set to EmailAddress.
"Invalid State/Correlation": This usually happens with IdP-Initiated logins. Camb.AI requires the login to start from the Camb.AI login page (SP-Initiated).
9. Support and Validation
If you require technical validation of your configuration, please contact Camb.AI Support with the following details:
Organization Name and Email Domain.
Protocol Choice (OIDC or SAML).
Discovery URL (OIDC) or Metadata URL (SAML).
Screenshot of your IdP’s Attribute Mapping/Claims section.