Multi-IDP Support

Master this essential documentation concept

Quick Definition

The ability of a platform to integrate with multiple identity providers, allowing users to authenticate through different directory services or authentication systems

How Multi-IDP Support Works

flowchart TD A[Documentation User] --> B{Which Identity Provider?} B --> C[Azure Active Directory] B --> D[Okta] B --> E[Google Workspace] B --> F[SAML Enterprise IDP] C --> G[Multi-IDP Authentication Layer] D --> G E --> G F --> G G --> H{Role & Permission Mapping} H --> I[Internal Employees] H --> J[External Partners] H --> K[Contractors] H --> L[Read-Only Clients] I --> M[Full Documentation Access] J --> N[Partner Portal Docs] K --> L2[Project-Specific Docs] L --> O[Public Knowledge Base] M --> P[Documentation Platform] N --> P L2 --> P O --> P P --> Q[Audit Log: IDP Source Tracked] style G fill:#4A90D9,color:#fff style P fill:#27AE60,color:#fff style Q fill:#F39C12,color:#fff

Understanding Multi-IDP Support

Multi-IDP (Multi-Identity Provider) Support enables documentation platforms to authenticate users through several different identity systems at once, such as Okta, Azure Active Directory, Google Workspace, or SAML-based enterprise systems. For documentation teams managing content across large organizations or serving multiple client groups, this capability removes the friction of forcing all users into a single authentication pathway while maintaining centralized access control.

Key Features

  • Simultaneous integration with multiple SAML, OAuth, or OIDC-based identity providers
  • Automatic user provisioning and deprovisioning based on IDP group memberships
  • Role mapping from different IDPs to unified documentation permission levels
  • Single Sign-On (SSO) support across all connected identity providers
  • Conditional access rules that apply different policies based on the authenticating IDP
  • Audit logging that tracks which IDP was used for each authentication event

Benefits for Documentation Teams

  • Serve contractors, partners, and employees through their respective authentication systems without creating separate documentation portals
  • Reduce IT support tickets related to password resets or access issues by leveraging existing corporate credentials
  • Onboard acquired companies or new departments quickly without migrating their identity infrastructure
  • Maintain compliance requirements by enforcing different security policies for different user groups
  • Scale documentation access globally without rebuilding authentication architecture for each region or entity
  • Simplify offboarding by automatically revoking documentation access when users are removed from their IDP

Common Misconceptions

  • Multi-IDP does not mean users can choose any login method arbitrarily — administrators still control which IDPs are available to which user segments
  • Having multiple IDPs does not inherently weaken security; properly configured Multi-IDP environments can enforce stricter policies than single-IDP setups
  • Multi-IDP support is not only for large enterprises — mid-sized documentation teams serving external clients or partners benefit equally
  • It does not require users to have multiple accounts; each user authenticates through their single designated IDP

Real-World Documentation Use Cases

Merging Documentation Portals After Corporate Acquisition

Problem

A software company acquires a smaller firm and needs to give the acquired company's 200 employees immediate access to the parent company's documentation platform. The acquired team uses Okta while the parent company uses Azure Active Directory, and creating 200 new accounts manually would take weeks and create ongoing maintenance burdens.

Solution

Configure Multi-IDP Support to accept both Azure AD and Okta as valid identity providers on the same documentation platform, allowing both employee groups to authenticate through their existing credentials simultaneously.

Implementation

1. Register the acquired company's Okta tenant as a secondary IDP in the documentation platform's authentication settings. 2. Map Okta user groups (e.g., 'Engineering', 'Support') to equivalent permission roles in the documentation platform. 3. Configure which documentation spaces are accessible to Okta-authenticated users. 4. Test authentication flow with a pilot group of 10 users from the acquired company. 5. Communicate the login process to all acquired employees with a one-page guide. 6. Monitor the audit logs for the first two weeks to catch any access issues.

Expected Outcome

