Master this essential documentation concept
Single Sign-On / Security Assertion Markup Language - a system that allows users to log in once and access multiple applications, with SAML being the protocol that securely transfers authentication data between systems.
Single Sign-On / Security Assertion Markup Language - a system that allows users to log in once and access multiple applications, with SAML being the protocol that securely transfers authentication data between systems.
When your team sets up SSO/SAML integration for a new application, the process often involves a screen-share walkthrough — someone from IT or DevOps records themselves configuring the identity provider, mapping attributes, and testing the assertion flow. That recording gets shared in a Slack channel or stored in a drive folder, and everyone assumes the knowledge is captured.
The problem surfaces six months later when a different team needs to connect a new tool to your existing SSO/SAML setup. They know a walkthrough exists somewhere, but scrubbing through a 45-minute recording to find the specific moment where certificate configuration is explained is impractical. Critical details — like how your organization structures NameID formats or which attribute mappings your IdP requires — stay buried in video timestamps nobody remembers.
Converting those SSO/SAML setup recordings into structured documentation changes how your team accesses that institutional knowledge. Instead of rewatching entire sessions, engineers can search directly for "SAML attribute mapping" or "IdP metadata URL" and land on the exact steps they need. A concrete example: onboarding a new SaaS tool that requires SSO/SAML configuration becomes a self-service process when the documentation is searchable, versioned, and linked from your internal wiki.
If your team regularly captures authentication and access management workflows on video, see how converting those recordings into structured documentation can make that knowledge actually usable.
Enterprise customers using Jira, Confluence, and Zendesk separately must maintain three sets of credentials, leading to password fatigue, frequent account lockouts, and IT help desk tickets consuming ~30% of support capacity.
SAML 2.0 SSO federates all three applications to the company's existing Okta Identity Provider, so employees authenticate once via Okta and are silently passed a signed SAML Assertion to each application without re-entering credentials.
['Register each SP (Jira, Confluence, Zendesk) in Okta by configuring the Entity ID and Assertion Consumer Service (ACS) URL for each application.', "Export the IdP metadata XML from Okta and import it into each SP's SAML configuration panel to establish trust.", 'Map Okta user profile attributes (email, department, role) to SAML Attribute Statements so each SP receives the correct group memberships for authorization.', 'Enable Just-in-Time (JIT) provisioning in each SP so new Okta users are automatically created on first login without manual admin steps.']
Password-related help desk tickets drop by ~70%, onboarding time for new employees accessing all three tools falls from 2 days to under 15 minutes, and offboarding is instant via a single Okta deactivation.
A SaaS company's developer documentation portal (built on Readme.io) is publicly accessible, but API key management pages and internal changelogs must be restricted to paying enterprise customers who already authenticate via their own corporate IdPs (Azure AD, Ping Identity).
Readme.io is configured as a SAML SP supporting multiple IdP connections, allowing each enterprise customer to supply their own IdP metadata. Users from Acme Corp authenticate against Acme's Azure AD and receive a SAML Assertion that grants them access to Acme-specific portal sections.
["Create a separate SAML application entry in each customer's Azure AD tenant, providing them with Readme.io's Entity ID and ACS URL.", "Collect each customer's IdP metadata XML (or individual fields: SSO URL, Entity ID, x.509 certificate) and configure a dedicated IdP connection in Readme.io per customer.", "Use SAML Attribute Statements to pass a 'customer_tier' attribute, which Readme.io maps to visibility groups controlling access to gated content sections.", 'Test the flow end-to-end using SAML-tracer browser extension to inspect the Base64-decoded Assertion and confirm attribute values before go-live.']
Enterprise customers access restricted documentation using their existing corporate credentials with no additional passwords, reducing customer support requests about portal login by 85% and satisfying SOC 2 access control requirements.
A financial services firm uses legacy internal tools (older Jenkins, Grafana, internal wikis) that have no native MFA support. Auditors flagged these as non-compliant with PCI-DSS requirements for multi-factor authentication on systems handling sensitive data.
Each legacy tool is configured as a SAML SP behind the company's Azure AD IdP, which enforces MFA (Microsoft Authenticator) as a Conditional Access policy before issuing SAML Assertions. The tools themselves never handle credentials—authentication and MFA are fully delegated to Azure AD.
["Install and configure the SAML plugin for Jenkins (SAML Plugin) and Grafana's built-in SAML provider, pointing each to Azure AD as the IdP using the federation metadata URL.", 'Create an Azure AD Conditional Access policy requiring MFA for any authentication request originating from these SAML SP applications.', 'Map Azure AD group memberships to SAML Role attributes so Jenkins and Grafana automatically assign the correct permission levels (admin, read-only) from the Assertion.', 'Run a pilot with the DevOps team for one week, reviewing Azure AD sign-in logs to confirm MFA challenges are being triggered and Assertions are being accepted.']
All flagged legacy tools now require MFA without code changes to the tools themselves. The firm passes the subsequent PCI-DSS audit checkpoint, and the security team gains centralized visibility into all authentication events through Azure AD logs.
When employees leave a 500-person tech company, IT must manually revoke access in 40+ SaaS tools. This process takes an average of 3 days, leaving a window where former employees retain active sessions and access tokens in tools like GitHub, Figma, Notion, and Datadog.
All 40+ tools are federated to Okta via SAML. Disabling a user in Okta immediately prevents new SAML Assertions from being issued for that user. Combined with Okta's session revocation and SCIM deprovisioning, access is cut off within minutes of the offboarding trigger.
['Audit all 40 SaaS tools and confirm each supports SAML 2.0; migrate any tool still using local passwords to SAML-based login with Okta as the IdP.', 'Enable SCIM provisioning alongside SAML for tools that support it (GitHub Enterprise, Slack, Datadog) so user accounts are actively deactivated, not just blocked from new logins.', 'Create an Okta Workflow that triggers automatically when an HR system (Workday) marks an employee as terminated, deactivating the Okta account and initiating SCIM deprovisioning.', 'Configure session lifetime policies in each SP to a maximum of 8 hours so any active sessions expire quickly after the Okta account is disabled.']
Offboarding time drops from 3 days to under 30 minutes. A quarterly access review confirms zero instances of former employees retaining active access beyond the session expiry window, satisfying SOC 2 Type II access termination controls.
A SAML Assertion is only trustworthy if the SP cryptographically verifies the IdP's digital signature using the IdP's public x.509 certificate. Skipping or weakening this check opens the door to Assertion forgery attacks where a malicious actor crafts a fake Assertion granting admin privileges. Ensure your SP is configured to reject unsigned or invalidly signed Assertions outright.
SAML Assertions contain a validity window defined by the NotBefore and NotOnOrAfter conditions. Overly long assertion lifetimes (e.g., 24 hours) increase the risk window if an Assertion is intercepted or replayed. Similarly, SP-side session cookies should expire independently and not simply inherit the Assertion's validity period.
SAML is often implemented only to confirm who a user is, but Attribute Statements in the Assertion can carry rich authorization data—group memberships, roles, cost centers, or subscription tiers—eliminating the need for the SP to maintain its own user directory. This keeps access control synchronized with the IdP's source of truth in real time.
SAML supports two login flows: SP-initiated (user starts at the SP, gets redirected to IdP) and IdP-initiated (user clicks an app tile in the IdP dashboard). IdP-initiated flows lack an AuthnRequest, making them more susceptible to open redirect and CSRF attacks if the SP doesn't validate the RelayState and enforce anti-CSRF measures.
The IdP's x.509 signing certificate has an expiration date, and when it expires or is rotated without coordination, every SP that has the old certificate pinned will reject all SAML Assertions, causing a complete authentication outage across all federated applications. Most organizations discover this only when users suddenly cannot log in.
Join thousands of teams creating outstanding documentation
Start Free Trial