DEV Community

Preecha
Preecha

Posted on

What is SAML 2.0? Complete Guide to Secure SSO Explained

In today's digital landscape, SAML 2.0 is still one of the most common ways to implement secure enterprise single sign-on (SSO). If you build SaaS apps, internal portals, or APIs that need to integrate with an enterprise identity provider, understanding the SAML flow helps you design safer authentication boundaries and debug integration issues faster.

Try Apidog today

What Is SAML 2.0?

SAML 2.0 stands for Security Assertion Markup Language 2.0. It is an open standard from OASIS for exchanging authentication and authorization data between two main parties:

  • Identity Provider (IdP): Authenticates the user.
  • Service Provider (SP): The application the user wants to access.

SAML uses XML-based messages called assertions. After the IdP authenticates a user, it sends a signed assertion to the SP. The SP validates the assertion and grants access if it is trusted.

In practice, SAML 2.0 lets users log in once through a trusted IdP and access multiple applications without managing separate credentials for each one.

Why SAML 2.0 Matters

SAML 2.0 is useful when you need enterprise-grade federated identity.

Common reasons teams use it:

  • Centralize authentication through one IdP.
  • Reduce password sprawl across SaaS and internal apps.
  • Improve user experience with SSO.
  • Reduce help desk tickets for password resets.
  • Support auditable authentication flows for compliance.
  • Integrate B2B customers that require enterprise SSO.

If you are building a SaaS platform for enterprise customers, SAML support is often a requirement.

Core SAML 2.0 Components

A typical SAML setup includes the following pieces:

Component Role
User / Principal The person trying to access the application
Service Provider / SP The application being accessed
Identity Provider / IdP The system that authenticates the user
SAML Assertion XML document containing authentication and user attributes
Binding How SAML messages are transported, such as HTTP POST or Redirect
Metadata XML configuration describing endpoints, certificates, and identifiers

How the SAML 2.0 Login Flow Works

A common SP-initiated SAML login flow looks like this:

  1. The user opens your application.
  2. Your application, acting as the SP, detects that the user is not authenticated.
  3. The SP creates a SAML authentication request.
  4. The browser redirects the user to the IdP.
  5. The user authenticates with the IdP.
  6. The IdP generates a SAML assertion.
  7. The browser posts the assertion back to the SP's Assertion Consumer Service endpoint.
  8. The SP validates the assertion.
  9. The SP creates an application session for the user.

Simple flow:

User -> Service Provider -> Identity Provider -> User -> Service Provider
Enter fullscreen mode Exit fullscreen mode

Each step represents a browser redirect or POST carrying SAML protocol messages.

Key Endpoints in a SAML Integration

When implementing SAML, your SP typically needs these endpoints:

Endpoint Purpose
Login URL Starts the SAML login flow
Assertion Consumer Service / ACS URL Receives the SAML response from the IdP
Metadata URL Exposes SP configuration to the IdP
Logout URL Handles SAML single logout when supported

Example SP metadata values you may need to configure:

Entity ID: https://app.example.com/saml/metadata
ACS URL: https://app.example.com/saml/acs
Single Logout URL: https://app.example.com/saml/logout
Certificate: Your SP signing certificate
Enter fullscreen mode Exit fullscreen mode

The IdP will also provide metadata, including:

IdP Entity ID
SSO URL
SLO URL
X.509 signing certificate
Supported bindings
Enter fullscreen mode Exit fullscreen mode

What Is a SAML Assertion?

A SAML assertion is an XML document that communicates identity information from the IdP to the SP.

There are three common assertion types:

  • Authentication assertion: Confirms that the user authenticated.
  • Attribute assertion: Provides user attributes such as email, name, or role.
  • Authorization decision assertion: Indicates whether the user is authorized for a specific action.

A simplified SAML assertion may look like this:

<saml:Assertion
  xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
  ID="_example"
  IssueInstant="2025-01-01T12:00:00Z"
  Version="2.0">

  <saml:Issuer>https://idp.example.com</saml:Issuer>

  <saml:Subject>
    <saml:NameID>john.doe@example.com</saml:NameID>
  </saml:Subject>

  <saml:AttributeStatement>
    <saml:Attribute Name="email">
      <saml:AttributeValue>john.doe@example.com</saml:AttributeValue>
    </saml:Attribute>

    <saml:Attribute Name="role">
      <saml:AttributeValue>admin</saml:AttributeValue>
    </saml:Attribute>
  </saml:AttributeStatement>
</saml:Assertion>
Enter fullscreen mode Exit fullscreen mode