Both employee groups access the unified documentation platform using their existing credentials within days of the acquisition announcement, with zero new accounts created and automatic access revocation when either IDP removes a user.

Serving External Partners Alongside Internal Teams

Problem

A documentation team at a manufacturing company maintains technical manuals for both internal engineers (using corporate Azure AD) and external reseller partners (who have their own Google Workspace accounts). Currently, partners receive PDF exports via email because they cannot access the internal documentation portal, resulting in outdated content reaching the field.

Solution

Enable Multi-IDP Support to allow Google Workspace authentication alongside Azure AD, then create a dedicated partner documentation space that Google-authenticated users can access with read-only permissions.

Implementation

1. Add Google Workspace as a secondary IDP using OAuth 2.0 configuration. 2. Create a partner-specific documentation space containing only reseller-approved content. 3. Set Google-authenticated users to automatically receive 'Partner Viewer' role with read-only access. 4. Restrict Azure AD users from seeing the partner space to prevent internal content leakage. 5. Notify reseller partners with login instructions directing them to use their Google credentials. 6. Schedule quarterly reviews of partner access lists against the Google Workspace directory.

Expected Outcome

Partners always access the latest documentation versions directly in the platform, eliminating PDF distribution workflows and reducing documentation-related support calls by an estimated 40%.

Managing Contractor Access Without Provisioning Corporate Accounts

Problem

A documentation team regularly works with 50+ freelance technical writers and UX contractors who need temporary access to the documentation platform. Creating and managing corporate identity accounts for each contractor overwhelms the IT department and creates security risks when contracts end.

Solution

Configure a third-party contractor IDP (such as a dedicated Okta org or Auth0 tenant managed by the documentation team) as an additional identity provider, separate from the corporate IDP, giving documentation managers direct control over contractor authentication.

Implementation

1. Set up a lightweight identity provider (Auth0 or Okta developer account) specifically for contractors. 2. Register this contractor IDP alongside the corporate IDP in the documentation platform. 3. Create a contractor onboarding workflow: add user to contractor IDP, assign to relevant documentation project group, set account expiration date. 4. Map contractor IDP groups to 'Contributor' roles with access limited to assigned projects. 5. Configure automatic deactivation in the contractor IDP when project end dates pass. 6. Train documentation managers to add/remove contractors directly without IT involvement.

Expected Outcome

Documentation managers onboard contractors in under 10 minutes, IT ticket volume for contractor access drops to near zero, and security audits confirm no orphaned contractor accounts exist after project completion.

Supporting Multi-Region Documentation with Local Identity Systems

Problem

A global enterprise's documentation team maintains regulatory compliance documentation for operations in the EU, US, and Asia-Pacific regions. Each region has its own identity infrastructure due to data residency requirements, making it impossible to use a single IDP without violating local data governance policies.

Solution

Implement region-specific IDPs for each geographic entity, connecting all three to the documentation platform while configuring data residency rules that ensure each IDP's user data stays within its required jurisdiction.

Implementation

1. Identify the IDP used in each region (e.g., Azure AD EU tenant, Okta US org, Google Workspace APAC). 2. Configure each as a separate IDP connection in the documentation platform with distinct identifiers. 3. Create region-specific documentation spaces with content relevant to local regulatory requirements. 4. Map each regional IDP to its corresponding documentation space as the default view. 5. Define cross-regional access policies for global documentation managers who need visibility across all regions. 6. Document the IDP configuration in a runbook for IT and documentation team reference. 7. Conduct annual access reviews aligned with each region's compliance calendar.

Expected Outcome

All regional teams access documentation through locally compliant authentication systems, global documentation managers maintain oversight across all regions, and the organization passes data residency audits without documentation platform exceptions.

Best Practices

✓ Map IDP Groups to Documentation Roles Before Go-Live

