SAML/SCIM

Master this essential documentation concept

Quick Definition

Security protocols used for identity management - SAML handles authentication while SCIM manages user provisioning and access control across systems.

How SAML/SCIM Works

sequenceDiagram participant HR as HR System participant IdP as Identity Provider (Okta/Azure AD) participant SCIM as SCIM Protocol participant DocPlatform as Documentation Platform participant Writer as Technical Writer Note over HR,DocPlatform: User Provisioning Flow (SCIM) HR->>IdP: New writer added to system IdP->>SCIM: Trigger provisioning event SCIM->>DocPlatform: Create user account + assign roles DocPlatform-->>SCIM: Confirm account created SCIM-->>IdP: Provisioning complete Note over Writer,DocPlatform: Authentication Flow (SAML) Writer->>DocPlatform: Attempts to access docs portal DocPlatform->>IdP: Redirect to Identity Provider (SSO) IdP->>Writer: Prompt for credentials Writer->>IdP: Enter corporate credentials IdP->>DocPlatform: Send SAML assertion (authenticated) DocPlatform->>Writer: Grant access with correct permissions Note over HR,DocPlatform: Offboarding Flow (SCIM) HR->>IdP: Employee deactivated IdP->>SCIM: Trigger deprovisioning SCIM->>DocPlatform: Revoke access immediately

Understanding SAML/SCIM

SAML and SCIM are complementary identity and access management standards that work together to streamline how organizations control who can access their documentation platforms and tools. While SAML handles the authentication handshake that lets users log in once and access multiple systems, SCIM automates the behind-the-scenes work of creating, updating, and removing user accounts when employees join, change roles, or leave the organization.

Key Features

  • SAML SSO: Enables users to authenticate once through an Identity Provider (IdP) like Okta, Azure AD, or OneLogin and gain access to all connected documentation tools without re-entering credentials
  • SCIM Provisioning: Automatically creates user accounts in documentation platforms when new employees are onboarded in the HR or IT system
  • Role-Based Access Control: Syncs user roles and groups from a central directory to documentation tools, ensuring contributors, reviewers, and readers have appropriate permissions
  • Real-Time Deprovisioning: Immediately revokes access to sensitive documentation when an employee is offboarded or changes departments
  • Attribute Mapping: Transfers user attributes like department, job title, and team from the identity provider to the documentation platform for granular access rules

Benefits for Documentation Teams

  • Eliminates manual user management, freeing documentation managers from adding or removing individual accounts
  • Reduces security risks by ensuring former employees lose access to proprietary documentation instantly upon offboarding
  • Ensures consistent permissions across all documentation tools when a writer changes teams or projects
  • Simplifies compliance audits by maintaining a centralized record of who has access to which documentation
  • Improves writer onboarding speed by automatically granting access to all required documentation tools on day one

Common Misconceptions

  • SAML and SCIM are the same thing: They are distinct standards — SAML handles authentication (proving identity), while SCIM handles provisioning (managing accounts)
  • SSO means no passwords are needed: SSO reduces the number of logins, but users still authenticate through their central Identity Provider
  • SCIM replaces SAML: They work best together — SCIM provisions the account, and SAML authenticates the user session
  • Only large enterprises need SAML/SCIM: Any documentation team managing multiple contributors across several tools benefits from automated identity management

Real-World Documentation Use Cases

Automating Onboarding for a Growing Documentation Team

Problem

A software company hires five new technical writers each quarter. The documentation manager spends hours manually creating accounts in the docs platform, wiki, and style guide portal, often delaying writers' ability to contribute for several days.

Solution

Implement SCIM provisioning between the company's Identity Provider (e.g., Azure AD) and the documentation platform so that when HR adds a new writer to the 'Technical Writing' group, accounts are automatically created across all connected tools with the correct contributor permissions.

Implementation

1. Connect Azure AD to the documentation platform via SCIM API credentials. 2. Create a 'Technical Writers' group in Azure AD with mapped attributes (role: contributor, workspace: product-docs). 3. Configure SCIM attribute mapping to assign the correct permission tier in the docs platform. 4. Test by adding a test user to the group and verifying automatic account creation. 5. Coordinate with HR to ensure new hires are added to the correct AD group during onboarding.

Expected Outcome

New technical writers have fully provisioned access to all documentation tools within minutes of being added to the HR system, reducing onboarding time from days to hours and eliminating manual setup errors.

Securing Sensitive API Documentation with SSO

Problem

A company's internal API documentation contains proprietary architecture details. Writers and developers access it with individual usernames and passwords, creating security risks when employees leave and accounts are not promptly deactivated.

Solution

Configure SAML SSO so all users must authenticate through the corporate Identity Provider to access the documentation portal, and enable SCIM deprovisioning to automatically revoke access when an employee's corporate account is disabled.

Implementation

1. Enable SAML SSO in the documentation platform settings and download the Service Provider metadata. 2. Upload SP metadata to Okta and configure the SAML application with user attribute mappings. 3. Enforce SSO-only login in the docs platform to prevent password-based access. 4. Enable SCIM integration to sync deprovisioning events from Okta. 5. Test the offboarding flow by disabling a test account and confirming immediate access revocation.

Expected Outcome

All access to sensitive API documentation is tied to active corporate credentials. Former employees lose access within seconds of offboarding, and the security team can audit all documentation access through a single identity system.

Managing Role-Based Access Across Documentation Workspaces

Problem