In production, assertions should be signed, validated, and optionally encrypted depending on your security requirements.

SAML Bindings and Protocols

SAML defines how messages are exchanged.

Common bindings include:

  • HTTP Redirect: Often used to send authentication requests to the IdP.
  • HTTP POST: Often used by the IdP to send the SAML response back to the SP.
  • SOAP: Used in some back-channel communication scenarios.

Protocols define message patterns, such as:

  • Authentication request and response.
  • Single logout.
  • Artifact resolution.

For most web SSO implementations, you will primarily work with HTTP Redirect and HTTP POST bindings.

SAML 2.0 vs. SAML 1.1

SAML 2.0 improved on SAML 1.1 in several important ways:

  • Broader interoperability across vendors.
  • Better support for single logout.
  • More flexible attribute exchange.
  • Improved support for signing and encryption.
  • More mature enterprise ecosystem.

For new integrations, SAML 2.0 is the practical standard.

Common Use Cases for SAML 2.0

Enterprise SSO

Large organizations use SAML to let employees access many apps through one corporate identity provider.

For example:

Corporate IdP -> HR portal
Corporate IdP -> CRM
Corporate IdP -> Expense management app
Corporate IdP -> Internal dashboard
Enter fullscreen mode Exit fullscreen mode

The employee signs in through the IdP, and each connected SP trusts the IdP's assertion.

SaaS Customer SSO

SaaS providers often support SAML so enterprise customers can connect their own IdP, such as Okta, Azure AD, Auth0, Google Workspace, or Microsoft 365.

This keeps user identity management under the customer's control.

API and Backend Integrations

SAML is mostly used for browser-based SSO, but API developers still need to understand it when:

  • Building ACS endpoints.
  • Creating login initiation routes.
  • Mapping SAML attributes to application users.
  • Debugging failed SSO attempts.
  • Bridging SAML with other auth systems.
  • Documenting authentication flows for internal teams.

Tools like Apidog can help document, test, and mock APIs that interact with SAML-related endpoints.

How to Implement SAML 2.0

Use this checklist when adding SAML support to your application.

1. Choose the Identity Provider

Common IdPs include:

  • Okta
  • Azure AD
  • Auth0
  • Google Workspace
  • Microsoft 365
  • OneLogin

Your SP must trust the IdP metadata and signing certificate.

2. Configure Your Service Provider

Your application needs to expose or define:

SP Entity ID
ACS URL
SLO URL, if supported
SP metadata URL
Signing certificate, if required
Encryption certificate, if required
Enter fullscreen mode Exit fullscreen mode

The ACS endpoint is especially important because it receives the SAML response.

Example route structure:

GET  /saml/login       Start SAML login
POST /saml/acs         Receive SAML response
GET  /saml/metadata    Return SP metadata
POST /saml/logout      Handle logout, if supported
Enter fullscreen mode Exit fullscreen mode

3. Exchange Metadata

The IdP and SP need each other's configuration.

Typical process:

  1. Export SP metadata from your application.
  2. Import the SP metadata into the IdP.
  3. Export IdP metadata from the IdP.
  4. Import the IdP metadata into your application.
  5. Confirm the Entity IDs, ACS URL, and certificates match.

4. Map User Attributes

Decide which SAML attributes your application expects.

Example mapping:

SAML Attribute Application Field
email User email
firstName First name
lastName Last name
role Application role
department Department

Keep the mapping explicit. Avoid relying on undocumented IdP defaults.

5. Validate Assertions

Your SP should validate at least the following:

  • Signature is valid.
  • Assertion issuer matches the trusted IdP.
  • Audience matches your SP Entity ID.
  • Assertion has not expired.
  • NotBefore and NotOnOrAfter conditions are valid.
  • Destination matches your ACS URL.
  • NameID or required user identifier exists.
  • Replay protection is enforced where applicable.

6. Create an Application Session

After validation, map the SAML identity to an application user.

Typical logic:

samlUser = validateSamlResponse(request.body.SAMLResponse)

user = findUserByEmail(samlUser.email)

if user does not exist:
    user = provisionUser(samlUser)

createSession(user)

redirectToApp()
Enter fullscreen mode Exit fullscreen mode

For enterprise SaaS, decide whether just-in-time provisioning is allowed or whether users must be pre-created.

7. Test the Flow

Test both successful and failed paths:

  • Valid login.
  • Expired assertion.
  • Invalid signature.
  • Wrong audience.
  • Missing required attribute.
  • User not assigned to the app.
  • IdP certificate rotation.
  • Logout behavior, if supported.