Before activating a new identity provider, thoroughly document how that IDP's user groups and attributes will translate into documentation platform roles and permissions. Inconsistent role mapping is the leading cause of either over-permissioned access (security risk) or under-permissioned access (user frustration) in Multi-IDP environments.

✓ Do: Create a role mapping matrix spreadsheet that lists every IDP group from each connected provider alongside its corresponding documentation platform role, review it with both IT and documentation team leads, and test it with real user accounts in a staging environment before production deployment.
✗ Don't: Do not assume that similarly named groups across different IDPs have equivalent permissions, and avoid using default or catch-all role assignments that grant broader access than necessary just to avoid mapping complexity.

✓ Establish a Consistent IDP Offboarding Process

One of the greatest security benefits of Multi-IDP Support is automatic access revocation when users are removed from their identity provider. However, this only works reliably if your documentation platform is configured to sync with each IDP's deprovisioning events and if your organization has clear processes for removing users from the correct IDP when they leave.

✓ Do: Configure SCIM provisioning for each IDP where available to enable real-time user deprovisioning, document which team owns each IDP connection and is responsible for removing departed users, and run monthly reconciliation reports comparing active IDP users against active documentation platform users.
✗ Don't: Do not rely solely on manual deactivation within the documentation platform, and avoid situations where multiple teams share responsibility for a single IDP connection without clear ownership, as this creates accountability gaps during offboarding.

✓ Label and Document Each IDP Connection Clearly

In platforms managing three or more identity providers, configuration drift and institutional knowledge loss become serious risks. Administrators who set up IDP connections often move to other roles, leaving undocumented configurations that future team members are afraid to modify. Clear labeling and documentation prevent this technical debt from accumulating.

✓ Do: Name each IDP connection with a descriptive label that includes the organization name, IDP type, and purpose (e.g., 'Acme-Corp-AzureAD-Employees' or 'Partner-Network-Google-ReadOnly'), maintain a living runbook in your internal documentation that describes each connection's purpose, user population, and configuration details, and review this runbook quarterly.
✗ Don't: Do not use generic names like 'IDP1' or 'Secondary Provider' for connections, and avoid storing IDP configuration details only in the memory of individual team members or in undocumented settings within the platform's admin console.

✓ Test Authentication Flows from Each IDP Regularly

IDP configurations can break silently due to certificate expirations, API changes, or administrative changes on the IDP side. Users authenticating through a broken IDP connection often receive cryptic error messages and contact support rather than reporting a configuration issue, making problems hard to detect quickly. Proactive testing prevents extended outages.

✓ Do: Create a dedicated test account in each connected IDP and include authentication testing through every IDP in your monthly platform health checks, set up monitoring alerts for authentication failure rate spikes segmented by IDP, and subscribe to change notifications or changelogs from each IDP vendor to anticipate breaking changes.
✗ Don't: Do not wait for user-reported login failures to discover IDP connection issues, and avoid letting SAML certificates or OAuth client secrets expire by failing to track their renewal dates in a shared calendar or secrets management system.

✓ Apply the Principle of Least Privilege Per IDP

Each identity provider represents a distinct user population with different trust levels and documentation needs. External partner IDPs should not grant the same default permissions as internal employee IDPs, even if both are technically configured and functional. Treating all IDPs as equally trusted by default creates unnecessary risk and complicates compliance audits.

✓ Do: Define a default permission level for each IDP that reflects the minimum access appropriate for that user population (e.g., external IDPs default to read-only, internal IDPs default to contributor), require explicit elevation for any IDP user who needs broader access, and document the business justification for any exceptions in your access review records.
✗ Don't: Do not configure all IDPs with identical default roles for the sake of simplicity, and avoid granting administrative documentation permissions to users authenticated through external or partner IDPs unless there is a specific, documented, and reviewed business requirement.

How Docsie Helps with Multi-IDP Support

Book a Demo

Build Better Documentation with Docsie

Join thousands of teams creating outstanding documentation

Book a Demo