What is SAML? The Core Concept

If you've navigated the world of enterprise APIs, you've likely encountered phrases like "Our application uses SAML SSO," "The Identity Provider will send a SAML Assertion," or "Configure SAML between Okta and the application." For many API developers, SAML can appear as a complex, XML-based protocol, shrouded in mystery. However, its fundamental purpose is straightforward: SAML is simply a secure mechanism for one system to inform another that a user has already been authenticated.

Despite the widespread adoption of OAuth 2.0 and OpenID Connect in modern cloud-native applications, a significant number of enterprise systems continue to rely heavily on SAML. This includes established platforms like SAP, Salesforce, Workday, Oracle, ServiceNow, and numerous internal corporate portals. Understanding SAML is crucial for anyone working with these systems or integrating with them via APIs.

At its heart, SAML (Security Assertion Markup Language) is an open standard that allows identity providers (IdPs) to pass authorization credentials to service providers (SPs). Think of it like a trusted messenger service. When you log into a company portal (the SP), it doesn't necessarily store your password. Instead, it trusts an external Identity Provider (like Okta, Azure AD, or PingFederate) to verify your identity and send a secure, signed message – a SAML Assertion – back to the SP. This assertion essentially says, "Yes, this user is who they claim to be, and here's some basic information about them." This process enables Single Sign-On (SSO), allowing users to access multiple applications with a single set of credentials.

Diagram illustrating the SAML SSO flow between an Identity Provider and a Service Provider.

Key Components of SAML

To grasp how SAML operates, it's essential to understand its core components:

  • Principal: This is the user or entity attempting to access a service. In most enterprise contexts, this is an end-user.
  • Identity Provider (IdP): The system responsible for authenticating the principal. It verifies the user's identity (e.g., via username/password, multi-factor authentication) and issues SAML Assertions. Examples include Okta, Azure Active Directory, Google Workspace, and Ping Identity.
  • Service Provider (SP): The application or system that the principal is trying to access. The SP relies on the IdP to authenticate the user and trusts the SAML Assertion it receives. This could be a SaaS application like Salesforce or an internal company portal.
  • SAML Assertion: This is the critical piece of information. It's an XML document containing statements about the authenticated principal, such as their identity, attributes (like email address, role, department), and authorization decisions. The IdP digitally signs the assertion to ensure its integrity and authenticity.
  • XML: SAML messages are formatted in XML, which is a widely adopted markup language for structuring data. While this can make SAML appear verbose, it ensures broad compatibility.

The SAML SSO Flow: Step-by-Step

Let's walk through a typical SAML SSO flow. Imagine a user wanting to access a CRM application (the SP) after already logging into their company's central authentication system (the IdP).

  1. User Initiates Access: The user navigates to the CRM's login page or clicks a link to access it.
  2. SP Redirects to IdP: The CRM (SP) recognizes that the user isn't authenticated. It generates a SAML Authentication Request (also an XML document) and redirects the user's browser to the Identity Provider (IdP).
  3. IdP Authenticates User: The IdP receives the request. If the user is not already logged into the IdP's session, it prompts them for credentials (username, password, MFA, etc.).
  4. IdP Generates Assertion: Once authenticated, the IdP creates a SAML Assertion. This assertion contains information about the user (e.g., their unique ID, email address, group memberships) and is digitally signed by the IdP using its private key.
  5. IdP Responds to SP: The IdP sends the SAML Assertion back to the user's browser, typically via an HTTP POST request, which then automatically forwards it to the CRM's Assertion Consumer Service (ACS) endpoint.
  6. SP Verifies Assertion: The CRM (SP) receives the assertion. It uses the IdP's public key (which it has pre-configured) to verify the digital signature. This confirms the assertion came from the trusted IdP and hasn't been tampered with.
  7. SP Grants Access: If the signature is valid and the assertion contains the necessary information, the SP establishes a session for the user and grants them access to the application. The user is now logged in without needing to enter credentials directly into the CRM.

This flow can be initiated by either the SP (as described above, called SP-initiated SSO) or the IdP (called IdP-initiated SSO, where the user clicks an icon in an IdP dashboard to access the SP).

SAML vs. OAuth 2.0 / OpenID Connect

While SAML excels in enterprise SSO scenarios, modern API development often favors OAuth 2.0 and OpenID Connect (OIDC). It's crucial to understand their differences and use cases:

  • SAML: Primarily designed for authentication and authorization in enterprise SSO. It's assertion-based, uses XML, and is often seen as more complex for simple API access but robust for federated identity across organizations. Its strength lies in delegating authentication to a trusted IdP for accessing multiple SPs.
  • OAuth 2.0: Primarily an authorization framework. It allows a user to grant a third-party application limited access to their resources on another service without sharing their credentials. It uses tokens (like JWTs) and is typically JSON-based, making it more lightweight for API-to-API communication and modern web/mobile apps.
  • OpenID Connect (OIDC): Built on top of OAuth 2.0, OIDC adds an identity layer. It provides standard ways to get identity information (like user profile data) in the form of ID Tokens (JWTs). OIDC is excellent for user authentication and profile retrieval in modern applications.

Think of SAML as a formal, signed letter of introduction between established businesses (IdP and SP) for a specific client (the user). OAuth 2.0 is more like a set of temporary, revocable access badges issued by a security desk (the authorization server) allowing specific people (clients) to enter certain areas (resources) of a building (the service provider) without revealing their full identity. OIDC adds a verifiable ID card to that badge.

For API developers, OAuth 2.0 and OIDC are generally preferred for new integrations due to their flexibility, token-based nature, and better fit for distributed systems and mobile clients. However, SAML remains indispensable for integrating with legacy enterprise systems and achieving SSO across established corporate ecosystems.

Why SAML Still Matters for API Engineers

Even with the rise of OAuth and OIDC, API and identity engineers cannot ignore SAML. Its continued prevalence in the enterprise landscape means:

  • Integration with Enterprise Systems: If your application needs to integrate with or be accessed by users from large enterprises (e.g., Fortune 500 companies), SAML support is often a non-negotiable requirement for your API or service.
  • Federated Identity: SAML is the backbone of many Business-to-Business (B2B) identity federation scenarios, enabling seamless SSO for partners and customers across different organizational boundaries.
  • Compliance and Security: For many regulated industries, SAML-based SSO solutions are well-established and meet stringent security and compliance requirements.
  • Legacy Systems: A vast number of critical business applications still operate on SAML. Understanding it is key to maintaining and extending these systems.

As an API engineer, you might be tasked with developing an API that consumes SAML assertions, or perhaps building a Service Provider that needs to accept SAML assertions from various Identity Providers. This requires understanding XML parsing, digital signature verification, and the specific SAML profiles (like the Web Browser SSO profile) that govern how assertions are exchanged.

While the XML format might seem dated, the security principles behind SAML—trust, digital signatures, and assertion validation—are timeless. Mastering SAML ensures you can effectively bridge modern application architectures with the established identity management practices of the enterprise world.