Document these flows so developers and security teams know what to expect. Apidog can be used to describe SAML-adjacent endpoints such as login initiation, ACS handling, metadata retrieval, and user provisioning APIs.

Security Considerations

SAML can be secure, but implementation details matter.

Why SAML 2.0 Is Secure

SAML improves security by using:

  • Token-based authentication: The SP does not receive the user's password.
  • Digital signatures: Assertions can be signed to prevent tampering.
  • Encryption: Sensitive assertion data can be encrypted.
  • Short-lived assertions: Limits replay risk.
  • Centralized identity control: Access can be managed through the IdP.

Common SAML Mistakes

Avoid these issues:

  • Not validating assertion signatures.
  • Accepting unsigned assertions.
  • Not checking the audience.
  • Not checking assertion expiration.
  • Trusting attributes without validation.
  • Using outdated SAML libraries.
  • Ignoring IdP certificate rotation.
  • Allowing replayed assertions.
  • Misconfiguring ACS URLs across environments.

A safer baseline:

Require signed responses or signed assertions.
Validate issuer, audience, destination, and time conditions.
Use maintained SAML libraries.
Keep IdP metadata current.
Log SAML failures without exposing sensitive assertion data.
Enter fullscreen mode Exit fullscreen mode

SAML 2.0 and OAuth 2.0 / OpenID Connect

SAML 2.0 is not obsolete. It remains common in enterprise SSO and B2B SaaS integrations.

However, OAuth 2.0 and OpenID Connect are often preferred for:

  • API authorization.
  • Mobile apps.
  • Single-page applications.
  • Modern consumer identity flows.

A practical distinction:

Protocol Primary Use
SAML 2.0 Enterprise browser-based SSO
OAuth 2.0 Delegated authorization
OpenID Connect Authentication built on OAuth 2.0

Some systems bridge SAML and OAuth/OIDC. For example, an enterprise user may authenticate through SAML, while downstream services use OAuth access tokens.

When documenting APIs that sit near these boundaries, keep the contracts clear: which endpoint receives SAML, which service creates the session, and which APIs require tokens.

Practical Example: SSO for a Company Intranet

Scenario: a company intranet acts as the SP, and Okta acts as the IdP.

Flow:

  1. User opens the intranet.
  2. Intranet redirects the user to Okta with a SAML authentication request.
  3. User logs in to Okta.
  4. Okta sends a SAML response to the intranet ACS endpoint.
  5. Intranet validates the assertion.
  6. Intranet maps the user by email.
  7. Intranet creates a session.
  8. User accesses the intranet.

Example endpoint documentation:

GET /saml/login

Description:
Starts an SP-initiated SAML login flow.

Response:
302 Redirect to IdP SSO URL
Enter fullscreen mode Exit fullscreen mode 
POST /saml/acs

Description:
Receives SAMLResponse from the IdP.

Form fields:
- SAMLResponse: Base64-encoded SAML response
- RelayState: Optional state value

Success:
302 Redirect to application home

Failure:
401 Unauthorized or redirect to login error page
Enter fullscreen mode Exit fullscreen mode 
GET /saml/metadata

Description:
Returns SP metadata XML.

Response:
200 application/xml
Enter fullscreen mode Exit fullscreen mode

This is the type of flow you can document in Apidog so backend developers, frontend developers, and security reviewers have a shared reference.

Summary

SAML 2.0 is an XML-based standard for federated authentication and enterprise SSO. It lets an IdP authenticate users and send trusted assertions to an SP.

If you are implementing SAML:

  • Define your SP metadata.
  • Exchange metadata with the IdP.
  • Configure ACS and login endpoints.
  • Map required user attributes.
  • Validate signatures, issuer, audience, destination, and expiration.
  • Test failure cases, not just happy paths.
  • Keep your SAML library and IdP metadata up to date.

For API teams, SAML knowledge is useful even when the protocol is not used directly by APIs. It often sits at the boundary where enterprise identity, user provisioning, session creation, and backend authorization meet.

Frequently Asked Questions

Is SAML 2.0 only for web applications?

SAML 2.0 is most common in browser-based SSO. It can also appear in some API and mobile-adjacent enterprise scenarios, especially in legacy environments.

How does SAML 2.0 compare to OAuth 2.0?

SAML 2.0 focuses on authentication and identity assertions. OAuth 2.0 focuses on delegated authorization and access to protected resources.

Can Apidog help with SAML 2.0 integration?

Yes. Apidog can help teams design, document, mock, and test APIs that interact with SAML-related authentication flows.

Top comments (0)