A documentation team supports multiple product lines, each with separate workspaces for internal drafts, external-facing docs, and legal reviews. Managing individual permissions for 50+ contributors manually leads to errors, with some users having too much or too little access.

Solution

Use SCIM group synchronization to map Identity Provider groups (e.g., 'Product-A-Writers', 'Legal-Reviewers', 'External-Editors') to specific workspace roles in the documentation platform, ensuring permissions are always aligned with a user's current team assignment.

Implementation

1. Define documentation access groups in the Identity Provider that mirror team structures. 2. Map each IdP group to a specific workspace and role in the documentation platform via SCIM. 3. Configure automatic role updates so when a writer moves from Product A to Product B team, their group membership change triggers permission updates. 4. Set up quarterly access reviews using IdP group reports. 5. Document the group-to-role mapping in an internal admin guide.

Expected Outcome

Permissions across all documentation workspaces stay synchronized with actual team assignments, reducing unauthorized access incidents and eliminating the need for manual permission audits.

Enabling Contractor Access with Automatic Expiration

Problem

Documentation teams frequently work with contract writers who need temporary access to specific documentation projects. Managing their access manually often results in contractors retaining access long after their contracts end.

Solution

Provision contractor accounts through SCIM with defined group memberships that have expiration policies, combined with SAML SSO to ensure contractors authenticate through a monitored identity system rather than standalone credentials.

Implementation

1. Create a 'Contractors' group in the Identity Provider with a defined lifecycle policy. 2. Configure SCIM to provision contractor accounts in the documentation platform with limited-scope permissions when added to this group. 3. Set account expiration dates in the IdP aligned with contract end dates. 4. Configure SAML SSO for contractor authentication using the same IdP. 5. Set up automated notifications to documentation managers 30 days before contractor access expires for renewal decisions.

Expected Outcome

Contractor access is automatically provisioned on day one and deprovisioned on the contract end date, eliminating orphaned accounts and ensuring contractors only access documentation relevant to their project scope.

Best Practices

✓ Map User Attributes Before Going Live

Before enabling SAML or SCIM in production, carefully plan and document how user attributes in your Identity Provider (department, role, team) will map to permissions and roles in your documentation platform. Incorrect mappings can result in users having too much or too little access from day one.

✓ Do: Create a detailed attribute mapping spreadsheet that defines which IdP groups correspond to which documentation roles (viewer, contributor, admin), and test all mappings with a pilot group of 5-10 users before full rollout.
✗ Don't: Don't rush the mapping configuration or assume default settings are correct. Avoid giving all users admin access temporarily 'just to get started' — this creates security gaps that are difficult to remediate later.

✓ Test Deprovisioning Before Enabling Provisioning

Many teams focus on getting user provisioning working correctly but neglect to thoroughly test the offboarding flow. Since deprovisioning is critical for security, it should be validated first using test accounts to confirm that access is revoked promptly and completely when a user is removed from the IdP.

✓ Do: Create a dedicated test account in your IdP, provision it to the documentation platform via SCIM, then deactivate it and measure how quickly access is revoked. Document the expected deprovisioning time and include it in your security policies.
✗ Don't: Don't assume deprovisioning works correctly just because provisioning worked. Avoid relying solely on SAML session expiration for access revocation — SCIM deprovisioning should be the primary mechanism for removing access.

✓ Enforce SSO-Only Login for Documentation Platforms

Once SAML SSO is configured, disable all alternative login methods (username/password, social logins) in your documentation platform. Allowing multiple authentication methods undermines the security benefits of SSO and creates unmonitored access paths that bypass your Identity Provider's controls.

✓ Do: Enable the 'Enforce SSO' or 'Disable password login' setting in your documentation platform's security settings after confirming all users can successfully authenticate via SAML. Communicate the change to all users at least two weeks in advance.
✗ Don't: Don't leave password-based login enabled as a 'backup' after SSO is live. Avoid creating shared service accounts that bypass SSO for integrations — use API tokens with scoped permissions instead.

✓ Maintain a Living Documentation of Your IAM Configuration

Your SAML and SCIM configuration represents critical infrastructure for documentation access. Maintain clear internal documentation of your IdP settings, attribute mappings, group structures, and the rationale behind access decisions. This is essential for troubleshooting, audits, and onboarding new IT administrators.

✓ Do: Create and maintain an internal admin runbook that includes SAML metadata URLs, SCIM endpoint details, group-to-role mappings, and step-by-step procedures for common tasks like adding a new workspace or onboarding a contractor. Review it quarterly.
✗ Don't: Don't store SAML certificates or SCIM bearer tokens in shared documents or wikis without proper access controls. Avoid making undocumented configuration changes directly in production — always update your runbook first.

✓ Conduct Regular Access Audits Using IdP Reports

Even with automated provisioning and deprovisioning, access drift can occur over time as organizational structures change. Regularly audit who has access to your documentation platform by comparing active users in the platform against current IdP group memberships to identify and remediate discrepancies.

✓ Do: Schedule quarterly access reviews where the documentation manager cross-references the documentation platform's user list with current IdP group memberships. Use your IdP's built-in access review features (available in Okta, Azure AD, and Google Workspace) to streamline this process.
✗ Don't: Don't assume that because SCIM is configured, all access is always accurate. Avoid skipping audits for contractor or external collaborator accounts — these are the most likely to have stale access that wasn't properly deprovisioned.

How Docsie Helps with SAML/SCIM

Book a Demo

Build Better Documentation with Docsie

Join thousands of teams creating outstanding documentation

Book a Demo